Orders and Payments - Keystone Commerce API Docs

Order and payment endpoints require a Customer access token and x-partner-id.

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

Send x-idempotency-key when creating an order or initiating a payment. Reuse the key only when retrying the same request; changing the payload returns a conflict.

Check shipping serviceability

Check delivery methods and payment options for a cart before checkout.

Method	Endpoint	Auth
`POST`	`/shipping/serviceability`	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": "prod_key064",
        "quantity": 1
      }
    ]
  }'

Response:

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

Get delivery quote

Method	Endpoint	Auth
`GET`	`/delivery/quote`	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

Use remainingPayable from POST /wallet/quote as collectableAmount.

Method	Endpoint	Auth
`POST`	`/orders/checkout-quote`	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 '{
    "collectableAmount": 1019,
    "pincode": "560001",
    "deliveryMethod": "STANDARD",
    "hasTradeIn": false
  }'

Response:

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

Create order

Method	Endpoint	Auth
`POST`	`/orders`	Customer access token + `x-partner-id`

Rules:

The customer profile must have a non-empty name.
items must contain at least one product.
quantity must be an integer from 1 to 9999.
alternatePhone, when sent, must be a 10-digit Indian mobile number.
paymentReturnUrl, when sent, must be an absolute URL.
couponCode is optional and must be issued for the partner.
shippingAddress.landmark is required.
paymentMode accepts PREPAID or COD. Default PREPAID.
deliveryMethod accepts STANDARD or EXPRESS. Default STANDARD.
useRewardPoints: true applies eligible Reward Points.
useWalletCash: true applies available Wallet Cash.

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

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`	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": 201,
  "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 during the reservation grace period.

Method	Endpoint	Auth
`POST`	`/payments/orders/{orderId}/abandon`	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": 201,
  "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

​Create order

​List orders

​Retrieve order

​Initiate payment

​Abandon payment

Check shipping serviceability

Get delivery quote

Check COD eligibility

Create order

List orders

Retrieve order

Initiate payment

Abandon payment