Orders API

Walkthrough: Automatically Apply Preconfigured Discounts to an Order Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Pricing options configured for an order affect the order's price calculation. For more information, see Automatically apply preconfigured catalog taxes or discounts. In this walkthrough, you use the pricing option to apply automatic discounts based on preconfigured pricing rules.

Overview
Step 1: Create two products (coffee and tea) for sale
Step 2: Create a rule-based discount for the products
Step 3: Test automatic discounts

Link to section
Overview

First, you create the products you want to sell. You preconfigure discounts on these items by creating a pricing rule. Using the Catalog API, you:

Create two products (CatalogItem objects). For this exercise, coffee and tea items are created.
Create a pricing rule that offers a 10% discount on these products:
- Create a product set (CatalogProductSet object) consisting of the coffee and tea items. The pricing rule you create applies to items in the product set.
- Create a discount (CatalogDiscount object) that defines the percentage discount (10%).
- Create a pricing rule (CatalogPricingRule object) identifying the discount and the product set to which the discount applies.

You then create example orders to explore how the automatic discounts affect the order's pricing calculation:

Create an order for the coffee and tea items. In the request, specify the pricing option (OrderPricingOptions) to automatically apply preconfigured discounts. The discount applies to all line items in the order.
Create an order to explore how the pricing blocklist (OrderLineItemPricingBlocklists) can be used to prevent the application of the discounts to specific line items.
Update the order to remove the automatically applied discount from specific line items. You explore how to use fields_to_clear in UpdateOrder to remove specific discounts from specific line items.

For more information, see How pricing rule-based discounts work.

Link to section
Step 1: Create two products (coffee and tea) for sale

Call BatchUpsertCatalogObjects to create two CatalogItem objects (coffee and tea items).

Batch Upsert Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "batches": [
      {
        "objects": [
          {
            "id": "#my-coffee",
            "type": "ITEM",
            "present_at_all_locations": true,
            "item_data": {
              "abbreviation": "coffee",
              "description": "hot coffee",
              "name": "8 oz coffee",
              "variations": [
                {
                  "id": "#small-hot-coffee",
                  "type": "ITEM_VARIATION",
                  "present_at_all_locations": true,
                  "item_variation_data": {
                    "price_money": {
                      "amount": 300,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                }
              ]
            }
          },
          {
            "id": "#my-tea",
            "type": "ITEM",
            "present_at_all_locations": true,
            "item_data": {
              "abbreviation": "tea",
              "description": "hot tea",
              "name": "8 oz tea",
              "variations": [
                {
                  "id": "#small-hot-tea",
                  "type": "ITEM_VARIATION",
                  "present_at_all_locations": true,
                  "item_variation_data": {
                    "price_money": {
                      "amount": 200,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Verify the response. Note the following information:

You need the item IDs to create a product set.
You need the item variation IDs to place an order.

The following is an example response fragment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  "objects": [
    {
      "type": "ITEM",
...
    },
    {
      "type": "ITEM",
...
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#my-coffee",
      "object_id": "A7AMURM7GOAIKXPOIEYRHQBL"
    },
    {
      "client_object_id": "#my-tea",
      "object_id": "L2T4V6U5HZTXUVLDTXV5NHLO"
    },
    {
      "client_object_id": "#small-hot-coffee",
      "object_id": "TUC4Z3GUU7FSMVGOHKHZRW7N"
    },
    {
      "client_object_id": "#small-hot-tea",
      "object_id": "FJRIZ2O4AI4EMCA6KP5FLDAJ"
    }
  ]
}

Link to section
Step 2: Create a rule-based discount for the products

You preconfigure the products with a discount that is rule based. The pricing rule you create applies to a product set. Therefore, you first create a product set consisting of the coffee and tea items:

Create a CatalogProductSet object to which the rule applies.
Create a CatalogDiscount object that defines a percentage-based discount.
Create a CatalogPricingRule identifying the discount and the product set to which it applies.

Call BatchUpsertCatalogObjects to create all these items in a single request. Update the code by providing the IDs of the coffee and tea items for the product set.

Batch Upsert Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "batches": [
      {
        "objects": [
          {
            "id": "#ProductSetID",
            "type": "PRODUCT_SET",
            "product_set_data": {
              "name": "PRODUCTSETWITHCOFFEE",
              "product_ids_any": [
                "COFFEE_ITEM_ID",
                "TEA_ITEM_ID"
              ]
            }
          },
          {
            "id": "#DiscountID",
            "type": "DISCOUNT",
            "discount_data": {
              "discount_type": "FIXED_PERCENTAGE",
              "name": "10% discount ",
              "percentage": "10"
            }
          },
          {
            "id": "#my-first-pricing-rule1",
            "type": "PRICING_RULE",
            "pricing_rule_data": {
              "discount_id": "#DiscountID",
              "name": "PRICINGRULE10PCCOFFEEDISCOUNT",
              "match_products_id": "#ProductSetID",
              "application_mode": "AUTOMATIC"
            }
          }
        ]
      }
    ]
  }'

The following is an example response fragment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

{
  "objects": [
    {
      "type": "PRODUCT_SET",
      "id": "2TFKNV52NE4OUL4TQ36JXDUX",
...
        "product_ids_any": [
          "A7AMURM7GOAIKXPOIEYRHQBL",
          "L2T4V6U5HZTXUVLDTXV5NHLO"
        ]
      }
    },
    {
      "type": "DISCOUNT",
      "id": "NQGJHG7AJJKMMW4ZCBBJJ4RG",
...
      "discount_data": {
        "name": "10% discount",
        "discount_type": "FIXED_PERCENTAGE",
        "percentage": "10.0"
      }
    },
    {
      "type": "PRICING_RULE",
 ...
      "pricing_rule_data": {
        "name": "PRICINGRULE10PCCOFFEEDISCOUNT",
        "discount_id": "NQGJHG7AJJKMMW4ZCBBJJ4RG",
        "match_products_id": "2TFKNV52NE4OUL4TQ36JXDUX",
        "application_mode": "AUTOMATIC"
      }
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#ProductSetID",
      "object_id": "2TFKNV52NE4OUL4TQ36JXDUX"
    },
    {
      "client_object_id": "#DiscountID",
      "object_id": "NQGJHG7AJJKMMW4ZCBBJJ4RG"
    },
    {
      "client_object_id": "#my-first-pricing-rule1",
      "object_id": "TL3AYTOI4DB4HYTL2WK3QJ6J"
    }
  ]
}

Link to section
Step 3: Test automatic discounts

Now you're ready to create orders and explore automatic discounts using pricing options.

Link to section
Step 3.1: Create an order with automatic discounts enabled

Call CreateOrder to create an order for a cup of coffee. The request includes the pricing_options with auto_apply_discounts enabled. Make sure you provide the variation ID of the small coffee in the request.

Create Order

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "{LOCATION_ID}",
      "line_items": [
        {
          "quantity": "1",
          "catalog_object_id": "{COFFEE_ITEM_VARIATION_ID}"
        }
      ],
      "pricing_options": {
        "auto_apply_discounts": true
      }
    }
  }'

In the response, notice how pricing calculations are affected by the application of automatic discounts preconfigured for the items. For example:

The line item includes applied_discounts that identifies the applied discount.
The order includes discounts that provides details about the applied discount.

The following is an example response fragment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

{
  "order":{
    "id":"5FLV8dgGYHgRdrE4XOR9W8RMxh4F",
    "location_id":"7WQ0KXC8ZSD90",
    "line_items":[
      {
        "uid":"PpAcZ9GNazqgGpy99BHbUC",
        "catalog_object_id":"TUC4Z3GUU7FSMVGOHKHZRW7N",
        "quantity":"1",
        "name":"8 oz coffee",
        "variation_name":"",
        "base_price_money":{
          "amount":300,
          "currency":"USD"
        },
...
        "total_discount_money":{
          "amount":30,
          "currency":"USD"
        },
...
        "applied_discounts":[
          {
            "uid":"ApDUTXKYyDukeiA98cG6mD",
            "discount_uid":"a5nircWuDBWzPBh797O5SD",
            "applied_money":{
              "amount":30,
              "currency":"USD"
            }
          }
        ],
        "item_type":"ITEM"
      }
    ],
    "discounts":[
      {
        "uid":"a5nircWuDBWzPBh797O5SD",
        "catalog_object_id":"NQGJHG7AJJKMMW4ZCBBJJ4RG",
        "name":"10% discount",
        "percentage":"10.0",
        "applied_money":{
          "amount":30,
          "currency":"USD"
        },
        "type":"FIXED_PERCENTAGE",
        "scope":"LINE_ITEM",
        "pricing_rule_id":"TL3AYTOI4DB4HYTL2WK3QJ6J"
      }
    ],
 ...
    "total_money":{
      "amount":270,
      "currency":"USD"
    },
...
    "pricing_options":{
      "auto_apply_discounts":true
    }
  }
}

Link to section
Step 3.2: Update an order to remove previously applied automatic discounts

You can call UpdateOrder to remove specific discounts applied to specific line items. You add fields_to_clear to identify the specific line items and specific discounts you want to remove. Update the preceding order by removing the specific discount applied to the line item. Make sure you provide the order ID, location ID, line item ID, and ID of the specific discount you want to remove.

Update Order

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
  -X PUT \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "version": 1,
      "location_id": "{LOCATION_ID}"
    },
    "fields_to_clear": [
      "line_items[LINE_ITEM_UID].applied_discounts[APPLIED_DISCOUNT_UID]"
    ]
  }'

In the response, review the pricing calculation updates. For example:

The line item includes pricing_blocklists showing the discount that is blocked from applying automatically.
The specific line item shows no discount and the order pricing is updated accordingly.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "order": {
    "id": "5FLV8dgGYHgRdrE4XOR9W8RMxh4F",
    "location_id": "7WQ0KXC8ZSD90",
    "line_items": [
      {
        "uid": "PpAcZ9GNazqgGpy99BHbUC",
        "catalog_object_id": "TUC4Z3GUU7FSMVGOHKHZRW7N",
        "quantity": "1",
        "name": "8 oz coffee",
        "variation_name": "",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
         ...
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        ...
        "pricing_blocklists": {
          "blocked_discounts": [
            {
              "uid": "5vcvLw4SgLJhCtxzXESzRD",
              "discount_catalog_object_id": "NQGJHG7AJJKMMW4ZCBBJJ4RG"
            }
          ]
        }
      }
    ],
    ...
  }
}

Link to section
Step 3.3: Create an order with automatic discounts enabled, but block specific line items

Create an order for both coffee and tea, but block one of the items from the automatic discount. In the following CreateOrder request:

pricing_options is specified to automatically apply preconfigured discounts.
One of the line items specifies pricing_blocklists and includes discount_catalog_object_id to block it from being automatically applied.

Make sure you provide the coffee and tea item variation IDs, location ID, and the ID of the CatalogDiscount you created in step 2.

Create Order

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "{LOCATION_ID}",
      "line_items": [
        {
          "quantity": "1",
          "catalog_object_id": "{COFFEE_ITEM_VARIATION_ID}"
        },
        {
          "quantity": "1",
          "catalog_object_id": "{TEA_ITEM_VARIATION_ID}",
          "pricing_blocklists": {
            "blocked_discounts": [
              {
                "uid": "{blocked-discount-uid1}",
                "discount_catalog_object_id": "{DISCOUNT_CATALOG_ITEM_ID}"
              }
            ]
          }
        }
      ],
      "pricing_options": {
        "auto_apply_discounts": true
      }
    }
  }'

In the response, verify the pricing calculations. The automatic discount is applied to only one item. The following is an example response fragment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

{
  "order": {
    "id": "H6cee9rVqMpk72u7PBNHpXwRzb4F",
    "location_id": "7WQ0KXC8ZSD90",
    "line_items": [
      {
        "uid": "65LYqUkTc8RRpnvDCQGMFD",
        "catalog_object_id": "C4GMNPPM72TKN6ZCQ2P6I7EA",
        "quantity": "1",
        "name": "8 oz coffee",
        "variation_name": "",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        ...
        "total_discount_money": {
          "amount": 30,
          "currency": "USD"
        },
        "applied_discounts": [
          {
            "uid": "BMzT5qieOsZE6xxV9YukI",
            "discount_uid": "BQbtlz2qPEDm1Krbb8W4s",
            "applied_money": {
              "amount": 30,
              "currency": "USD"
            }
          }
        ],
      },
      {
        "uid": "DGguEBcQASRM1b4QdUNNfD",
        "catalog_object_id": "4I3XGUSLC4GYG5TV3RGYFCLE",
        "quantity": "1",
        "name": "8 oz tea",
        "variation_name": "",
        "base_price_money": {
          "amount": 200,
          "currency": "USD"
        },
        ...
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "pricing_blocklists": {
          "blocked_discounts": [
            {
              "uid": "blocked-discount-uid1",
              "discount_catalog_object_id": "62PZMXOYOVQFAAPH6XXNGOWB"
            }
          ]
        }
      }
    ],
    "discounts": [
      {
        "uid": "BQbtlz2qPEDm1Krbb8W4s",
        "catalog_object_id": "62PZMXOYOVQFAAPH6XXNGOWB",
        "name": "10% discount",
        "percentage": "10.0",
        "applied_money": {
          "amount": 30,
          "currency": "USD"
        },
        "type": "FIXED_PERCENTAGE",
        "scope": "LINE_ITEM",
        "pricing_rule_id": "MJU7VWXVBTVDEGME7SWUTQD7"
      }
    ],
    "total_discount_money": {
      "amount": 30,
      "currency": "USD"
    },
    "total_money": {
      "amount": 470,
      "currency": "USD"
    },
    ...
    "net_amounts": {
      "total_money": {
        "amount": 470,
        "currency": "USD"
      },
      ...
      "discount_money": {
        "amount": 30,
        "currency": "USD"
      },
    },
    ...
    "pricing_options": {
      "auto_apply_discounts": true
    }
  }
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Walkthrough: Automatically Apply Preconfigured Discounts to an Order Beta release

This is pre-release documentation for an API in public beta and is subject to change.

On this page

Link to section
Overview

Link to section
Step 1: Create two products (coffee and tea) for sale

Link to section
Step 2: Create a rule-based discount for the products

Link to section
Step 3: Test automatic discounts

Link to section
Step 3.1: Create an order with automatic discounts enabled

Link to section
Step 3.2: Update an order to remove previously applied automatic discounts

Link to section
Step 3.3: Create an order with automatic discounts enabled, but block specific line items

On this page

Docs

Walkthrough: Automatically Apply Preconfigured Discounts to an Order Beta release This is pre-release documentation for an API in public beta and is subject to change.

On this page

Link to section Overview

Link to section Step 1: Create two products (coffee and tea) for sale

Link to section Step 2: Create a rule-based discount for the products

Link to section Step 3: Test automatic discounts

Link to section Step 3.1: Create an order with automatic discounts enabled

Link to section Step 3.2: Update an order to remove previously applied automatic discounts

Link to section Step 3.3: Create an order with automatic discounts enabled, but block specific line items

On this page

Walkthrough: Automatically Apply Preconfigured Discounts to an Order Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Link to section
Overview

Link to section
Step 1: Create two products (coffee and tea) for sale

Link to section
Step 2: Create a rule-based discount for the products

Link to section
Step 3: Test automatic discounts

Link to section
Step 3.1: Create an order with automatic discounts enabled

Link to section
Step 3.2: Update an order to remove previously applied automatic discounts

Link to section
Step 3.3: Create an order with automatic discounts enabled, but block specific line items