Returns and Support - Keystone Commerce API Docs

Returns and support endpoints accept either customer authentication method described in Authentication. With a Customer access token, ticket and return actions also require x-partner-id; upload URL requests do not.

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.

Evidence upload flow

Upload support and return images with signed URLs:

Request signed URLs from Keystone.
Upload each file with PUT to the returned uploadUrl.
Send the returned publicUrl in imageUrls when creating the ticket or return.

Limits:

Limit	Value
Max files per request	`5`
Max file size	`15 MB` (15,728,640 bytes), checked against the `sizeBytes` you declare
Allowed content types	`image/png`, `image/jpeg`, `image/webp`, `image/gif`
Upload URL TTL	`15 minutes`

Send each file’s sizeBytes when you request upload URLs. Keystone refuses a declared size over the limit, so check the file size before requesting a URL.

Create support upload URLs

Method	Endpoint	Auth
`POST`	`/support/uploads/signed-urls`	Partner API key + External user ID, or Customer access token

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/support/uploads/signed-urls \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "fileName": "damaged-package.jpg",
        "contentType": "image/jpeg",
        "sizeBytes": 102400
      }
    ]
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": [
    {
      "fileName": "damaged-package.jpg",
      "objectName": "support/tickets/cmr928qjc000002s6nh2ufmo2/<generated-file-name>",
      "uploadUrl": "<signed_upload_url>",
      "publicUrl": "https://storage.googleapis.com/keystone-media-dev/support/tickets/cmr928qjc000002s6nh2ufmo2/<generated-file-name>",
      "method": "PUT",
      "headers": {
        "Content-Type": "image/jpeg"
      },
      "expiresAt": "2026-07-06T10:27:32.197Z"
    }
  ]
}

Upload the file:

curl -X PUT "<signed_upload_url>" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@damaged-package.jpg"

Create support ticket

Field	Required	Rules
`topic`	Yes	2 to 120 characters
`detail`	Yes	5 to 5,000 characters
`orderId`	No	An order that belongs to this customer
`imageUrls`	No	Up to 5 `publicUrl` values from the upload flow

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

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/support/tickets \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Delivery issue",
    "detail": "The package arrived damaged.",
    "orderId": "cmr928rlh000702s6a4yh7rls",
    "imageUrls": [
      "https://cdn.example.com/support/damaged-package.jpg"
    ]
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": "cmr928ssp000d02s6f20dle4l",
    "partnerId": "<partner_id>",
    "orderId": "cmr928rlh000702s6a4yh7rls",
    "topic": "Delivery issue",
    "detail": "The package arrived damaged.",
    "imageUrls": [
      "https://cdn.example.com/support/damaged-package.jpg"
    ],
    "status": "OPEN"
  }
}

List support tickets

Method	Endpoint	Auth
`GET`	`/support/tickets`	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`	`OPEN`, `IN_PROGRESS`, `RESOLVED`, `CLOSED`	No	Filter by status

Request:

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

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": [
    {
      "id": "cmr928ssp000d02s6f20dle4l",
      "orderId": "cmr928rlh000702s6a4yh7rls",
      "topic": "Delivery issue",
      "detail": "The package arrived damaged.",
      "status": "OPEN",
      "order": {
        "id": "cmr928rlh000702s6a4yh7rls",
        "orderNumber": "KS-20260706-8DEACA50C6",
        "status": "DELIVERED",
        "totalAmount": "1019"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 1,
    "totalPages": 1
  }
}

Retrieve support ticket

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

Request:

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

Response shape is the same as a single item from the list response.

Create return upload URLs

Method	Endpoint	Auth
`POST`	`/returns/uploads/signed-urls`	Partner API key + External user ID, or Customer access token

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/returns/uploads/signed-urls \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "fileName": "return-evidence.jpg",
        "contentType": "image/jpeg",
        "sizeBytes": 204800
      }
    ]
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": [
    {
      "fileName": "return-evidence.jpg",
      "objectName": "returns/cmr928qjc000002s6nh2ufmo2/<generated-file-name>",
      "uploadUrl": "<signed_upload_url>",
      "publicUrl": "https://storage.googleapis.com/keystone-media-dev/returns/cmr928qjc000002s6nh2ufmo2/<generated-file-name>",
      "method": "PUT",
      "headers": {
        "Content-Type": "image/jpeg"
      },
      "expiresAt": "2026-07-06T10:27:32.417Z"
    }
  ]
}

Create return request

Returns require a delivered order. A prepaid order must also be paid; a COD order qualifies once it is delivered. Each requested quantity must not exceed the item’s remaining returnable quantity.

Field	Required	Rules
`orderId`	Yes	A delivered order that belongs to this customer
`reason`	Yes	2 to 120 characters
`detail`	Yes	5 to 5,000 characters
`requestedResolution`	No	One of the resolutions below. Default `ORIGINAL_PAYMENT_REFUND`
`items`	Yes	1 to 50 items, each with `orderItemId`, `quantity` (1 to 9,999) and an optional `reason` (up to 500 characters)
`imageUrls`	No	Up to 5 `publicUrl` values from the upload flow

COD orders cannot use ORIGINAL_PAYMENT_REFUND. Because it is the default, always send requestedResolution for COD returns, for example WALLET_CREDIT. Resolutions a customer can request:

Resolution	Meaning
`ORIGINAL_PAYMENT_REFUND`	Refund to original payment method
`WALLET_CREDIT`	Credit the customer wallet
`REPLACEMENT`	Request replacement
`KEEP_ITEM_WALLET_CREDIT`	Keep item and request damage credit

For mixed-tender orders, approved returns restore the applicable Reward Points and Wallet Cash. Any remaining original-payment amount is refunded through the payment provider when ORIGINAL_PAYMENT_REFUND is selected.

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

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/returns \
  -H "Authorization: Bearer <access_token>" \
  -H "x-partner-id: <partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "cmr928rlh000702s6a4yh7rls",
    "reason": "Damaged item",
    "detail": "The item was damaged on arrival and cannot be used.",
    "requestedResolution": "ORIGINAL_PAYMENT_REFUND",
    "items": [
      {
        "orderItemId": "cmr928rm7000802s6yxjdfaan",
        "quantity": 1,
        "reason": "Damaged in transit"
      }
    ],
    "imageUrls": [
      "https://cdn.example.com/returns/return-evidence.jpg"
    ]
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "id": "cmr928tj9000e02s6j5rzx13t",
    "partnerId": "<partner_id>",
    "orderId": "cmr928rlh000702s6a4yh7rls",
    "status": "REQUESTED",
    "reason": "Damaged item",
    "detail": "The item was damaged on arrival and cannot be used.",
    "requestedResolution": "ORIGINAL_PAYMENT_REFUND",
    "requestedAmount": "1019",
    "items": [
      {
        "id": "cmr928tk6000f02s6x1z5c60b",
        "orderItemId": "cmr928rm7000802s6yxjdfaan",
        "quantity": 1,
        "reason": "Damaged in transit",
        "requestedAmount": "1019"
      }
    ],
    "refunds": []
  }
}

List returns

Method	Endpoint	Auth
`GET`	`/returns`	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`	return status	No	Filter by status
`resolution`	return resolution	No	Filter by the final `resolution` set when Keystone reviews the return. It is `null` until then, so this does not filter by `requestedResolution`. Final values can also be `NO_REFUND` or `OTHER`.

Return statuses:

REQUESTED
UNDER_REVIEW
NEEDS_INFO
APPROVED
REJECTED
REFUND_PENDING
REFUNDED
REFUND_FAILED
RESOLVED

Request:

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

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": [
    {
      "id": "cmr928tj9000e02s6j5rzx13t",
      "orderId": "cmr928rlh000702s6a4yh7rls",
      "status": "REQUESTED",
      "reason": "Damaged item",
      "requestedResolution": "ORIGINAL_PAYMENT_REFUND",
      "requestedAmount": "1019"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 1,
    "totalPages": 1
  }
}

Retrieve return

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

Request:

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

Response shape is the same as the create return response.

​Evidence upload flow

​Create support upload URLs

​Create support ticket

​List support tickets

​Retrieve support ticket

​Create return upload URLs

​Create return request

​List returns

​Retrieve return

Evidence upload flow

Create support upload URLs

Create support ticket

List support tickets

Retrieve support ticket

Create return upload URLs

Create return request

List returns

Retrieve return