Returns and Support - Keystone Commerce API Docs

Returns and support endpoints require a Customer access token. Ticket and return actions also require x-partner-id.

Authorization: Bearer <access_token>
x-partner-id: <partner_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`
Allowed content types	`image/png`, `image/jpeg`, `image/webp`, `image/gif`
Upload URL TTL	About `15 minutes`

Create support upload URLs

Method	Endpoint	Auth
`POST`	`/support/uploads/signed-urls`	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": 201,
  "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

Method	Endpoint	Auth
`POST`	`/support/tickets`	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": 201,
  "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`	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
`search`	string	No	Search ticket text or order number

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}`	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`	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": 201,
  "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, paid order. Each requested quantity must not exceed the item’s remaining returnable quantity. COD orders cannot use ORIGINAL_PAYMENT_REFUND. Select another available resolution for COD returns. Allowed resolutions:

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`	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": 201,
  "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`	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 resolution
`search`	string	No	Search return fields

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