Promotion specifications

Use the promotion object to provide promotion data for an item.

Parameters

The promotion object accepts the following parameters.

Field	Type	Required	Description
promotion_type	string	yes	The type of promotional offer. For valid values and metadata requirements, see Promotion metadata fields.
promotion_metadata	JSON	yes	The metadata for the promotion. Required fields vary by promotion_type. For more information, see Promotion metadata fields.
promotion_start_at	string	yes	The date and time when the promotion begins, in ISO 8601 format. For example, 2025-01-15T14:30:00Z.
promotion_end_at	string	yes	The date and time when the promotion ends, in ISO 8601 format. For example, 2025-01-15T14:30:00Z.
promotion_group_id	string	yes	A unique identifier for the promotion group.

Example

{
  "lookup_code": "1234567890",
  "store_identifier": "1234",
  "promotion": {
    "promotion_type": "Buy_M_Get_N_Free",
    "promotion_metadata": {
      "buy": 3,
      "get": 2,
      "loyalty_members_only": 1,
      "qty_enforced": 1
    },
    "promotion_start_at": "2025-01-15T00:00:00Z",
    "promotion_end_at": "2025-01-31T23:59:59Z",
    "promotion_group_id": "promo-group-123"
  }
}