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

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.
transactionDateISO	String	Conditional	Specifies the time of the transaction in UTC, returned in the server time zone. EU server example 1738661445000 (UTC) → 04 February 2026, 09:30:45 (UTC) India server example 1738661445000 (+05:30) → 04 February 2026, 15:00:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
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

Code	Description
400	Invalid request. Check required parameters. Ensure all required parameters are provided and valid.
404	Passed promotion, redemption, or evaluation ID not found. Use a valid and existing promotion, redemption, or evaluation ID.
405	Org not enabled for redemption without cart evaluation. Enable this feature for your org or perform cart evaluation.
406	Web engage account Id is not valid for this org. Verify and update your web engage account ID for this org.
500	Internal server error. Retry the request after a short delay, and contact support if the error persists.
521	Could not acquire the lock on the resource. Retry after some time or resolve resource contention.