Wallet, Referrals, and Promotions - Keystone Commerce API Docs

Wallet, referral, and promotion endpoints require a Customer access token and x-partner-id.

Authorization: Bearer <access_token>
x-partner-id: <partner_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`	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": 201,
  "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. deliveryMethod defaults to STANDARD.

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}`	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
    }
  }
}

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": 201,
  "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