Get Cart Promotion Details using Code & Promotion mode

get

https://{host}/api_gateway/v1/promotions/code

This API can be used to fetch the Cart promotion details using the cart promotion code and the cart promotion mode.

Note: At present, the API to fetch cart promotion codes for existing code linked cart promotion is not available, you can download the generated code list via the "Manage Promo Codes" settings on the cart promotions listing page in the UI.

Example request

curl --location 'https://{Host}/api_gateway/v1/promotions/code?codes=DQCV73&mode=DISCOUNT' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--data ''

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

Resource information


Pagination	No
Batch support	No

Rate limit

Demo and Testing Clusters: 1,000 requests per minute per API key
Other Organizations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

Query parameters

Field	Type	Required	Description
codes	String	Yes	Defines the cart promotion code using which you want to retrieve the cart promotion details.
mode	String	Yes	Defines the mode of cart promotion applied Supported values: `DISCOUNT`, `PAYMENT_VOUCHER`.
includeRedemptions	Boolean	Optional	If true, includes redemption details for the codes.

Example response

{
    "data": [
        {
            "id": "68fb18d331d91c625a8d9e52",
            "orgId": 100458,
            "promotionId": "68fb18a431d91c625a8d9e51",
            "promotionName": "eratg",
            "code": "DQCV73",
            "customerId": 566881933,
            "active": true,
            "createdOn": 1761286355257,
            "createdOnISO": "2025-10-24T06:12:35Z",
            "validTill": 1763787599999,
            "validTillISO": "2025-11-22T04:59:59Z",
            "mode": "DISCOUNT",
            "redeemableFrom": 1761286355257,
            "redeemableFromISO": "2025-10-24T06:12:35Z"
        }
    ]
}

Response parameters

Field	Type	Description
data	Array	Defines a list of cart promotion code objects.
..id	String	Specifies the unique identifier for the cart promotion code record.
..orgId	Number	Specifies the Organization ID.
..promotionId	String	Specifies the ID of the cart promotion meta this code belongs to.
..promotionName	String	Specifies the name of the cart promotion.
..code	String	Specifies the cart promotion code itself.
..customerId	Number	Specifies the customer ID this code is linked to.
..active	Boolean	Indicates whether the code is currently active.
..createdOn	Number	Indicates the timestamp f when the code was created in UTC. Time format: Epoch milliseconds
..createdOnISO	String	Specifies the ISO 8601 timestamp of when the code was created in UTC.
..validTill	Number	Indicates the timestamp of when the code expires in UTC. Time format : Epoch milliseconds
..validTillISO	String	Specifies the ISO 8601 timestamp of when the code expires in UTC.
..mode	String	Specifies the cart promotion mode.
..redeemableFrom	Number	Indicates the timestamp from when the code is redeemable. Time format: Epoch milliseconds
..redeemableFromISO	String	Specifies the ISO 8601 timestamp from when the code is redeemable in UTC.

Error codes

Code	Description
400	Invalid request. Check required parameters. Ensure all required parameters are provided and valid.
902	Code provided is non alpha numeric. Special characters are not allowed. Provide an alphanumeric code value.
903	Code length should be greater than 5. Ensure the code meets the minimum length requirement.
904	Code length should be less than 40. Shorten the code to be under 40 characters.
905	Code should be in upper case only. Use only uppercase letters for the code.
1001	Invalid code. Provide a valid and existing code.
1002	Code has expired. Use a non-expired code.
1004	Code has been already redeemed. Use a code that has not already been redeemed.
1005	Code linked to another customer. Provide a code that is not already linked.
1006	Invalid customer identifier. Provide a valid customer identifier.
1007	Error while fetching customer identifier. Retry after checking the customer identifier details and service status.
1008	Org not enabled for redemption without cart evaluation. Enable the feature or perform cart evaluation as required.
1009	Validation failure for redemption without cart evaluation. Check your request for all needed validation compliance.
500	Internal server error. Retry after a short delay, and contact support if the error persists.

Language

Credentials

Basic

base64

URL

Click Try It! to start a request and see the response here!