For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
  • Overview
    • Quick Start
    • Sandboxes
    • Tools & SDKs
    • Support
  • Docs
      • Getting Started
        • Products overview
        • Contextual filters
          • Overview
          • Currency-Specific Promotions
          • Multi-Currency
          • API vs UI Features
            • Brand
            • Category
            • Customer
            • Order
            • Product
            • Shipping
            • Storewide
            • Using logical operators
            • Using multiple rules
    • Archive
    • Closed Beta Programs
Dev Portal
LogoLogo
On this page
  • Buy one and get one free
  • Buy (X units) of product A and get (Y units) of product B for $ or % off per unit
  • Get $ or % off product X
  • Take X% off the most expensive item in the cart
  • Buy X product variant and get X product variant free
  • Amount off
  • Percentage off
  • Buy three for the price of two
  • Buy extra-small or medium item and get free shipping to zone id 1 (Product Options Item Matcher)
  • Buy extra-small blue or medium blue item and receive free shipping (Product Options Item Matcher)
  • Take 20% off all men’s clothing (Product Custom Field Item Matcher)
DocsAdminCatalog and InventoryPromotionsExamples

Product Promotion Code Samples

Was this page helpful?
Previous

Order

Next

Shipping

Built with

Buy one and get one free

Request
Response
Example request
1{
2 "name": "Buy one and get one free",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "action": {
7 "gift_item": {
8 "product_id": 130,
9 "quantity": 1
10 }
11 },
12 "apply_once": false,
13 "stop": false,
14 "currency_code": "AUD",
15 "condition": {
16 "cart": {
17 "items": {
18 "products": [
19 130
20 ]
21 },
22 "minimum_quantity": 1
23 }
24 }
25 }
26 ],
27 "notifications": [
28 {
29 "type": "UPSELL",
30 "content": "",
31 "locations": [
32 "CART_PAGE"
33 ]
34 },
35 {
36 "type": "ELIGIBLE",
37 "content": "",
38 "locations": [
39 "CART_PAGE"
40 ]
41 },
42 {
43 "type": "APPLIED",
44 "content": "",
45 "locations": [
46 "CART_PAGE"
47 ]
48 }
49 ],
50 "stop": false,
51 "status": "ENABLED",
52 "start_date": "2019-02-06T05:00:00+00:00",
53 "end_date": "2019-02-09T04:59:59+00:00"
54}

Buy (X units) of product A and get (Y units) of product B for $ or % off per unit

Request
Response
Example request
{
"name": "Buy two X and get 10% off Y",
"redemption_type": "AUTOMATIC",
"rules": [
{
"action": {
"cart_items": {
"discount": {
"percentage_amount": "10"
},
"strategy": "LEAST_EXPENSIVE",
"as_total": false,
"include_items_considered_by_condition": false,
"items": {
"products": [
130
]
},
"quantity": 1
}
},
"apply_once": false,
"stop": false,
"condition": {
"cart": {
"items": {
"products": [
129
]
},
"minimum_quantity": 1
}
}
}
],
"notifications": [
{
"type": "UPSELL",
"content": "",
"locations": [
"CART_PAGE"
]
},
{
"type": "ELIGIBLE",
"content": "",
"locations": [
"CART_PAGE"
]
},
{
"type": "APPLIED",
"content": "",
"locations": [
"CART_PAGE"
]
}
],
"stop": false,
"status": "ENABLED"
}

Get $ or % off product X

Request
Response
Example request
1{
2 "name": "Spend 100 dollars and get 10% off small orbit",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "action": {
7 "cart_items": {
8 "discount": {
9 "percentage_amount": "10"
10 },
11 "strategy": "LEAST_EXPENSIVE",
12 "as_total": false,
13 "include_items_considered_by_condition": false,
14 "items": {
15 "products": [
16 130
17 ]
18 },
19 "quantity": 1
20 }
21 },
22 "apply_once": true,
23 "stop": false,
24 "condition": {
25 "cart": {
26 "minimum_spend": "100"
27 }
28 }
29 }
30 ],
31 "notifications": [
32 {
33 "type": "UPSELL",
34 "content": "",
35 "locations": [
36 "CART_PAGE"
37 ]
38 },
39 {
40 "type": "ELIGIBLE",
41 "content": "",
42 "locations": [
43 "CART_PAGE"
44 ]
45 },
46 {
47 "type": "APPLIED",
48 "content": "",
49 "locations": [
50 "CART_PAGE"
51 ]
52 }
53 ],
54 "stop": false,
55 "status": "ENABLED"
56}

Take X% off the most expensive item in the cart

Request
Response
Example request
1{
2 "name": "Apply 20% off most expensive cart item",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "action": {
7 "cart_items": {
8 "discount": {
9 "percentage_amount": "20"
10 },
11 "quantity": 1,
12 "strategy": "MOST_EXPENSIVE",
13 "as_total": false
14 }
15 },
16 "apply_once": true,
17 "stop": false
18 }
19 ],
20 "notifications": [
21 {
22 "type": "UPSELL",
23 "content": "<div>&nbsp;</div>",
24 "locations": [
25 "CART_PAGE"
26 ]
27 },
28 {
29 "type": "ELIGIBLE",
30 "content": "<div>&nbsp;</div>",
31 "locations": [
32 "CART_PAGE"
33 ]
34 },
35 {
36 "type": "APPLIED",
37 "content": "<div>&nbsp;</div>",
38 "locations": [
39 "CART_PAGE"
40 ]
41 }
42 ],
43 "stop": false,
44 "current_uses": 0,
45 "max_uses": null,
46 "start_date": "2019-01-31T05:00:00+00:00",
47 "end_date": null,
48 "status": "ENABLED"
49}

Buy X product variant and get X product variant free

Request
Response
Example request
1{
2 "name": "Buy X product variant and get X product variant free",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "action": {
7 "gift_item": {
8 "variant_id": 151,
9 "quantity": 1
10 }
11 },
12 "apply_once": false,
13 "stop": false,
14 "currency_code": "GBP",
15 "condition": {
16 "cart": {
17 "items": {
18 "variants": [
19 139
20 ]
21 },
22 "minimum_quantity": 2
23 }
24 }
25 }
26 ],
27 "notifications": [
28 {
29 "type": "UPSELL",
30 "content": "<div>&nbsp;</div>\r\n<div>&nbsp;</div>",
31 "locations": [
32 "CART_PAGE"
33 ]
34 },
35 {
36 "type": "ELIGIBLE",
37 "content": "<div>&nbsp;</div>\r\n<div>&nbsp;</div>",
38 "locations": [
39 "CART_PAGE"
40 ]
41 },
42 {
43 "type": "APPLIED",
44 "content": "<div>&nbsp;</div>\r\n<div>&nbsp;</div>",
45 "locations": [
46 "CART_PAGE"
47 ]
48 }
49 ],
50 "stop": false,
51 "status": "ENABLED"
52}

Amount off

Request
Response
Example request
1{
2 "name": "US $50 off a specific product",
3 "redemption_type": "AUTOMATIC",
4 "currency_code": "USD",
5 "rules": [
6 {
7 "apply_once": false,
8 "condition": {
9 "cart": {
10 "items": {
11 "products": [
12 129
13 ]
14 },
15 "minimum_quantity": 1
16 }
17 },
18 "action": {
19 "cart_items": {
20 "discount": {
21 "fixed_amount": "50"
22 },
23 "items": {
24 "products": [
25 130
26 ]
27 },
28 "quantity": 1,
29 "include_items_considered_by_condition": true
30 }
31 }
32 }
33 ]
34}

Percentage off

Request
Response
Example request
1{
2 "name": "US 15% off a specific product",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "apply_once": false,
7 "condition": {
8 "cart": {
9 "items": {
10 "products": [
11 129
12 ]
13 },
14 "minimum_quantity": 1
15 }
16 },
17 "action": {
18 "cart_items": {
19 "discount": {
20 "percentage_amount": "75"
21 },
22 "items": {
23 "products": [
24 130
25 ]
26 },
27 "quantity": 1,
28 "include_items_considered_by_condition": true
29 }
30 }
31 }
32 ]
33}

Buy three for the price of two

Request
Response
Example request
1{
2 "name": "Buy three for the price of two",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "apply_once": false,
7 "condition": {
8 "cart": {
9 "items": {
10 "products": [
11 129
12 ]
13 },
14 "minimum_quantity": 2
15 }
16 },
17 "action": {
18 "cart_items": {
19 "discount": {
20 "percentage_amount": "100"
21 },
22 "items": {
23 "products": [
24 130
25 ]
26 },
27 "quantity": 1
28 }
29 }
30 }
31 ]
32}

Buy extra-small or medium item and get free shipping to zone id 1 (Product Options Item Matcher)

Request
Response
Example request
1{
2 "name": "Buy extra-small or medium item and get free shipping to zone id 1",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "condition":{
7 "cart":{
8 "items": {
9 "product_option": {
10 "type": "string_match",
11 "name": "Size",
12 "values": [
13 "XS",
14 "M"
15 ]
16 }
17 },
18 "minimum_quantity": 1
19 }
20 },
21 "action":{
22 "shipping":{
23 "free_shipping":true,
24 "zone_ids":[
25 1
26 ]
27 }
28 }
29 }
30 ]
31}

Buy extra-small blue or medium blue item and receive free shipping (Product Options Item Matcher)

Request
Response
Example request
1{
2 "name": "Buy extra-small blue or medium blue item and receive free shipping",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "condition": {
7 "cart": {
8 "items": {
9 {
10 "product_option": {
11 "type": "string_match",
12 "name": "Size",
13 "values": [
14 "XS",
15 "M"
16 ]
17 }
18 },
19 {
20 "product_option": {
21 "type": "string_match",
22 "name": "Color",
23 "values": [
24 "Blue"
25 ]
26 }
27 }
28 },
29 "minimum_quantity": 1
30 }
31 },
32 "action": {
33 "shipping": {
34 "free_shipping": true,
35 "zone_ids": [
36 1
37 ]
38 }
39 }
40 }
41 ]
42}

Take 20% off all men’s clothing (Product Custom Field Item Matcher)

Request
Response
Example request
1{
2 "name": "Apply 20% off all male clothing",
3 "redemption_type": "AUTOMATIC",
4 "rules": [
5 {
6 "action": {
7 "cart_items": {
8 "discount": {
9 "percentage_amount": "20"
10 },
11 "items": {
12 "product_custom_field": {
13 "name": "Gender",
14 "values": [
15 "Mens"
16 ]
17 }
18 }
19 }
20 }
21 }
22 ]
23}