Override Default Checkout Behavior with APIs

API overrides enable integrators to bypass certain Bold Checkout behavior in favor of custom functionality.

The following overrides are available to integration developers:

• address_validate
• discount
• inventory
• shipping
• tax

This document explains the structure of overrides and how to implement them. For more information about overrides in general, refer to Checkout Overrides

note

API overrides differ in several ways from plugin overrides. Refer to API overrides and plugin overrides for more information.

How API overrides work

The following diagram and steps show an example of triggering a tax override.

1. When a customer proceeds to checkout, a call to the Initialize Order endpoint begins the checkout process.
2. Bold Checkout finds the override registered for the shop and associates it with the order.
3. As the customer proceeds through the checkout and enters their address information, the store makes a call to the Generate Taxes endpoint. This triggers the tax override.
4. Instead of using Bold Checkout functionality to calculate taxes, Bold Checkout makes a call to the integration's tax override URL, which was provided in the Create API Override call.
5. The integration performs custom tax calculations and responds to Bold Checkout with the appropriate tax information.
6. Bold Checkout updates and returns the application state.

Setting up an API override

API overrides are set at the store level. You must complete these steps for each store that installs the integration. Bold recommends making these calls during or just after the integration installation process to ensure all orders behave as expected.

With your API override installed on a store, Bold sets the override on each new order created by an Initialize Order call.

Use the following steps to create and configure an API override.

Prerequisites

API overrides require credentials, generated based on the type of integration they are associated with.

• For private integrations, refer to the Quick Start guide.
• For public integrations, refer to the Build Public Integrations guide.

You will need this API access token for the next step.

Create an API override

To set up an API override, call the Create API Override endpoint. Provide the override_type, url, and shared_secret for the override. This URL is the destination that Bold will call when the override is triggered. The shared secret is any string that is defined by the creator of API override. You may have one or multiple shared secrets.

The following code snippet shows an example of this call:

curl --request POST 'https://api.boldcommerce.com/checkout/shop/{shop_identifier}/overrides' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "override_type": "address_validate",
         "url": "example_override_url.com",
         "shared_secret": "example_shared_secret"
     }'

About the shared secret

In order for Bold to securely sign all requests to your override URL, you must provide your shared secret each time you create an API override. The shared secret prevents unauthorized requests to your override URL.

Bold Checkout uses your shared secret and the time the override request is sent to calculate a SHA-256 hash, which is passed to you in the header of each request as a signature.

note

Bold includes the time the override is sent in the x-bold-date header, using RFC822 format. The signature is included in the Authorization header.

Verify the response

When you receive an API override request, the headers of the request contain a signature and other important information in the following format:

Authorization: Signature keyId="api_secret", algorithm="hmac-sha256", signature="MXpePJs99hUcgzst2IDOU3HMj0kmcxyLc1ZpaWq3OeU", headers="(request-target) x-bold-date"
X-Bold-Api-Authorization: Signature keyId="api_secret", algorithm="hmac-sha256", signature="MXpePJs99hUcgzst2IDOU3HMj0kmcxyLc1ZpaWq3OeU", headers="(request-target) x-bold-date"

In order to verify that an override request is indeed from Bold, you can use the x-bold-date and your stored shared secret to calculate a SHA-256 hash and ensure it matches what was sent in the Authorization and X-Bold-Api-Authorization headers. These headers should contain the same value.

The following JavaScript snippet shows an example of programmatically verifying that the request you receive is indeed from Bold:

const httpSignature = require("http-signature");
const verify_signature = (req, res, next) => {
  // Verify Bold Checkout's HTTP signature.
  try {
    // Avoid failing validation if date header contains `request-target`.
    const tempURL = req.url;
    req.url = req.originalUrl;
    const parsed = httpSignature.parse(req);
    req.url = tempURL;

    // Verify that the request originated from Bold Checkout.
    if (httpSignature.verifyHMAC(parsed, process.env.SHARED_SECRET)) {
      next();
    } else {
      res.status(401).end();
    }
  } catch (error) {
    res.status(401).end();
  }
};
module.exports = {
  verify_signature,
};

Requests and responses

The following sections outline the requests that are sent from Bold to the API override URL and the responses that Bold expects back.

note

The format of these requests and responses is identical between API overrides and plugin overrides.

address_validate

Address validate override request

When the address_validate override is triggered (where Bold Checkout would normally perform an address operation), Bold sends an HTTP POST request to the url provided by the integration.

The following table describes the fields that Bold sends in this request:

Key	Type	Description
first_name	string	First name.
last_name	string	Last name.
company	string	Company name.
address	string	Street number and name.
address2	string	Extended address information.
city	string	City name.
province	string	Province or state.
province_code	string	Province or state code, using ISO-3166 standards.
country	string	Country name.
country_code	string	Country code, using ISO-3166 standards.
postal_code	string	Postal or zip code.
phone	string	Phone number.

The following snippet shows an example of the request body sent by Bold Checkout:

{
  "first_name": "John",
  "last_name": "Smith",
  "company": "",
  "address": "123 Fake St.",
  "address2": "Unit B",
  "city": "Winnipeg",
  "province": "Manitoba",
  "province_code": "MB",
  "country": "Canada",
  "country_code": "CA",
  "postal_code": "R3Y0L6",
  "phone": "8005550100"
}

Address validate override response

After the integration validates the address, it must respond to Bold with information about the validation.

The following table describes the fields that Bold Checkout expects in this response:

Key	Type	Description
valid	boolean	Whether the address is valid.
errors[].field	string	The input field which the error corresponds to.
errors[].error_message	string	The error message to display.

The following snippet shows an example of the response body sent to Bold Checkout:

{
  "valid": false,
  "errors": [
    {
      "field": "postal_code",
      "error_message": "Code not valid for country and province"
    }
  ]
}

discount

Discount override request

When the discount override is triggered (where Bold Checkout would normally perform a discount operation), Bold sends an HTTP POST request to the url provided by the integration.

The following table describes the fields that Bold sends in this request:

Key	Type	Description
discount	string	Discount code to be verified. Bold trims this string to remove leading and trailing spaces before sending the override request to the plugin.
platform_id	string	Domain of the shop.
platform	string	Platform type.
email_address	string	Customer email address.
order_id	integer	Unique identifier for the order.
finalize	boolean	true when the order is being finalized, false otherwise. Use this to track discount code usage.
shipping_country_code	string	Country code of the destination address, using ISO-3166 standards.
variants_in_cart	array	All variant IDs included in the cart.

The following snippet shows an example of the request body sent by Bold Checkout:

{
  "discount": "SUMMER2022",
  "platform_id": "store-CdDjsGr8RB.mybigcommerce.com",
  "platform": "bigcommerce",
  "email_address": "[email protected]",
  "order_id": 123456,
  "finalize": true,
  "shipping_country_code": "CA",
  "variants_in_cart": [5243892, 234579234, 23457345]
}

Discount override response

Discount override types

There can be several kinds of discount overrides. The following table shows them all:

Kind of discount	Description
FixedAmount	Discount an order by a fixed amount (e.g., $5.00 OFF).
Percentage	Discount an order by a percentage (e.g., 10% OFF).
FreeShipping	Discount an order by discounting the shipping cost by the total shipping cost.
ShippingFixedAmount	Discount an order by discounting the shipping cost by a fixed amount.
ShippingPercentage	Discount an order by discounting the shipping cost by a percentage.
FixedExceptProductsInList	Discount an order's products except the provided list of products by a fixed amount. Requires an itemKeys array to list the line item keys which the discount does not apply to.
PercentageExceptProductsInList	Discount an order's products except the provided list of products by a percentage. Requires an itemKeys array to list the line item keys which the discount does not apply to.
FixedProductsInList	Discount an order's products that are in the provided list of products by a fixed amount. Requires an itemKeys array to list the line item keys which the discount applies to.
PercentageProductsInList	Discount an order's products that are in the provided list of products by a percentage. Requires an itemKeys array to list the line item keys which the discount applies to.

Discount override conditions

The discount can also provide the following conditions:

Type	Description
emailEquals	The email provided MUST match the response's email.
cartTotalMin	Cart total MUST be at least the provided minimum.
shippingCostMax	The maximum allowed shipping cost for the override to be applied.
shippingCostMin	The minimum allowed shipping cost for the override to be applied.
inCountries	Shipping country must be in the list of countries.
useLimitPerCustomer	Limit the amount of times a discount can be used, per email.
use_limit_reached	A boolean that indicates whether the use limit has been reached.

After the integration performs its own discount functionality, it must respond to Bold with information about the discount.

The following table describes the fields that Bold Checkout expects in this response:

Key	Type	Description
found	boolean	Whether the discount is found.
valid	boolean	Whether the discount is valid.
kind	string	Type of discount to register. See Discount override types.
amount	integer	Discount amount.
conditions	array	Array of conditions. See Discount override conditions.
params	array	Parameters for discount (if any). See Discount override types.
message	string	Message for discount (displayed on front end).
tag_line	string	Should always be set to Discount.

The following snippet shows an example of the response body sent to Bold Checkout:

{
  "found": true,
  "valid": true,
  "kind": "FixedExceptProductsInList",
  "amount": 15000, // $150.00
  "conditions": [
    {
      "name": "cartTotalMin",
      "params": {
        "value": "1"
      }
    }
  ],
  "params": [
    {
      "itemKeys": [13333646573679, 13332992098415, 13332775141487]
    }
  ],
  "message": "SomeMessage",
  "tag_line": "Discount"
}

inventory

Inventory override request

When the inventory override is triggered (where Bold Checkout would normally perform an inventory check), Bold sends an HTTP POST request to the url provided by the integration.

Checkout can request an inventory check in two different order stages:

• initial is a preliminary inventory check, typically at (but not restricted to) the beginning of the Checkout flow.
• final indicates that the order is being finalized and that the customer intends to follow through with the transaction.

Line items may use different identifiers depending on the platform or the product setup on the platform. Either the item sku or the variant_id may be empty depending on the platform.

The shipping address may be missing if it has not been set on the order when the inventory check occurs.

The following table describes the fields that Bold sends in this request:

Key	Type	Description
type	string	An enum indicating the stage of the order in Checkout. Possible values are initial and final.
items[].sku	string	This line item's stock keeping unit.
items[].quantity	string	The order quantity of the item.
items[].id	integer	The unique identifier for the line item used by Checkout.
items[].variant_id	string	The variant id of the item on the platform.
items[].line_item_properties	object	An object containing custom key-value pairs assigned to the line item.
order_id	string	A unique identifier that is safe for public consumption.
shipping_address.first_name	string	First name of the shipping recipient.
shipping_address.last_name	string	Last name of the shipping recipient.
shipping_address.company	string	Company name of the shipping address.
shipping_address.address1	string	Line 1 of the shipping address.
shipping_address.address2	string	Line 2 of the shipping address.
shipping_address.phone	string	Phone number of the shipping address.
shipping_address.city	string	City of the shipping address.
shipping_address.province	string	Province or state of the shipping address.
shipping_address.province_code	string	Province or state code of the shipping address.
shipping_address.country	string	Country of the shipping address.
shipping_address.country_code	string	Country code of the shipping address, using ISO-3166 standards.
shipping_address.postal_code	string	Postal or zip code of the shipping address.
note_attributes	object	Extra data added to the order and pushed to the platform, defined with key and value pairs. Visible to the merchant.
cart_params	object	Metadata about the order, defined with key and value pairs.

The following snippet shows an example of the request body sent by Bold Checkout:

{
  "type": "initial",
  "items": [
    {
      "sku": "AABBCC",
      "quantity": 1,
      "id": 100200,
      "variant_id": "77",
      "line_item_properties": {
        "age_restricted": true
      }
    }
  ],
  "order_id": "BasrFjrCj6L2Mi2SvUjdAMwE8ERNsOdOKhqkNpw0EHa3i7g8wdfOF0uJyyHSxcI0",
  "shipping_address": {
    "address1": "123 Fake Street",
    "address2": "",
    "city": "Destination City",
    "province": "Manitoba",
    "province_code": "MB",
    "country": "Canada",
    "country_code": "CA",
    "postal_code": "H0H 1H1"
  }
}

Inventory override response

After the integration completes its inventory check, it must respond to Bold with information about the stock availability.

Responding with a type of final causes Bold Checkout to cache the result, in the case of one or more out-of-stock items, so that subsequent inventory checks for this order will use the cached result instead of making another API call.

If an item's available_quantity is less than its order quantity, Bold Checkout considers the inventory check to have failed. For the initial check, the storefront has the discretion to proceed with Checkout or halt it. For the final check, Bold Checkout prevents the order from being completed.

The following table describes the fields that Bold Checkout expects in this response:

Key	Type	Description
type	string	The stage of the order in Checkout.
items[].sku	string	The item's stock keeping unit.
items[].variant_id	string	The item's variant id on the platform.
items[].quantity	integer	The item's quantity on the order.
items[].available_quantity	integer	The item's quantity in stock.

The following snippet shows an example of the response body sent to Bold Checkout:

{
  "type": "initial",
  "items": [
    {
      "sku": "AABBCC",
      "variant_id": "77",
      "quantity": 1,
      "available_quantity": 0
    }
  ]
}

shipping

Shipping override request

When the shipping override is triggered (where Bold Checkout would normally perform a shipping operation), Bold sends an HTTP POST request to the url provided by the integration.

The following table describes the fields that Bold sends in this request:

Key	Type	Description
source_address.address1	string	Line 1 of the source address.
source_address.address2	string	Line 2 of the source address.
source_address.city	string	City of the source address.
source_address.province	string	Province or state of the source address.
source_address.province_code	string	Province or state code of the source address, using ISO-3166.
source_address.country	string	Country of the source address.
source_address.country_code	string	Country code of the source address, using ISO-3166 standards.
source_address.postal_code	string	Postal or zip code of the source address.
destination_address.address1	string	Line 1 of the destination address.
destination_address.address2	string	Line 2 of the destination address.
destination_address.city	string	City of the destination address.
destination_address.province	string	Province or state of the destination address.
destination_address.province_code	string	Province or state code of the destination address, using ISO-3166.
destination_address.country	string	Country of the destination address.
destination_address.country_code	string	Country code of the destination address, using ISO-3166 standards.
destination_address.postal_code	string	Postal or zip code of the destination address.
cart	array	The cart array that contains line items.
cart[].title	string	Name of the line item. Displayed in Bold Checkout admin and on platform.
cart[].product_title	string	Name of the product.
cart[].variant_title	string	Name of the variant.
cart[].image	url	URL for the line item's image asset.
cart[].properties	object	Extra metadata about the line item.
cart[].description	string	Product description.
cart[].quantity	integer	The quantity of the line item.
cart[].price	integer	The price of the product in cents.
cart[].total_price	integer	The price of the product after being multiplied by quantity in cents.
cart[].line_item_id	integer	Index of the line item in the cart array.
cart[].line_item_key	string	Unique identifier of this line item.
cart[].platform_variant	object	Platform specific data related to the variant of this line item.
cart[].includes_tax	boolean	Whether taxes are included in the price of the line item.
cart[].weight	integer	Weight of the line item.
cart[].platform_variant_id	integer	Platform specific ID of the variant associated with this line item.
cart[].platform_product_id	integer	Platform specific ID of this product.
cart[].sku	string	This line item's stock keeping unit.
note_attributes	object	Extra data added to the order and pushed to the platform, defined with key and value pairs. Visible to the merchant.
cart_params	object	Metadata about the order, defined with key and value pairs.

The following snippet shows an example of the request body sent by Bold Checkout:

{
  "cart": [
    {
      "id": 1000,
      "title": "Test Product - Small / Red / Cotton",
      "product_title": "Test Product",
      "variant_title": "Small / Red / Cotton",
      "image": "https://example.com/thing.jpg",
      "properties": {
        "gift wrap": "yes"
      },
      "description": "Test product description.",
      "quantity": 2,
      "price": 5000, //$50.00
      "total_price": 10000, //$100.00
      "visible": 1,
      "available_quantity": 0,
      "updated_quantity": 0,
      "line_item_id": 0,
      "line_item_key": "AABBCC123",
      "inventory_policy": null,
      "platform_variant": {
        "id": 123456789,
        "barcode": "",
        "compare_at_price": null,
        "fulfillment_service": "manual",
        "grams": 10,
        "inventory_management": "shopify",
        "inventory_policy": "deny",
        "option1": "Small",
        "option2": "Red",
        "option3": "Cotton",
        "position": 1,
        "price": 50, //$50.00
        "product_id": 987654321,
        "requires_shipping": 1,
        "sku": "TEST-SM-RED-CTN-01",
        "taxable": 1,
        "title": "Small / Red / Cotton",
        "inventory_quantity": 100,
        "old_inventory_quantity": 100,
        "image_id": null,
        "created_at": "2018-09-21 10:53:25",
        "updated_at": "2018-09-21 10:53:25",
        "inventory_item_id": 0,
        "product": {
          "id": 987654321,
          "myshopify_domain": "example.myshopify.com",
          "handle": "test-product",
          "product_type": "Test",
          "published_scope": "web",
          "template_suffix": null,
          "title": "Test Product",
          "vendor": "Test Vendor",
          "tags": "Test, Vintage",
          "featured_image_id": 11111111111,
          "created_at": "2018-09-21 10:53:24",
          "updated_at": "2018-09-21 10:53:28"
        }
      },
      "includes_tax": 0,
      "weight": 10,
      "note": "",
      "platform_variant_id": 123456789,
      "platform_product_id": 987654321,
      "sku": "TEST-SM-RED-CTN-01"
    }
  ],
  "source_address": {
    "address1": "123 Warehouse Road",
    "address2": "",
    "city": "Warehouse City",
    "province": "Manitoba",
    "province_code": "MB",
    "country": "Canada",
    "country_code": "CA",
    "postal_code": "H0H 0H0"
  },
  "destination_address": {
    "address1": "123 Fake Street",
    "address2": "",
    "city": "Destination City",
    "province": "Manitoba",
    "province_code": "MB",
    "country": "Canada",
    "country_code": "CA",
    "postal_code": "H0H 1H1"
  }
}

Shipping override response

After the integration performs its custom shipping functionality, it must respond to Bold with information about the shipping rates.

The following table describes the fields that Bold Checkout expects in this response:

Key	Type	Description
name	string	The name of the shipping provider.
rates	array	Array of shipping options returned from the 3rd party resource.
line_text	array	Describes the shipping option (e.g. Expedited Shipping).
value	float	Value of shipping rate in dollars (e.g. 10.50 = $10.50).
code	string	A unique identifier for the shipping option.

The following snippet shows an example of the response body sent to Bold Checkout:

{
  "name": "Left-turn Shipping",
  "rates": [
    {
      "line_text": "Overnight Express",
      "value": 15,
      "code": "EXP"
    },
    {
      "line_text": "Economy (5-7 Business Days)",
      "value": 10.5,
      "code": "ECO"
    }
  ]
}

tax

Tax override request

When the tax override is triggered (where Bold Checkout would normally perform a tax calculation), Bold sends an HTTP POST request to the url provided by the integration.

The following table describes the fields that Bold sends in this request:

Key	Type	Description
store_addresses	array	Array of available potential source addresses.
store_addresses[].province	string	Province or state code of the available source address, using ISO-3166.
store_addresses[].country	string	Country code of the available source address, using ISO-3166 standards.
store_addresses[].postal_code	string	Postal or zip code of the available source address.
shipping_address.address	string	Line 1 of the destination address.
shipping_address.city	string	City of the destination address.
shipping_address.province	string	Province or state code of the destination address, using ISO-3166.
shipping_address.country	string	Country code of the destination address, using ISO-3166 standards.
shipping_address.postal_code	string	Postal or zip code of the destination address.
warehouse_address.address	string	Line 1 of the warehouse that will ship the order.
warehouse_address.address2	string	Line 2 of the warehouse that will ship the order.
warehouse_address.city	string	City of the warehouse that will ship the order.
warehouse_address.province	string	Province or state of the warehouse that will ship the order.
warehouse_address.province_code	string	Province or state code of the warehouse that will ship the order, using ISO-3166 standards.
warehouse_address.country	string	Country of the warehouse that will ship the order.
warehouse_address.country_code	string	Country code of the warehouse that will ship the order, using ISO-3166 standards.
warehouse_address.postal_code	string	Postal or zip code of the warehouse that will ship the order.
sub_total	boolean	Apply taxes to the subtotal.
shipping_total	boolean	Apply taxes to the shipping total.
shipping_lines.selected_shipping_line	object	The selected shipping line for the order.
shipping_lines.selected_shipping_line.id	string	The unique identifier for the selected shipping line.
shipping_lines.selected_shipping_line.description	string	The selected shipping line description.
shipping_lines.selected_shipping_line.amount	integer	The amount of the selected shipping line, in base currency units, using ISO-4217 standards.
shipping_lines.selected_shipping_line.code	string	The unique identifier code for the selected shipping line.
shipping_lines.available_shipping_lines	array	Available shipping lines that are configured in Checkout.
shipping_lines.available_shipping_lines[].id	string	The unique identifier for the avalable shipping line.
shipping_lines.available_shipping_lines[].description	string	The available shipping line description.
shipping_lines.available_shipping_lines[].amount	integer	The amount of the available shipping line, in base currency units, using ISO-4217 standards.
shipping_lines.available_shipping_lines[].code	string	The unique identifier code for the available shipping line.
cart	array	The cart array that contains line items.
cart[].title	string	Name of the line item. Displayed in Bold Checkout admin and on platform.
cart[].product_title	string	Name of the product.
cart[].variant_title	string	Name of the variant.
cart[].image	url	URL for the line item's image asset.
cart[].properties	object	Extra metadata about the line item.
cart[].description	string	Product description.
cart[].quantity	integer	The quantity of the line item.
cart[].price	integer	The price of the product in cents.
cart[].total_price	integer	The price of the product after being multiplied by quantity in cents.
cart[].line_item_id	integer	Index of the line item in the cart array.
cart[].line_item_key	string	Unique identifier of this line item.
cart[].platform_variant	object	Platform specific data related to the variant of this line item.
cart[].includes_tax	boolean	Whether taxes are included in the price of the line item.
cart[].weight	integer	Weight of the line item.
cart[].platform_variant_id	integer	Platform specific ID of the variant associated with this line item.
cart[].platform_product_id	integer	Platform specific ID of this product.
cart[].sku	string	This line item's stock keeping unit.
note_attributes	object	Extra data added to the order and pushed to the platform, defined with key and value pairs. Visible to the merchant.
cart_params	object	Metadata about the order, defined with key and value pairs.

The following snippet shows an example of the request body sent by Bold Checkout:

{
  "store_addresses": [
    {
      "province": "MB",
      "country": "CA",
      "postal_code": "R2G4W3"
    }
  ],
  "shipping_address": {
    "address": "50 Fultz Blvd",
    "city": "Winnipeg",
    "province": "MB",
    "country": "CA",
    "postal_code": "R2K3S4"
  },
  "sub_total": 1,
  "shipping_total": 1,
  "warehouse_address": {
    "address1": "123 Warehouse Road",
    "address2": "",
    "city": "Warehouse City",
    "province": "Manitoba",
    "province_code": "MB",
    "country": "Canada",
    "country_code": "CA",
    "postal_code": "H0H 0H0"
  },
  "shipping_lines": {
    "selected_shipping_line": {
      "id": "0",
      "description": "Test rate",
      "amount": 500,
      "code": "TR-5"
    },
    "available_shipping_lines": [
      {
        "id": "0",
        "description": "Test rate",
        "amount": 500,
        "code": "TR-5"
      }
    ]
  },
  "cart": [
    {
      "id": 1000,
      "title": "Test Product - Small / Red / Cotton",
      "product_title": "Test Product",
      "variant_title": "Small / Red / Cotton",
      "image": "https://example.com/thing.jpg",
      "properties": {
        "gift wrap": "yes"
      },
      "description": "Test product description.",
      "quantity": 2,
      "price": 5000, //$50.00
      "total_price": 10000, //$100.00
      "visible": 1,
      "available_quantity": 0,
      "updated_quantity": 0,
      "line_item_id": 0,
      "line_item_key": "AABBCC123",
      "inventory_policy": null,
      "platform_variant": {
        "id": 123456789,
        "barcode": "",
        "compare_at_price": null,
        "fulfillment_service": "manual",
        "grams": 10,
        "inventory_management": "shopify",
        "inventory_policy": "deny",
        "option1": "Small",
        "option2": "Red",
        "option3": "Cotton",
        "position": 1,
        "price": 50, //$50.00
        "product_id": 987654321,
        "requires_shipping": 1,
        "sku": "TEST-SM-RED-CTN-01",
        "taxable": 1,
        "title": "Small / Red / Cotton",
        "inventory_quantity": 100,
        "old_inventory_quantity": 100,
        "image_id": null,
        "created_at": "2018-09-21 10:53:25",
        "updated_at": "2018-09-21 10:53:25",
        "inventory_item_id": 0,
        "product": {
          "id": 987654321,
          "myshopify_domain": "example.myshopify.com",
          "handle": "test-product",
          "product_type": "Test",
          "published_scope": "web",
          "template_suffix": null,
          "title": "Test Product",
          "vendor": "Test Vendor",
          "tags": "Test, Vintage",
          "featured_image_id": 11111111111,
          "created_at": "2018-09-21 10:53:24",
          "updated_at": "2018-09-21 10:53:28"
        }
      },
      "includes_tax": 0,
      "weight": 10,
      "note": "",
      "platform_variant_id": 123456789,
      "platform_product_id": 987654321,
      "sku": "TEST-SM-RED-CTN-01"
    }
  ]
}

Tax override response

After the integration performs its custom tax calculations, it must respond to Bold with information about the new values.

Line item level taxes are optional, and any line item on the order with no line item level tax specified will have its tax calculated using the sub_total tax rates.

The following table describes the fields that Bold Checkout expects in this response:

Key	Type	Description
line_items	object	Taxes that apply to individual line items.
shipping	array	Taxes that apply to the shipping total.
sub_total	array	Taxes that apply to the order subtotal.
shipping.name and sub_total.name	string	Tax line name (e.g., GST).
shipping.rate and sub_total.rate	string	Decimal rate of taxation (e.g., 0.05 is 5%).

The following table describes the line_items object:

Key	Type	Description
{line_item_key}	array	The key for this array must be one of the line item keys on the order.
{line_item_key}[].name	string	Tax line name (e.g., GST).
{line_item_key}[].rate	string	Decimal rate of taxation (e.g., 0.05 is 5%).
{line_item_key}[].amount	number	Optional. The amount of tax per quantity of this line item. Represented in base currency. (e.g., $5 is represented as 500).

If both {line_item_key}[].rate and {line_item_key}[].amount are specified, then the rate is only used for informational/display purposes and calculations rely on the amount instead of the rate.

The following snippet shows an example of the response body sent to Bold Checkout:

{
  "line_items": {
    "nq3iptIy6vYb0MKo": [
      {
        "rate": 0.05,
        "name": "GST"
        "amount": 14
      }
    ],
    "DusgQ09jGVDQ5GxC": [
      {
        "rate": 0.05,
        "name": "GST"
      },
      {
        "rate": 0.08,
        "name": "PST"
      },
      {
        "rate": 0.06,
        "name": "PDQ"
      }
    ]
  },
  "shipping": [
    {
      "rate": 0.01,
      "name": "VAT"
    }
  ],
  "sub_total": [
    {
      "rate": 0.05,
      "name": "GST"
    },
    {
      "rate": 0.08,
      "name": "PST"
    }
  ]
}