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.

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 (doesn't 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 (doesn't 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

  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 is scoped to LINE_ITEM. Individual line items to which the tax applies must include applied_taxes with a reference the tax defined. The following example shows two line items and the tax applies only to the second line item:

  Create order

  cURL

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

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

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:

• Walkthrough: Automatically Apply Preconfigured Discounts to an Order
• Walkthrough: Automatically Apply Preconfigured Taxes to an Order

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

For more information, see the blocking taxes example in Walkthrough: Automatically Apply Preconfigured Taxes to an Order and the blocking discounts example in Walkthrough: Automatically Apply Preconfigured Discounts to an Order.

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: Automatically Apply Preconfigured Discounts to an Order and the blocking taxes example in Walkthrough: Automatically Apply Preconfigured Taxes to an Order.