Orders and Payments - Keystone Commerce API Docs

Order and payment endpoints accept either customer authentication method described in Authentication.

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. Send x-idempotency-key when creating an order or initiating a payment, and reuse a key only to retry the same request.

Orders: the same key with the same order returns the original order instead of creating a second one. The same key with different items, address, alternate phone, coupon, payment mode, delivery method or balance options returns 409 Checkout idempotency key has already been used with a different payload. paymentReturnUrl is not compared.
Payments: while a payment session is active, initiating again returns that same session, whatever the key or body. Once the attempt has ended (for example after abandon), reusing its key returns 409 Payment attempt idempotency key has already been used, so send a new key for each new attempt.

Check shipping serviceability

Check delivery methods and payment options for a cart before checkout. express.available reports courier coverage only. Offer express delivery only when the delivery quote also returns expressDeliveryEnabled: true; otherwise express requests return 400 Express delivery is not available.

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

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/shipping/serviceability \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationPincode": "560001",
    "items": [
      {
        "productId": "<product_id>",
        "quantity": 1
      }
    ]
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "serviceable": true,
    "destinationPincode": "560001",
    "message": "Delivery is available to this pincode.",
    "reasons": [],
    "deliveryOptions": {
      "standard": {
        "available": true,
        "codAvailable": true,
        "serviceType": "B2C SMART EXPRESS",
        "reasons": []
      },
      "express": {
        "available": false,
        "codAvailable": false,
        "serviceType": "B2C PRIORITY",
        "reasons": [
          {
            "code": "EXPRESS_NOT_AVAILABLE",
            "message": "Fast delivery is not available to this pincode."
          }
        ]
      }
    },
    "paymentOptions": {
      "prepaid": {
        "available": true,
        "reasons": []
      },
      "cod": {
        "available": true,
        "reasons": []
      }
    },
    "availableServices": ["B2C SMART EXPRESS", "COD"],
    "checkedAt": "2026-08-05T10:00:00.000Z"
  }
}

Send productVariantId for products with variants. items accepts up to 100 entries.

Get delivery quote

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

Query parameters:

Param	Type	Required	Notes
`cartValue`	number	Yes	Non-negative amount with up to two decimal places
`deliveryMethod`	`STANDARD`, `EXPRESS`	No	Default `STANDARD`

Request:

curl "https://dev-api.keystonecommerce.in/api/v1/delivery/quote?cartValue=250&deliveryMethod=STANDARD" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>"

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "cartValue": "250.00",
    "deliveryCharge": "30.00",
    "configuredDeliveryCharge": "30.00",
    "freeDeliveryThreshold": "299.00",
    "amountRemainingForFreeDelivery": "49.00",
    "isFree": false,
    "deliveryMethod": "STANDARD",
    "expressDeliveryEnabled": true,
    "expressDeliveryCharge": "0.00",
    "configuredExpressDeliveryCharge": "35.00",
    "totalDeliveryCharge": "30.00"
  }
}

Check COD eligibility

Send the cart items to check COD eligibility with the same pricing that checkout uses, including coupons, Reward Points, Wallet Cash, and delivery charges.

Method	Endpoint	Auth
`POST`	`/orders/checkout-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/orders/checkout-quote \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "<product_id>",
        "quantity": 1
      }
    ],
    "pincode": "560001",
    "deliveryMethod": "STANDARD",
    "useRewardPoints": false,
    "useWalletCash": false
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "paymentOptions": {
      "prepaid": {
        "available": true,
        "reasons": []
      },
      "cod": {
        "available": true,
        "reasons": [],
        "collectableAmount": "1019.00",
        "codCharge": "0.00",
        "totalCollectableAmount": "1019.00",
        "limits": {
          "minimumOrderAmount": "0.00",
          "maximumOrderAmount": "5000.00",
          "maxOpenOrdersPerCustomer": 3
        }
      }
    }
  }
}

Request fields:

Field	Required	Notes
`items`	Recommended	1 to 100 items with `productId`, `quantity`, and `productVariantId` for products with variants
`pincode`	Yes	6-digit delivery pincode
`deliveryMethod`	Yes	`STANDARD` or `EXPRESS`
`couponCode`	No	Coupon to apply before checking eligibility
`useRewardPoints`	No	Apply eligible Reward Points. Default `false`
`useWalletCash`	No	Apply available Wallet Cash. Default `false`

totalCollectableAmount is the amount the customer pays on delivery, including codCharge.

Requests without items must send collectableAmount and hasTradeIn instead. This legacy format is deprecated. Use items so Keystone calculates the collectable amount.

List available coupons

Returns the coupons the customer can apply to the cart, sorted by the largest discount first.

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

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/orders/available-coupons \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "subtotal": 1019,
    "items": [
      {
        "productId": "<product_id>",
        "quantity": 1
      }
    ]
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": [
    {
      "code": "WELCOME10",
      "subtotal": 1019,
      "eligibleCartAmount": 1019,
      "discountAmount": 101.9,
      "payableAmount": 917.1
    }
  ]
}

An empty data array means no coupon applies to the cart.

Quote coupon

Checks a coupon code against the cart and returns the discount it applies. Call it when the customer enters a code, then send the same code as couponCode in POST /orders.

Method	Endpoint	Auth
`POST`	`/orders/coupon-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/orders/coupon-quote \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "subtotal": 1019,
    "items": [
      {
        "productId": "<product_id>",
        "quantity": 1
      }
    ]
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "code": "WELCOME10",
    "subtotal": 1019,
    "eligibleCartAmount": 1019,
    "discountAmount": 101.9,
    "payableAmount": 917.1
  }
}

Request fields for both coupon endpoints:

Field	Required	Notes
`code`	Quote only	Letters, numbers, underscores, and hyphens, up to 50 characters. Codes are case-insensitive.
`subtotal`	Yes	Cart value, from `0` with up to two decimal places
`items`	Recommended	1 to 100 items with `productId`, `quantity` from `1` to `1000`, and `productVariantId` for products with variants

When you send items, Keystone prices the cart from its catalog and returns that value as subtotal, ignoring the subtotal you sent. Always send items so the discount matches checkout. eligibleCartAmount is the part of the cart the coupon applies to. A coupon that is invalid, expired, fully used, or not applicable to the cart returns 400 with the reason in message.

Create order

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

Rules:

When shippingAddress.recipientName is not sent, the customer profile must have a non-empty name.
items must contain at least one product.
productVariantId is required for products with variants. Use the variants returned by the product endpoints.
quantity must be an integer from 1 to 9999.
alternatePhone, when sent, must be 10 digits.
paymentReturnUrl, when sent, must be an absolute URL.
couponCode is optional. Check it first with POST /orders/coupon-quote.
shippingAddress.landmark is required.
paymentMode accepts PREPAID or COD. Default PREPAID.
deliveryMethod accepts STANDARD or EXPRESS. Default STANDARD.
useRewardPoints: true applies eligible Reward Points. Default false.
useWalletCash: true applies available Wallet Cash. Default false.
Send the same useRewardPoints and useWalletCash values you used for the quote. POST /wallet/quote defaults both to true, and order creation defaults both to false, so leaving them out gives a different amount.

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "x-idempotency-key: checkout-20260706-001" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "<product_id>",
        "quantity": 1
      }
    ],
    "shippingAddress": {
      "label": "Home",
      "line1": "221B MG Road",
      "line2": "Near Trinity Metro",
      "city": "Bengaluru",
      "state": "Karnataka",
      "pincode": "560001",
      "landmark": "Near Trinity Metro"
    },
    "alternatePhone": "9876543210",
    "paymentMethod": "upi",
    "paymentMode": "PREPAID",
    "deliveryMethod": "STANDARD",
    "paymentReturnUrl": "https://app.example.com/payment/return",
    "useRewardPoints": false,
    "useWalletCash": false
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": "cmr928rlh000702s6a4yh7rls",
    "orderNumber": "KS-20260706-8DEACA50C6",
    "status": "PENDING_PAYMENT",
    "subtotal": "863.56",
    "taxAmount": "155.44",
    "discountAmount": "0",
    "rewardPointsApplied": 0,
    "rewardPointsValue": "0",
    "walletCashApplied": "0",
    "deliveryCharge": "0",
    "expressDeliveryCharge": "0",
    "deliveryMethod": "STANDARD",
    "paymentMode": "PREPAID",
    "externalPaymentAmount": "1019",
    "totalAmount": "1019",
    "items": [
      {
        "id": "cmr928rm7000802s6yxjdfaan",
        "productId": "<product_id>",
        "productName": "10W IPX5 Portable Bluetooth Speaker - 12-Hour Battery",
        "quantity": 1,
        "unitPrice": "1019",
        "totalPrice": "1019"
      }
    ],
    "payment": {
      "id": "cmr928rpo000b02s6yqmjm8he",
      "status": "INITIATED",
      "provider": "cashfree",
      "providerSessionId": "<provider_session_id>"
    },
    "paymentSessionId": "<provider_session_id>",
    "paymentProvider": "cashfree",
    "paymentClientAction": {
      "type": "cashfree_sdk",
      "payload": {
        "environment": "sandbox",
        "orderId": "<provider_order_id>",
        "paymentSessionId": "<provider_session_id>"
      }
    }
  }
}

Use paymentClientAction.type and paymentClientAction.payload to open the configured payment provider SDK. COD and orders with no external payment do not return a provider session.

List orders

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

Query parameters:

Param	Type	Required	Notes
`page`	number	No	Default `1`
`limit`	number	No	Default `20`, max `100`
`status`	`PENDING_PAYMENT`, `PLACED`, `CONFIRMED`, `PACKED`, `SHIPPED`, `OUT_FOR_DELIVERY`, `DELIVERED`, `CANCELLED`	No	Filter by status

Request:

curl "https://dev-api.keystonecommerce.in/api/v1/orders?page=1&limit=5" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>"

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": [
    {
      "id": "cmr928rlh000702s6a4yh7rls",
      "orderNumber": "KS-20260706-8DEACA50C6",
      "status": "PENDING_PAYMENT",
      "totalAmount": "1019"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 5,
    "totalPages": 1
  }
}

Retrieve order

Method	Endpoint	Auth
`GET`	`/orders/{orderId}`	Partner API key + External user ID, or Customer access token + `x-partner-id`

Request:

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

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": "cmr928rlh000702s6a4yh7rls",
    "orderNumber": "KS-20260706-8DEACA50C6",
    "status": "DELIVERED",
    "totalAmount": "1019",
    "items": [
      {
        "id": "cmr928rm7000802s6yxjdfaan",
        "productId": "<product_id>",
        "productName": "10W IPX5 Portable Bluetooth Speaker - 12-Hour Battery",
        "quantity": 1,
        "unitPrice": "1019",
        "totalPrice": "1019"
      }
    ],
    "payment": {
      "id": "cmr928rpo000b02s6yqmjm8he",
      "status": "CAPTURED",
      "provider": "cashfree",
      "providerSessionId": "<provider_session_id>"
    }
  }
}

List order invoices

Returns the invoices for an order. Orders can have a PRODUCT invoice and a DELIVERY invoice.

Method	Endpoint	Auth
`GET`	`/orders/{orderId}/invoices`	Partner API key + External user ID, or Customer access token + `x-partner-id`

Request:

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

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": [
    {
      "type": "PRODUCT",
      "invoiceNumber": "INV-2026-000123",
      "invoiceDate": "2026-07-06T10:00:00.000Z",
      "amount": "1019",
      "status": "SYNCED",
      "available": true,
      "url": "/api/v1/orders/cmr928rlh000702s6a4yh7rls/invoices/PRODUCT/pdf"
    }
  ]
}

available is true when the PDF can be downloaded. Otherwise url is null, and status is PENDING, IN_PROGRESS, or FAILED. Check again later if an invoice is not yet available. An empty array means no invoice has been created for the order yet.

Download order invoice

Returns the invoice PDF. type is PRODUCT or DELIVERY.

Method	Endpoint	Auth
`GET`	`/orders/{orderId}/invoices/{type}/pdf`	Partner API key + External user ID, or Customer access token + `x-partner-id`

Request:

curl https://dev-api.keystonecommerce.in/api/v1/orders/cmr928rlh000702s6a4yh7rls/invoices/PRODUCT/pdf \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -o invoice.pdf

The response is the PDF file with Content-Type: application/pdf, not a JSON envelope. The API returns 404 if the invoice is not ready.

Initiate payment

Order creation initiates payment automatically. Call this endpoint if you need to retry or refresh a provider session for an existing prepaid PENDING_PAYMENT order.

Method	Endpoint	Auth
`POST`	`/payments/orders/{orderId}/initiate`	Partner API key + External user ID, or Customer access token + `x-partner-id`

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/payments/orders/cmr928rlh000702s6a4yh7rls/initiate \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "x-idempotency-key: payment-20260706-001" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "upi",
    "returnUrl": "https://app.example.com/payment/return"
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "payment": {
      "id": "cmr928rpo000b02s6yqmjm8he",
      "orderId": "cmr928rlh000702s6a4yh7rls",
      "amount": "1019",
      "status": "INITIATED",
      "provider": "cashfree",
      "providerSessionId": "<provider_session_id>",
      "method": "upi"
    },
    "provider": "cashfree",
    "providerSessionId": "<provider_session_id>",
    "clientAction": {
      "type": "cashfree_sdk",
      "payload": {
        "environment": "sandbox",
        "orderId": "<provider_order_id>",
        "paymentSessionId": "<provider_session_id>"
      }
    }
  }
}

Use clientAction.type and clientAction.payload to open the configured payment provider SDK.

Abandon payment

Call this endpoint when the customer closes an active provider checkout. The payment moves to USER_DROPPED and can be retried with Initiate payment during the 2-minute grace period. A retry sent within a few seconds of abandoning can return 409 The previous payment session is still closing. Please retry shortly.; wait a few seconds and retry.

Method	Endpoint	Auth
`POST`	`/payments/orders/{orderId}/abandon`	Partner API key + External user ID, or Customer access token + `x-partner-id`

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/payments/orders/cmr928rlh000702s6a4yh7rls/abandon \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>"

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "abandoned": true,
    "status": "USER_DROPPED"
  }
}

Payment statuses:

Status	Meaning
`INITIATED`	Provider session has been created
`PENDING_COLLECTION`	COD payment is awaiting collection
`COLLECTED`	COD payment was collected after delivery
`CAPTURED`	Payment succeeded
`FAILED`	Payment failed
`USER_DROPPED`	Customer dropped from the provider checkout

​Check shipping serviceability

​Get delivery quote

​Check COD eligibility

​List available coupons

​Quote coupon

​Create order

​List orders

​Retrieve order

​List order invoices

​Download order invoice

​Initiate payment

​Abandon payment

Check shipping serviceability

Get delivery quote

Check COD eligibility

List available coupons

Quote coupon

Create order

List orders

Retrieve order

List order invoices

Download order invoice

Initiate payment

Abandon payment