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 specifiescatalog_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 specifiescatalog_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 anORDER
-scoped tax that applies to every line item in the order:Create order
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 toLINE_ITEM
. Individual line items to which the tax applies must includeapplied_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
Similarly, you can define
discounts
and addapplied_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'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 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.