Orders API

Walkthrough: Automatically Apply Preconfigured Taxes 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 taxes based on taxes preconfigured for the catalog items.

Overview
Step 1: Create a product (coffee) for sale
Step 2: Test automatic taxes

Link to section
Overview

First, you create the products you want to sell with taxes preconfigured. You then create example orders to explore how automatically applying preconfigured taxes affects the order's pricing calculation:

Create an order for coffee. In the request, specify the pricing option to automatically apply preconfigured taxes. The taxes apply to all line items in the order.
Update the order to remove the automatically applied tax from specific line items.
Create an order with automatic taxes enabled, but block specific line items.

For more information, see Automatically apply preconfigured catalog taxes and discounts.

Link to section
Step 1: Create a product (coffee) for sale

Call BatchUpsertCatalogObjects to create two items in the catalog:

A CatalogTax item (define 10% tax).
A CatalogItem object (coffee) with the tax enabled.

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

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": "#Coffee-Tax",
            "type": "TAX",
            "tax_data": {
              "name": "10PCTax",
              "percentage": "10.0"
            }
          },
          {
            "id": "#Coffee-Item",
            "type": "ITEM",
            "present_at_all_locations": true,
            "item_data": {
              "abbreviation": "coffee",
              "description": "hot coffee",
              "name": "8 oz coffee",
              "tax_data": "8 oz coffee",
              "tax_ids": [
                "#Coffee-Tax"
              ],
              "variations": [
                {
                  "id": "#8-oz-hot",
                  "type": "ITEM_VARIATION",
                  "present_at_all_locations": true,
                  "item_variation_data": {
                    "price_money": {
                      "amount": 300,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

In the response, verify that the catalog objects are created. The coffee items (of the ITEM type) should have the tax_ids field showing the tax enabled on it.

You need the coffee item variation ID to place the coffee order in the next step.

Link to section
Step 2: Test automatic taxes

Link to section
Step 2.1: Create an order with automatic taxes enabled

Call CreateOrder to create an order for a cup of coffee. In the request, include pricing_options to enable auto_apply_taxes.

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_taxes": true
      }
    }
  }'

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

The line item includes applied_taxes that identifies the taxes applied.
The order includes taxes that provides details about the taxes applied.

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

{
  "order": {
    "id": "tf5qPnDsDZmMFL1URXuGw6XyPg4F",
    "location_id": "7WQ0KXC8ZSD90",
    "line_items": [
      {
        "uid": "NG6toHsDGEQ55E9xrIU3DB",
        "catalog_object_id": "UOYGJJLCO6IPMLS74RBHBXP6",
        "quantity": "1",
        "name": "8 oz coffee",
        "variation_name": "",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 30,
          "currency": "USD"
        },
...
        "applied_taxes": [
          {
            "uid": "2htIbrU5QIHrV3QRy1jnED",
            "tax_uid": "EUzV9RDN1IwueboPLyw6B",
            "applied_money": {
              "amount": 30,
              "currency": "USD"
            }
          }
        ],
      }
    ],
    "taxes": [
      {
        "uid": "EUzV9RDN1IwueboPLyw6B",
        "catalog_object_id": "EJPKOFCKEQPMERIW5N6PMHYE",
        "name": "10PCTax",
        "percentage": "10.0",
        "type": "ADDITIVE",
        "applied_money": {
          "amount": 30,
          "currency": "USD"
        },
        "scope": "LINE_ITEM",
        "auto_applied": true
      }
    ],
...
    "total_tax_money": {
      "amount": 30,
      "currency": "USD"
    },
...
    "total_money": {
      "amount": 330,
      "currency": "USD"
    },
...
    "pricing_options": {
      "auto_apply_taxes": true
    }
  }
}

Link to section
Step 2.2: Update an order to remove previously applied automatic taxes

You can call UpdateOrder to remove specific taxes applied to specific line items. Add fields_to_clear to identify specific line items and specific taxes to remove. Update the preceding order by removing the specific taxes applied to the line item.

Make sure you provide the order ID, location ID, line item ID, and ID of the applied tax that 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_taxes[APPLIED_TAX_UID]"
    ]
  }'

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

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

The response shows the line item with specific taxes blocked that were previously applied.

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

{
  "order": {
    "id": "tf5qPnDsDZmMFL1URXuGw6XyPg4F",
    "location_id": "7WQ0KXC8ZSD90",
    "line_items": [
      {
        "uid": "NG6toHsDGEQ55E9xrIU3DB",
        "catalog_object_id": "UOYGJJLCO6IPMLS74RBHBXP6",
        "quantity": "1",
        "name": "8 oz coffee",
        "variation_name": "",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
...
        "total_tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 300,
          "currency": "USD"
        },
        "item_type": "ITEM",
        "pricing_blocklists": {
          "blocked_taxes": [
            {
              "uid": "kREIvFWsK344VAoDXgQ7bB",
              "tax_catalog_object_id": "EJPKOFCKEQPMERIW5N6PMHYE"
            }
          ]
        }
      }
    ],
...
    "total_tax_money": {
      "amount": 0,
      "currency": "USD"
    },
...
    "total_money": {
      "amount": 300,
      "currency": "USD"
    },
...
    "pricing_options": {
      "auto_apply_taxes": true
    }
  }
}

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

Call CreateOrder to create an order for the coffee. In the request:

Specify pricing_options to automatically apply preconfigured taxes.
For the specific line item, add pricing_blocklists and include the ID of the CatalogTax object to block it from having taxes automatically applied.

Make sure you provide the coffee item variation ID, location ID, and ID of the tax (you created in step 1) that you want to block from automatic application.

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

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_blocklists": {
            "blocked_taxes": [
              {
                "uid": "{blocked-tax-uid1}",
                "tax_catalog_object_id": "{TAX_CATALOG_OBJECT_ID}"
              }
            ]
          }
        }
      ],
      "pricing_options": {
        "auto_apply_taxes": true
      }
    }
  }'

In the response, verify the pricing calculations. Because you blocked the line item from having preconfigured taxes automatically applied, there are no taxes applied. 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

{
  "order": {
    "id": "TUKUwDEc8KyJzDhDm9OIvxg7Hd4F",
    "location_id": "7WQ0KXC8ZSD90",
    "line_items": [
      {
        "uid": "xjltiLQzOGHmitTPlLjD3",
        "catalog_object_id": "UOYGJJLCO6IPMLS74RBHBXP6",
        "quantity": "1",
        "name": "8 oz coffee",
        "variation_name": "",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
...
        "total_tax_money": {
          "amount": 0,
          "currency": "USD"
        },
...
        "pricing_blocklists": {
          "blocked_taxes": [
            {
              "uid": "blocked-tax-uid1",
              "tax_catalog_object_id": "EJPKOFCKEQPMERIW5N6PMHYE"
            }
          ]
        }
      }
    ],
...
    "total_tax_money": {
      "amount": 0,
      "currency": "USD"
    },
    "total_discount_money": {
...
    "total_money": {
      "amount": 300,
      "currency": "USD"
    },
...
      "tax_money": {
        "amount": 0,
        "currency": "USD"
      },
...
    "pricing_options": {
      "auto_apply_taxes": true
    }
  }
}

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

Docs

Walkthrough: Automatically Apply Preconfigured Taxes 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 a product (coffee) for sale

Link to section
Step 2: Test automatic taxes

Link to section
Step 2.1: Create an order with automatic taxes enabled

Link to section
Step 2.2: Update an order to remove previously applied automatic taxes

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

On this page

Docs

Walkthrough: Automatically Apply Preconfigured Taxes 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 a product (coffee) for sale

Link to section Step 2: Test automatic taxes

Link to section Step 2.1: Create an order with automatic taxes enabled

Link to section Step 2.2: Update an order to remove previously applied automatic taxes

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

On this page

Walkthrough: Automatically Apply Preconfigured Taxes 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 a product (coffee) for sale

Link to section
Step 2: Test automatic taxes

Link to section
Step 2.1: Create an order with automatic taxes enabled

Link to section
Step 2.2: Update an order to remove previously applied automatic taxes

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