Update Cart Promotion

get https://{host}/api_gateway/v1/promotions/{PromotionID}

This endpoint allows you to update cart promotion details.

Example request

curl --location --request PUT 'https://{host}/api_gateway/v1/promotions/68c38794aa0d7cbb06ac' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-AUTH-ORG-ID: 100232' \
--header 'user-agent: pyapps_auto_Promotion_Engine_Eucrm_Smoke' \
--header 'Authorization: Basic bmFtYW5fZG9jOmEzYjRjYjgyMzA3MWJmYjM5OGM5ZmM2YjZlY2I2MmEy' \
--data '{
    "name": "CODE_Promotion_Test_17573886",
    "orgId": 100027,
    "priority": 0,
    "active": true,
    "messageLabel": "test!!",
    "type": "CODE",
    "condition": {
      "type": "CART",
      "cartCondition": {
        "kpi": "SUBTOTAL",
        "operator": "EQUALS",
        "value": 250.0
      }
    },
    "action": {
      "type": "CART_BASED",
      "cartBasedAction": {
        "type": "ABSOLUTE",
        "value": 25.0
      }
    },
    "createdBy": 70707,
    "createdOn": 0,
    "lastUpdatedBy": 70707,
    "startDate": "1857388651000",
    "endDate": "1857475051000",
    "campaignId": 39077,
    "mode": "DISCOUNT",
    "promotionRestrictions": {
      "Code": [
        {
          "kpi": "REDEMPTION",
          "limit": 1
        }
      ]
    },
    "isStackable": false
  }'

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

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.

Path parameters

Field	Type	Required	Description
Promotion id	String	Yes	Indicates the unique identifier of the promotion. This is returned in the `data.id` field of the promotion payload during promotion creation.

Body parameters

Field	Type	Required	Description
name	String	Yes	Indicates a unique name of the promotion. Character limit : 1-50.
priority	Integer	Yes	Specifies the order in which promotions are applied. Lower numbers have higher priority. By default, the priority value is `0`. Promotions with priority `0` are applied first. Example If there are three promotions—A (priority 0), B (priority 1), and C (priority 2) The order of application will be: Promotion A(priority 0) Promotion A (priority 1) Promotion C (priority 2) <br /> Note: If `customerActivationRequired` is enabled for a promotio, the customer must activate it. In this case, the priority order does not apply.
active	Boolean	Yes	Indicates if the promotion is active. Supported values are `true` and `false`.
messageLabel	String	Yes	Specifies a label for the promotion message. There is no character limit set for labels. Example: `SummerSale2025`
type	Enum	Yes	Specifies the type of promotion. Supported values are: `POS` (Point of Sale): Applies automatically at checkout when cart or purchase conditions are met. No code or customer action is required. `CODE`: Requires the customer to enter a promotion code for redemption. `CUSTOMER`: Targets specific customer segments or individuals based on attributes or behaviour. Applies automatically when criteria are met. `EARNING`: Grants rewards (such as points or benefits) when earning conditions are fulfilled. `REWARD`: Offers a direct reward, such as a discount or complimentary item, upon meeting specific conditions.
.condition	Object	Yes	Specifies the rules that determine how the promotion applies. Conditions can be based on factors such as cart subtotal or on the type of items in the cart.
..type	Enum	Yes	Specifies the type of condition used to evaluate a promotion. Supported values are: `CART`: Conditions based on the entire shopping cart. Example: “Receive free shipping when you buy 5 or more items.” `ITEM`: Conditions based on individual items in the cart. Example: “Get 20% off laptops priced over $800.”
..cartCondition	Object	Conditional	Defines rules that apply to the entire shopping cart. This object is required when `condition.type` is set to `CART`. Example Cart subtotal GREATER_THAN 500 Total item count EQUALS 3
....kpi	Enum	Yes	Specifies the metric used to evaluate the cart condition. Supported values are: `SUBTOTAL`: The total price of all items in the cart. `TOTAL_QUANTITY`: The sum of quantities of all items in the cart. `ITEM_COUNT`: The count of unique items in the cart. Examples `SUBTOTAL GREATER_THAN 500` Apply promotion if the cart total exceeds $500. Business example: “Spend more than $500 and get free shipping.” `TOTAL_QUANTITY EQUALS 3` Apply promotion if the cart has exactly 3 items (regardless of type). Business example: “Buy any 3 products and get 10% off.” `TOTAL_ITEMS GREATER_THAN_OR_EQUALS 2` Apply promotion if the cart contains 2 or more unique products. Business example: “Purchase 2 different categories of items and receive a free gift.”
....operator	Enum	Yes	Specifies the comparison operator used for the cart condition. Supported values: `EQUALS` `GREATER_THAN` `LESS_THAN` `GREATER_THAN_OR_EQUALS` `LESS_THAN_OR_EQUALS` Examples `TOTAL_QUANTITY EQUALS 3` “Apply the promotion if the cart has exactly 3 items.” `SUBTOTAL GREATER_THAN 500` “Apply the promotion if the cart total exceeds $500.” `TOTAL_ITEMS LESS_THAN_OR_EQUALS 1` “Apply the promotion if the cart has only 1 unique product.”
....value	Number	Yes	Specifies the number to compare against for the cart condition. The value can be an integer or a decimal. Examples `SUBTOTAL GREATER_THAN_OR_EQUALS 250` “Apply the promotion if the cart subtotal is $250 or more.” `TOTAL_QUANTITY EQUALS 3` “Apply the promotion if the cart has exactly 3 items.” `SUBTOTAL LESS_THAN 100.50` “Apply the promotion if the cart subtotal is less than $100.50.”.
action	Object	Yes	Specifies what happens when the promotion is applied. The action defines the scope of the discount or reward. Example If `action.type` = `CART_BASED` The promotion applies to the entire cart. If `action.type` =`ITEM_BASED` The promotion applies only to specific items.
..type	Enum	Yes	Specifies the scope of the action when the promotion is applied. Supported values: `CART_BASED`: Applies to the entire cart. Example: “Get 10% off the total cart value when you spend $500 or more.” `ITEM_BASED`: Applies to specific items in the cart. Example: “Buy any 2 shirts and get 1 free.”
..cartBasedAction	Object	Conditional	Defines the action that applies to the entire shopping cart. Use this when `actionType` is set to `CART_BASED`. Examples “15% discount on the total cart amount.” “$50 off when the cart subtotal is $500 or more.”
....type	Enum	Yes	Specifies the type of cart-based action. Supported values: `ABSOLUTE`: A fixed monetary discount. Example: “Get $100 off purchases above $600.” `PERCENTAGE`: A percentage discount on the cart total. Example: “Get 20% off purchases above $1,000.”
....value	Number	Yes	Specifies the value for the cart-based action. This can be an integer or a decimal, depending on the action type. For ABSOLUTE, the value is a currency amount. Example: `100` → “$100 discount.” For PERCENTAGE, the value is a percentage. Example: `20` → “20% discount.”
startDate	Long	Yes	Specifies the date and time when the promotion becomes active. The value is expressed as a Unix epoch timestamp in milliseconds (UTC). Example `1757388651000` corresponds to 2025-09-12 06:30:51 UTC
endDate	Long	Yes	Specifies the end date and time when the promotion was created. The value is expressed as a Unix epoch timestamp in milliseconds (UTC). Example `1726123456789` corresponds to 2024-09-12 10:24:16 UTC
campaignId	Long	Yes	Specifies the unique identifier of the campaign that the promotion is linked to. Example If a promotion belongs to the “Holiday Sale 2025” campaign with ID `12345`, then `campaignId` = `12345`.
mode	Enum	Yes	Specifies how the promotion is applied. Supported values: `DISCOUNT`: Provides a direct monetary reduction in the current purchase. Example: “Spend $100 and get $20 off instantly.” `PAYMENT_VOUCHER`: Issues a voucher that the customer can redeem on a future purchase. Example: “Spend $100 and receive a $20 voucher for your next order.”
.promotionRestrictions	Object	Optional	Defines the limitations applied to the promotion, if any. Restrictions are grouped by level, which specifies where the restriction applies. Supported levels include: `CODE`: Restricts usage to specific promotion codes. `CUSTOMER`: Restricts eligibility to certain customers or segments. `CART`: Restricts based on cart conditions (e.g., minimum subtotal). `EARN`: Restricts how rewards are earned. `PROMOTION`: Restricts promotion usage or stacking with other promotions.
..Code	Array of Objects	Optional	Specifies restrictions that apply to promotion codes. This is an array of objects, where each object defines a key performance indicator (KPI) and its limit.
....kpi	Enum	Yes	Specifies the metric used to apply the restriction. Supported values: `REDEMPTION`: Limits how many times a specific promotion can be redeemed. Example: A promotion code with a `REDEMPTION` limit of 1 per customer: “Each customer can use this code only once.” `TRANSACTION`: Limits the number of transactions in which a promotion can be applied. Example: A “first-time buyer” promotion with a `TRANSACTION` limit of 1: “The promotion applies only on the customer’s first purchase.” `DISCOUNT`: Caps the total monetary value of the discount a promotion can provide. Example: A “10% off” promotion with a `DISCOUNT` limit of 50 : “Even if 10% of the order is $100, the customer receives only $50 off.”
....limit	Number	Yes	Specifies the maximum allowed value for the restriction. Must be a positive integer. Examples `REDEMPTION limit = 1` : A customer can redeem the promotion only once. `TRANSACTION limit = 1` : The promotion applies only to the customer’s first purchase. `DISCOUNT limit = 50`: The maximum discount a customer can receive is $50. .
isStackable	Boolean	Yes	Indicates whether this promotion can be used together with other promotions. Supported values: `true`, `false` Default: `false` (if not specified) Examples `true` → “This promotion can be combined with other active promotions.” `false` → “This promotion cannot be combined with any other promotion.”

Example response

{
    "data": {
        "id": "68c38794aa0d7a770cbb06ac",
        "name": "CODE_Promotion_Test_17573886",
        "orgId": 100737,
        "priority": 0,
        "active": true,
        "messageLabel": "test!!",
        "type": "CODE",
        "condition": {
            "type": "CART",
            "cartCondition": {
                "kpi": "SUBTOTAL",
                "operator": "EQUALS",
                "value": "250.000000"
            }
        },
        "action": {
            "type": "CART_BASED",
            "cartBasedAction": {
                "type": "ABSOLUTE",
                "value": "25.000000"
            }
        },
        "createdBy": 75152721,
        "createdOn": 1757644692081,
        "lastUpdatedBy": 75152721,
        "lastUpdatedOn": 1757661962770,
        "startDate": 1857388651000,
        "endDate": 1857475051000,
        "campaignId": 39077,
        "promotionRestrictions": {
            "Code": [
                {
                    "kpi": "REDEMPTION",
                    "limit": "1.000000"
                }
            ]
        },
        "earnLimitedToSpecificAudience": false,
        "mode": "DISCOUNT",
        "maxIssuancePerCustomer": 1,
        "isStackable": false,
        "expiryDateChangeJobList": [
            {
                "jobType": "CODE",
                "status": "OPEN",
                "createdOn": 1757661962776,
                "lastUpdatedOn": 1757661962776,
                "lastUpdatedBy": 75152721,
                "createdBy": 75152721,
                "message": "Changed to 'Expire on 2028-11-10T13:17:31Z' from 'Expire on 2025-09-10T03:30:51Z'",
                "requestId": "52b0047103d9cbd8ef300d6a0be9fc94"
            }
        ]
    }
}

Response parameters

Field	Type	Description
data	Object	The main container object for the promotion details.
..id	String	Indicates the unique identifier assigned to the promotion by the system.
..name	String	The name of the promotion.
..orgId	Number	Indicates the organization ID this promotion is associated with..
..priority	Number	The priority of the promotion. A higher number indicates higher priority. Defaults to 0 if not explicitly set during creation.
..active	Boolean	Indicates if the promotion is active.
..messageLabel	String	Indicates the label for the promotion message.
..type	String	The type of promotion. Possible values: POS, CODE, CUSTOMER, EARNING, REWARD.
..condition	Object	Defines the conditions under which the promotion applies.
....type	String	Indicates the type of condition. Possible values: CART, ITEM.
....cartCondition	Object	Specifies conditions related to the shopping cart. Present if data.condition.type is CART.
......kpi	String	The Key Performance Indicator for the cart condition. Possible values: SUBTOTAL, TOTAL_QUANTITY, TOTAL_ITEMS.
......operator	String	The operator to use for the cart condition comparison. Possible values: EQUALS, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUALS, LESS_THAN_OR_EQUALS.
......value	String	The value to compare against for the cart condition. Returned as a string with fixed decimal places.
..action	Object	Defines the action taken when the promotion applies.
....type	String	The type of action. Possible values: CART_BASED, ITEM_BASED.
....cartBasedAction	Object	Specifies actions related to the shopping cart. Present if data.action.type is CART_BASED.
......type	String	The type of cart-based action. Possible values: ABSOLUTE, PERCENTAGE.
......value	String	Indicates the value for the cart-based action
..createdBy	Long	Indicates the unique identifier of the user who created the promotion.
..createdOn	Long	Indicates the date and time when the promotion was created.
..lastUpdatedBy	Long	Indicates the unique identifier of the user who last updated the promotion.
..lastUpdatedOn	Long	Indicates the date and time when the promotion was last updated.
..startDate	Long	Indicates the start date of the promotion.
..endDate	Long	Indicates the end date of the promotion in Unix epoch milliseconds.
..promotionRestrictions	Object	Indicates the restrictions applied to the promotion.
....Code	Array of Objects	Indicates the restrictions specific to promotion codes.
......kpi	String	Indicates the Key Performance Indicator for the restriction. Possible values: REDEMPTION, TRANSACTION, DISCOUNT.
......limit	String	Indicates the limit for the specified KPI.
..earnLimitedToSpecificAudience	Boolean	Indicates if earning is limited to a specific audience.
..mode	String	Indicates the mode of the promotion. Possible values: DISCOUNT, PAYMENT_VOUCHER.
..maxIssuancePerCustomer	Number	Indicates the maximum number of times this promotion can be issued to a single customer.
..isStackable	Boolean	Indicates if this promotion can be combined with other promotions. Defaults to false if not provided.
expiryDateChangeJobList	Array	A list of jobs created to change expiry dates for various entities related to the promotion. Each object in the array represents a single job.
..jobType	String	The type of entity whose expiry date is being changed by this job. Possible values are: `ISSUED`: for issued promotion . `EARNED`: for earned rewards . `CODE`: for promotion codes.
..status	String	The current status of the expiry date changed. Possible values: `OPEN`, `IN_PROGRESS` , `COMPLETED`, `FAILED`, `CANCELLED`.
..createdOn	Long	Indicates the date and time when this expiry date change job was created.
..lastUpdatedOn	Long	Indicates the date and time when this expiry date change job was last updated.
..lastUpdatedBy	Long	The system generated ID of the user that last updated this expiry date change job.
..createdBy	Long	The system generated ID of the user or system process that created this expiry date change job.
..message	String	A descriptive message providing details about the expiry date change, including the old and new expiry dates.

Error codes

Code	Description
400	Invalid request. Check required parameters.
400	Enum value is invalid. Check `type`, `kpi`, `operator` fields for valid values.
401	Unauthorized. Check your authentication credentials.
500	Internal server error. Retry the request after a short delay.

Language

URL

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