Wallet, Referrals, and Promotions - Keystone Commerce API Docs

The wallet summary and wallet quote endpoints accept either customer authentication method described in Authentication. Referral and promotion endpoints require a Customer access token and x-partner-id.

x-api-key: <api_key>
x-external-user-id: <external_user_id>

Authorization: Bearer <access_token>
x-partner-id: <partner_id>

Examples on this page use a Customer access token. With the Partner API key and External user ID method, replace the Authorization and x-partner-id headers with x-api-key and x-external-user-id. Reward Points and Wallet Cash are separate balances:

Balance	Unit	Checkout behavior
Reward Points	Points	Apply as an order discount before delivery eligibility is calculated
Wallet Cash	INR	Apply as payment after product and delivery charges are calculated

Quote wallet usage

Use this endpoint to calculate Reward Points, Wallet Cash, delivery charges, and the remaining payable amount before checkout.

Method	Endpoint	Auth
`POST`	`/wallet/quote`	Partner API key + External user ID, or Customer access token + `x-partner-id`

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/wallet/quote \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "cartValue": 750,
    "useRewardPoints": true,
    "useWalletCash": true,
    "deliveryMethod": "STANDARD"
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "enabled": true,
    "cartValue": "750.00",
    "deliveryEligibleCartValue": "700.00",
    "rewardPoints": {
      "available": 100,
      "reserved": 0,
      "pending": 0,
      "eligible": 50,
      "applied": 50,
      "remaining": 50,
      "nextEligibleCartValue": "1000.00",
      "earliestExpiry": "2026-09-30T00:00:00.000Z",
      "rule": {
        "id": "cmwallet-rule-001",
        "minCartValue": "500.00",
        "maxRewardPoints": 50
      }
    },
    "walletCash": {
      "available": "200.00",
      "reserved": "0.00",
      "applied": "200.00",
      "remaining": "0.00"
    },
    "delivery": {
      "cartValue": "700.00",
      "deliveryCharge": "0.00",
      "configuredDeliveryCharge": "30.00",
      "freeDeliveryThreshold": "299.00",
      "amountRemainingForFreeDelivery": "0.00",
      "isFree": true,
      "deliveryMethod": "STANDARD",
      "expressDeliveryEnabled": true,
      "expressDeliveryCharge": "0.00",
      "configuredExpressDeliveryCharge": "35.00",
      "totalDeliveryCharge": "0.00"
    },
    "remainingPayable": "500.00"
  }
}

useRewardPoints and useWalletCash default to true here but to false in POST /orders, so send both explicitly. deliveryMethod defaults to STANDARD. Send deliveryEligibilityCartValue when the cart value for delivery eligibility differs from cartValue. It defaults to cartValue, and Keystone subtracts applied Reward Points from it before checking free delivery.

Get wallet

Returns both balances, recent transactions, and active Reward Point rules. Send cartValue to include a checkout quote.

Method	Endpoint	Auth
`GET`	`/wallet?cartValue={amount}`	Partner API key + External user ID, or Customer access token + `x-partner-id`

Request:

curl "https://dev-api.keystonecommerce.in/api/v1/wallet?cartValue=750" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>"

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "balances": {
      "walletCash": {
        "available": "200.00",
        "reserved": "0.00"
      },
      "rewardPoints": {
        "available": 100,
        "reserved": 0,
        "pending": 0,
        "earliestExpiry": "2026-09-30T00:00:00.000Z"
      }
    },
    "transactions": [],
    "discountRules": [
      {
        "id": "cmwallet-rule-001",
        "cartValue": "500.00",
        "maxRewardPoints": 50
      }
    ],
    "quote": {
      "enabled": true,
      "cartValue": "750.00",
      "deliveryEligibleCartValue": "700.00",
      "rewardPoints": {
        "available": 100,
        "reserved": 0,
        "pending": 0,
        "eligible": 50,
        "applied": 50,
        "remaining": 50,
        "nextEligibleCartValue": "1000.00",
        "earliestExpiry": "2026-09-30T00:00:00.000Z",
        "rule": {
          "id": "cmwallet-rule-001",
          "minCartValue": "500.00",
          "maxRewardPoints": 50
        }
      },
      "walletCash": {
        "available": "200.00",
        "reserved": "0.00",
        "applied": "200.00",
        "remaining": "0.00"
      },
      "delivery": {
        "cartValue": "700.00",
        "deliveryCharge": "0.00",
        "configuredDeliveryCharge": "30.00",
        "freeDeliveryThreshold": "299.00",
        "amountRemainingForFreeDelivery": "0.00",
        "isFree": true,
        "deliveryMethod": "STANDARD",
        "expressDeliveryEnabled": true,
        "expressDeliveryCharge": "0.00",
        "configuredExpressDeliveryCharge": "35.00",
        "totalDeliveryCharge": "0.00"
      },
      "remainingPayable": "500.00"
    }
  }
}

To apply balances during checkout, send useRewardPoints: true or useWalletCash: true in POST /orders.

Get referral details

Method	Endpoint	Auth
`GET`	`/referrals/me`	Customer access token + `x-partner-id`

Request:

curl https://dev-api.keystonecommerce.in/api/v1/referrals/me \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>"

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "code": "AARAV100",
    "shareUrl": "https://app.example.com/referral/AARAV100",
    "program": {
      "isEnabled": true,
      "referrerRewardPoints": 100,
      "inviteeRewardPoints": 50,
      "rewardExpiryDays": 60,
      "validUntil": null
    },
    "stats": {
      "invited": 2,
      "rewarded": 2,
      "earnedPoints": 200
    }
  }
}

shareUrl is null while the referral program is off (program.isEnabled: false).

Redeem wallet promotion

Each customer can redeem a promotion code once. Successful redemptions credit Reward Points.

Method	Endpoint	Auth
`POST`	`/wallet/promotions/redeem`	Customer access token + `x-partner-id`

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/wallet/promotions/redeem \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{"code":"WELCOME100"}'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "promotion": {
      "code": "WELCOME100",
      "name": "Welcome reward",
      "rewardPoints": 100
    },
    "redemption": {
      "id": "cmpromotion-redemption-001",
      "promotionId": "cmpromotion-001",
      "userId": "cmr928qjc000002s6nh2ufmo2",
      "walletTransactionId": "cmwallet-transaction-001",
      "redeemedAt": "2026-08-05T10:00:00.000Z"
    },
    "walletTransaction": {
      "id": "cmwallet-transaction-001",
      "bucket": "REWARD_POINTS",
      "type": "CREDIT",
      "source": "PROMOTION",
      "amount": "100",
      "expiresAt": "2026-10-04T10:00:00.000Z"
    }
  }
}

​Quote wallet usage

​Get wallet

​Get referral details

​Redeem wallet promotion

Quote wallet usage

Get wallet

Get referral details

Redeem wallet promotion