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

Apply Taxes and Discounts

You can apply taxes and discounts to an order's price calculation using the following options:

  • You can explicitly specify taxes and discounts in the order.

  • You can have taxes and discounts preconfigured for catalog items. In the order, you can enable the automatic application of these taxes and discounts.

Explicitly specify taxes or discounts in an order Permalink Get a link to this section

You can define taxes or discounts in an order. In the definition, include the scope identifying whether it applies to the entire order or to specific line items in the order.

The following are examples of taxes attributes you can add to an order:

  • taxes that specifies catalog_object_id to reference a predefined catalog tax to be applied.

     "taxes": [
        {
          "uid": "STATE_SALES_TAX_UID",
          "catalog_object_id": "STATE_SALES_TAX_CATALOG_ID",
          "scope": "ORDER"
        }
      ]
    
  • taxes that defines ad hoc taxes (does not reference any predefined catalog object).

    "taxes": [
        {
            "uid": "STATE_SALES_TAX_UID",
            "scope": "ORDER",
            "name": "State Sales Tax",
            "percentage": "7.0"
        }
    ]
    

The following are examples of discounts attributes that you can add to an order:

  • discounts that specifies catalog_object_id to reference a predefined catalog discount to be applied.

    "discounts": [
        {
            "uid": "EXPLICIT_DISCOUNT_UID",
            "scope": "ORDER",
            "catalog_object_id": "EXPLICIT_DISCOUNT_CATALOG_ID"
        }
    ]
    
  • discounts that defines ad hoc discount (does not reference any predefined catalog discount).

     "discounts": [
         {
           "uid": "EXPLICIT_DISCOUNT_UID",
           "name": "Sale - $1.00 off",
           "amount_money": {
             "amount": 100,
             "currency": "USD"
           },
           "scope": "ORDER"
         }
       ]
    

The preceding examples set ORDER as the scope. Therefore, these apply to all line items in the order. If the scope is limited to LINE_ITEM only, individual line items must include applied_taxes or applied_discounts corresponding to the tax or discount that applies.

The following are example CreateOrder requests that configure taxes and discounts explicitly for the order:

  • Create an order with explicit taxes scoped to the entire order. The following CreateOrder request defines an ORDER-scoped tax that applies to every line item in the order:

    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
    • 33
    • 34
    • 35
    • 36
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2021-07-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "{LOCATION_ID}",
          "line_items": [
            {
              "catalog_object_id": "{COFFEE_ITEM_ID}",
              "modifiers": [
                {
                  "catalog_object_id": "{SMALL_MODIFIER_ID}"
                }
              ]
            },
            {
              "catalog_object_id": "{COOKIE_ITEM_ID}",
              "modifiers": [
                {
                  "catalog_object_id": "{CHOCOLATE_MODIFIER_ID}"
                }
              ]
            }
          ],
          "taxes": [
            {
              "uid": "{STATE_SALES_TAX_UID}",
              "catalog_object_id": "{STATE_SALES_TAX_CATALOG_ID}",
              "scope": "ORDER"
            }
          ]
        }
      }'

    Similarly, you can explicitly define discounts that apply to the entire order.

  • Create an order with explicit discounts scoped to line items. The following CreateOrder request defines a tax that is scoped to LINE_ITEM. Individual line items to which the tax applies must include applied_taxes with a reference the tax defined. The example shows two line items and the tax applies only to the second line item.

    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
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    • 41
    • 42
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2021-07-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "{LOCATION_ID}",
          "line_items": [
            {
              "catalog_object_id": "{COFFEE_ITEM_ID}",
              "modifiers": [
                {
                  "catalog_object_id": "{SMALL_MODIFIER_ID}"
                }
              ]
            },
            {
              "catalog_object_id": "{SODA_ITEM_ID}",
              "modifiers": [
                {
                  "catalog_object_id": "{CHERRY_MODIFIER_ID}"
                }
              ],
              "applied_taxes": [
                {
                  "uid": "{APPLIED_SODA_TAX}",
                  "tax_uid": "{SODA_TAX_UID}"
                }
              ]
            }
          ],
          "taxes": [
            {
              "uid": "{SODA_TAX_UID}",
              "catalog_object_id": "{SODA_TAX_CATALOG_ID}",
              "scope": "LINE_ITEM"
            }
          ]
        }
      }'

    Similarly, you can define discounts and add applied_discounts to specific line items.

    Note

    You can create LINE_ITEM taxes and discounts ahead of time without referencing them from any line items. Later, when you are ready for the tax or discount to take effect, you can update the order to reference the tax or discount from the line-item level.

Block ORDER-scoped discounts and taxes from applying to individual line items Permalink Get a link to this section

When you have ORDER-scoped taxes or discounts, you can add the pricing_blocklists attribute to individual line items in the order to identify the ORDER-scoped discounts or taxes you do not want to apply.

"pricing_blocklists": {
  "blocked_discounts": [
    {
      "uid": "BLOCKED_DISCOUNT_UID",
      "discount_uid": "ORDER_SCOPED_DISCOUNT_UID"
    }
  ],
  "blocked_taxes": [
    {
      "uid": "BLOCKED_TAX_UID",
      "tax_uid": "ORDER_SCOPED_TAX_UID"
    }
  ]
}

Automatically apply preconfigured catalog taxes or discounts Permalink Get a link to this section

Automatically applying taxes or discounts removes the need to explicitly apply these price adjustments to an order. For example, you can create a CatalogTax object defining a tax percentage (such as 10%). You can then enable the tax on a catalog item.

To apply these preconfigured taxes and discounts to an order's price calculation, you must explicitly specify pricing_options (OrderPricingOptions) in the order and enable the automatic application of these preconfigured taxes and discounts.

  • Automatically apply discounts.

     "pricing_options": {
       "auto_apply_discounts": true
     }
    
  • Automatically apply taxes.

     "pricing_options": {
       "auto_apply_taxes": true
     }
    

This automatic application of preconfigured taxes and discounts applies to all applicable line items.

For examples, see the following topics:

Block the automatic application of preconfigured taxes and discounts Permalink Get a link to this section

When you specify pricing_options, preconfigured taxes and discounts are automatically applied to an order's price calculation. You can also block this automatic application to individual line items when creating an order or after the order is created. You might choose to block a preconfigured tax or discount if they should not be applied to an order based on the business or tax rules.

  • CreateOrder (Block the automatic application of preconfigured taxes and discounts). When creating an order, you can add pricing_blocklists (OrderLineItemPricingBlocklists) to individual line items to identify preconfigured discounts and taxes that you do not want applied.

    "pricing_blocklists": {
      "blocked_discounts": [
        {
          "uid": "BLOCKED_DISCOUNT_UID",
          "discount_catalog_object_id": "DISCOUNT_CATALOG_OBJECT_ID"
        }
      ],
      "blocked_taxes": [
        {
          "uid": "BLOCKED_TAX_UID",
          "tax_catalog_object_id": "TAX_CATALOG_OBJECT_ID"
        }
      ]
    }
    

    For more information, see the blocking taxes example in Walkthrough 2 and the blocking discounts example in Walkthrough 1.

Update an order to remove previously applied discounts or taxes Permalink Get a link to this section

After an order is created, you can call UpdateOrder to unapply taxes and discounts previously applied to individual line items. In the request, you include fields_to_clear and specify the line item and specific tax or discount you want removed.

"fields_to_clear": [   
  "line_items[LINE_ITEM_UID].applied_discounts[APPLIED_DISCOUNT_UID]",
  "line_items[LINE_ITEM_UID].applied_taxes[{{APPLIED_TAX_UID]"
]

For more information, see the blocking discounts example in Walkthrough 1 and the blocking taxes example in Walkthrough 2.