Redeem Cart Promotion

post

https://{host}/api_gateway/v1/promotions/redemptions#

This API defines the endpoint for saving or applying a cart promotion that a customer used during a purchase. It specifies the method to record the details of the transaction, such as the customer information, the items bought, the discount received, and how the cart promotion was applied.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/redemptions' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-AUTH-ORG-ID: 4000004' \
--header 'Authorization: Basic bmFtYW5fZG9jgyMzA3MWJmYjM5OGM5ZmM2YjZlY2I2MmEy' \
--header 'Cookie: _cfuvid=uvNcgoyanbmZMCVkA64njE4pSA_tJw1wkWo-1762160764633-0.0.1.1-604800000' \
--data '{
  "customerIdentifierValue" : "1234512345", 
  "customerIdentifierType" : "mobile",
  "customerId" : "566881933",
  "transactionIdentifier" : "txn-50",
  "transactionNumber" : "txn-50",
   "transactionDate":1743521508000, 
   "amount":1000,
   "lineItems" : [
    {
        "sku":"Sku#Fuel", 
        "promotionId":"67e3c1073919452f135e2da0",  
        "earnedPromotionId":"67e63559e1c34e7d8e9348aa", 
        "redemptionCount":1,
        "discount":500,
        "discountAppliedOnQuantity":1,
        "promotionAppliedOnQuantity":1
     }
   ],
   "redemptions" : [
      {
        "sku":"Sku#Fuel", 
        "promotionId":"67e3c1073919452f135e2da0",  
        "redemptionCount":1,
        "discount":500,
        "discountAppliedOnQuantity":1,
        "promotionAppliedOnQuantity":1
     }
   ]
}'

Prerequisites

Authentication: Basic or OAuth authentication
Access group resource: Write access to customer group resource

Rate limit

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

Body parameters

Field	Type	Required	Description
customerIdentifierValue	String	Conditional	Specifies the value used to identify the customer, such as their mobile number. Required if customerId is not provided.
customerIdentifierType	String	Conditional	Specifies the type of identifier used. Required if customerId is not provided.
customerId	String	Conditional	Specifies the Unique Identifier of the customer. Note : One of customerId or the identifier pair is required.
transactionIdentifier	String	Yes	Specifies the unique ID for the transaction. Supports a max of 250 characters.
transactionNumber	String	Yes	Specifies the customer-facing bill or receipt number. Supports a max of 250 characters.
transactionDate	Integer	Yes	Specifies the time of the transaction in UTC. Time format : milliseconds since epoch.
amount	Integer	Yes	Specifies the total amount of the transaction before any discount.
lineItems	Array	Conditional	Defines the details of the items purchased. At least one of lineItems or redemptions must be specified.
.sku	String	Optional	Specifies the unique identifier for the product (SKU) to which the cart promotion is applied.
.promotionId	String	Yes	Specifies the Unique Identifier of the cart promotion being redeemed or applied to the item.
.earnedPromotionId	String	Optional	Specifies the Unique Identifier of the previously earned cart promotion being redeemed.
.redemptionCount	Integer	Yes	Specifies the number of times this cart promotion is being redeemed for the item.
.discount	Integer	Yes	Specifies the monetary value of the discount applied.
.discountAppliedOnQuantity	Integer	Yes	Specifies the number of item units on which the discount was actually applied.
.promotionAppliedOnQuantity	Integer	Yes	Specifies the quantity of the item that was eligible for the cart promotion.
redemptions	Array	Conditional	Details about the cart promotions redeemed. You must specify at least one of the lineItems or redemptions.
.sku	String	Optional	Specifies the product SKU for which the cart promotion is being redeemed.
.promotionId	String	Yes	Specifies the unique identifier of the cart promotion that is being redeemed.
.redemptionCount	Integer	Yes	Specifies the number of times this cart promotion needs to be redeemed for the item.
.discount	Integer	Yes	Specifies the discount amount applied as part of the redemption.
.discountAppliedOnQuantity	Integer	Yes	Specifies the quantity of the item on which the discount is applied.
.promotionAppliedOnQuantity	Integer	Yes	Specifies the quantity of the item on which the discount was is applied.

Example response

{
    "data": {
        "orgId": 100737,
        "customerIdentifierValue": "1234512345",
        "customerIdentifierType": "mobile",
        "customerId": 566881933,
        "transactionIdentifier": "txn-50",
        "transactionNumber": "txn-50",
        "transactionDate": 1743521508000,
        "transactionDateISO": "2025-04-01T15:31:48Z",
        "amount": 1000.0,
        "redemptions": [
            {
                "promotionId": "67e3c1073919452f135e2da0",
                "redemptionCount": 1,
                "discount": "500.000000",
                "discountAppliedOnQuantity": "1.000000",
                "promotionAppliedOnQuantity": "1.000000"
            }
        ],
        "lineItems": [
            {
                "sku": "Sku#Fuel",
                "promotionId": "67e3c1073919452f135e2da0",
                "earnedPromotionId": "67e63559e1c34e7d8e9348aa",
                "redemptionCount": 1,
                "discount": "500.000000",
                "discountAppliedOnQuantity": "1.000000",
                "promotionAppliedOnQuantity": "1.000000"
            }
        ]
    }
}

Response parameters

Field	Type	Description
data	Object	Defines the object that contains the details of the processed redemption.
.orgId	Integer	Specifies the Unique Identifier of your organization.
.customerIdentifierValue	String	Specifies the value used to identify the customer.
.customerIdentifierType	String	Specifies the type of identifier provided.
.customerId	Integer	Specifies the Unique Identifier of the customer.
.transactionIdentifier	String	Specifies the Unique Identifier used to track transaction.
.transactionNumber	String	Specifies the visible transaction number.
.transactionDate	Integer	Indicates the timestamp of the transaction in milliseconds since epoch.
.amount	Integer	Specifies the total transaction amount before applying discounts.
.redemptions	Array	Defines the redemptions array that contains details about the cart promotions that were redeemed.
..promotionId	String	Specifies the unique identifier of the cart promotion that is being redeemed.
..redemptionCount	Integer	Indicates the number of times this cart promotion is being redeemed for the item.
..discount	String	Specifies the discount amount applied as part of the redemption.
..discountAppliedOnQuantity	String	Indicates the quantity of the item on which the discount was actually applied.
..promotionAppliedOnQuantity	String	Indicates the quantity of the item that was eligible for the cart promotion.
.lineItems	Array	Defines the details of the items purchased in the transaction.
..sku	String	Specifies the unique identifier for the product (SKU).
..promotionId	String	Specifies the unique identifier of the cart promotion that is being redeemed.
..earnedPromotionId	String	Specifies the Unique Identifier of the previously earned cart promotion being redeemed.
..redemptionCount	Integer	Indicates the number of times this cart promotion is being redeemed for the item.
..discount	String	Specifies the discount amount applied as part of the redemption.
..discountAppliedOnQuantity	String	Indicates the quantity of the item on which the discount was actually applied.
..promotionAppliedOnQuantity	String	Indicates the quantity of the item on which the discount was actually applied.

Error codes

Error Code	Description	Reason
400	Bad Request	Indicates at least lineItems or redemptions must be specified
400	Bad Request	Indicates CustomerIdentifierType and CustomerIdentifierValue is mandatory when customerId is not specified.

Language

Credentials

Basic

base64

URL

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