Apply Catalog Taxes to Orders

Applies to: Orders API | Catalog API

Learn how to create orders with automatically applied catalog taxes.

Pricing options configured for an order affect the order's price calculation. Use the pricing option to have Square apply catalog-defined taxes to line items, whether they're ad hoc items or based on catalog item variations.

Before this automatic tax application feature was available, your application relied on the presence of an order.taxes object in the order as shown in the following example:

{
  "taxes": [
     {
         "uid": "STATE_SALES_TAX_UID",
         "catalog_object_id": "BME4AVPBJG7ZCMJAK3PCQGK4",
         "scope": "ORDER"
     }
  ]
}

If the order.taxes property isn't present in a CreatOrder request, Square cannot apply a tax to the order. For more information about manually taxing an order, see Apply taxes and discounts.

Instead of adding an order.taxes property to a CreateOrder request, add the order.pricing_options property as shown in the following example:

{
    "pricing_options": {
        "auto_apply_discounts": true,
        "auto_apply_taxes": true
    }
}

When taxes are automatically applied, Square gets tax information from the seller's catalog. For catalog-based line items, taxes associated with the catalog item are applied. For ad hoc items, Square applies all CatalogTax objects that can be applied to custom amounts.

The following CreateOrder request creates an order for a cup of coffee, which is taxed twice. There's an automatically applied line item tax for the tax associated with the coffee catalog item and there's an order tax manually applied to the order:

If a seller wants to charge an arbitrary amount on an order without referencing an item from the catalog, they create an order line item without first selecting one from the Item library. In the order.line_items[].name property, your application uses whatever item name and price the seller inputs.

For example, a buyer gets a pair of socks from a sale bin on the sidewalk in front of a store. All the socks in the bin are discounted to $1 and are no longer in the catalog. The clerk types "socks" in the checkout page of your application and inputs $1.00. Your application creates an ad hoc item with the name "socks" and a custom price of 100 ($1.00).

The order.line_items[].base_price_money property holds whatever amount the seller wants to charge. It has a custom amount because the base price doesn't come from the catalog. The ad hoc line item doesn't reference a catalog item variation. For more information about taxing ad hoc items, see Catalog taxes.

Before your application can apply preconfigured taxes to an order, the seller needs to define one or more CatalogTax items. The CatalogTax has properties that define how the tax is calculated in an order. However, the property that differentiates a catalog tax that applies to catalog items and a tax that also applies to ad hoc items is the applies_to_custom_amounts Boolean property.

The following two tax object examples show both types of catalog taxes:

{
          "type": "TAX",
          "id": "QZEJM5A6Y3KFTKHWAVDKXU2O",
          "updated_at": "2024-09-11T22:25:20.797Z",
          "created_at": "2024-09-11T22:25:20.797Z",
          "version": 1726093520797,
          "is_deleted": false,
          "present_at_all_locations": true,
          "tax_data": {
              "name": "catalog item tax",
              "calculation_phase": "TAX_SUBTOTAL_PHASE",
              "inclusion_type": "ADDITIVE",
              "percentage": "10.0",
              "applies_to_custom_amounts": false,
              "enabled": true
          }
      }

When your application creates an order that specifies a line item without referencing a catalog item variation, but just supplies an item name, quantity, and base price, it's creating an ad hoc item as shown in the following example CreateOrder request and response.

{
  "idempotency_key": "PBU2WR26J7RUMISJBAT5YEG3",
  "order": {
      "reference_id": "my-order-0009",
      "location_id": "{LOCATION_ID}",
      "customer_id": "{CUSTOMER_ID}",
      "line_items": [
          {
              "name": "Last year's wool socks",
              "quantity": "1",
              "variation_name": "Medium",
              "base_price_money": {
                  "amount": 100,
                  "currency": "USD"
              }
          }
      ],
      "pricing_options": {
          "auto_apply_discounts": true,
          "auto_apply_taxes": true
      }
  }
}

First, create the products you want to sell and a tax you want to use. Then, create example orders to explore how having Square apply preconfigured taxes affects the order's pricing calculation:

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

For more information, see Square applies taxes and discounts.

Call BatchUpsertCatalogObjects to create two items in the catalog:

• A CatalogTax object with a 10% tax that applies to all line items.
• A CatalogItem coffee object with the tax enabled.

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.

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

In the response, see how pricing calculations are affected by Square's application of preconfigured taxes for the item. For example:

• The line item includes applied_taxes, which identifies the applied taxes.
• The order includes taxes, which provides details about the applied taxes.

Square calculates taxes using rounding rules known as Bankers' Rounding. For information about these rounding rules, see Rounding rules.

The following example response shows a partial Order object with only the relevant fields:

{
  "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
    }
  }
}

You can call UpdateOrder to remove specific taxes applied to specific line items. Add fields_to_clear to identify specific line items and specific the 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.

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

• The line item includes pricing_blocklists, showing the taxes that are blocked from being automatically applied.
• 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.

{
  "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
    }
  }
}

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

• Specify pricing_options for Square-applied taxes.
• For the specific line item, add pricing_blocklists and include the ID of the CatalogTax object to block it from having taxes applied by Square.

Make sure you provide the coffee item variation ID, location ID, and ID of the tax (you previously created) that you want to block from application by Square.

In the response, verify the pricing calculations. Because you blocked the line item from having taxes applied by Square, there are no taxes applied. The following is an example response fragment:

{
  "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
    }
  }
}