Apply Taxes, Discounts, and Service Charges

Applies to: Orders API | Catalog API

Learn how to apply taxes and discount to an order's price calculation.

Your application can apply taxes and discounts to orders and line items using either of the following options:

• Your business logic applies taxes and discounts to order line items.
• Square automatically applies taxes and discounts to order line items based on pricing rules and taxes that a seller defines in the catalog.

With the first option, the application of taxes and discounts is encoded in your application. With the second option, the application of taxes and discounts is controlled by a seller who provides the application rules in their catalog.

For information about how automatic taxes and discounts are applied by Square, see Discounts, service charges, and taxes.

Set a fixed tax percentage or discount amount for an order or to its items. The values can be defined in a CatalogTax, a CatalogDiscount, or your own business logic. After your application receives these values, add taxes or discounts attributes to the order with the values.

If you want to apply the values to individual line items, add applied_taxes or applied_discounts to those line items. If your taxes and discounts apply to the whole order, set the taxes or discounts scope to ORDER. Otherwise, set the scope to LINE_ITEM. Square calculates the tax and discounts to apply based on your values.

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

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

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

• The taxes that use business-logic-derived tax percentages.

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

• The discounts attributes that reference a predefined catalog discount to be applied.

  {
      "discounts": [
          {
              "uid": "EXPLICIT_DISCOUNT_UID",
              "scope": "ORDER",
              "catalog_object_id": "EXPLICIT_DISCOUNT_CATALOG_ID"
          }
      ]
  }

• The discounts attributes that define a business-logic-derived 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 values apply to all line items in the order. If the scope is limited to LINE_ITEM, individual line items must include applied_taxes or applied_discounts corresponding to the tax or discount that applies.

The following examples are 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

  cURL

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

• Create an order with explicit taxes scoped to line items - The following CreateOrder request defines a tax that's scoped to LINE_ITEM. Individual line items to which the tax applies must include applied_taxes with a reference to the defined tax. The following example shows two line items, with the tax applied only to the second line item:

  Create order

  cURL

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

You can create LINE_ITEM taxes and discounts ahead of time without referencing them from any line items. Later, when you're 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.

When you have ORDER-scoped taxes or discounts, you can add the pricing_blocklists attribute to individual line items to identify the ORDER-scoped discounts or taxes you don't 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"
            }
        ]
    }
}

When you set the pricing_options attribute for taxes or discounts to true, you are telling Square to calculate these values using pre-configured rules that you defined in the Square catalog. In this case, do not add Order taxes, discounts, applied_taxes, or applied_discounts fields. Instead, let Square add tax and discount amounts from your catalog rules

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 by setting the tax_ids attribute on the catalog item to be taxed. When your order line item refers to that taxed catalog item, Square taxes the order line item according to the catalog item tax_ids references.

To apply these preconfigured taxes and discounts to an order's price calculation, set the pricing_options (OrderPricingOptions) in the order to 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 order lines whose catalog items are taxable.

When you specify pricing_options, preconfigured taxes and discounts are automatically applied to an order's price calculation. You can 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 shouldn't be applied to an order based on the business or tax rules.

When creating an order, you can add pricing_blocklists (OrderLineItemPricingBlocklists) to individual line items to identify preconfigured discounts and taxes that you don't 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"
            }
        ]
    }
}

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

• Square-Applied Order Discounts
• Square-Applied Order Taxes