Pricing options configured for an order affect the order's price calculation. In this topic, use the pricing option to ask Square to apply taxes based on taxes preconfigured for the catalog items.
First, create the products you want to sell with taxes preconfigured. 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 preconfigured taxes. The taxes apply 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.
- A CatalogItem coffee object with the tax enabled.
Batch upsert catalog objects
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
.
Create order
In the response, notice how pricing calculations are affected by Square's application of taxes preconfigured for the item. For example:
- The line item includes
applied_taxes
, which identifies the taxes applied. - The order includes
taxes
, which provides details about the taxes applied.
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 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
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.
{
"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 theCatalogTax
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 created in step 1) that you want to block from application by Square.
Create order
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
}
}
}