Skip to main content

Implement API Overrides

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. Refer to the Making API Calls guide to obtain this credential

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:

KeyTypeDescription
first_namestringFirst name.
last_namestringLast name.
companystringCompany name.
addressstringStreet number and name.
address2stringExtended address information.
citystringCity name.
provincestringProvince or state.
province_codestringProvince or state code, using ISO-3166 standards.
countrystringCountry name.
country_codestringCountry code, using ISO-3166 standards.
postal_codestringPostal or zip code.
phonestringPhone 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:

KeyTypeDescription
validbooleanWhether the address is valid.
errors[].fieldstringThe input field which the error corresponds to.
errors[].error_messagestringThe 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:

KeyTypeDescription
discountstringDiscount code to be verified. Bold trims this string to remove leading and trailing spaces before sending the override request to the plugin.
platform_idstringDomain of the shop.
platformstringPlatform type.
email_addressstringCustomer email address.
order_idintegerUnique identifier for the order.
finalizebooleantrue when the order is being finalized, false otherwise. Use this to track discount code usage.
shipping_country_codestringCountry code of the destination address, using ISO-3166 standards.
variants_in_cartarrayAll 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 discountDescription
FixedAmountDiscount an order by a fixed amount (e.g., $5.00 OFF).
PercentageDiscount an order by a percentage (e.g., 10% OFF).
FreeShippingDiscount an order by discounting the shipping cost by the total shipping cost.
ShippingFixedAmountDiscount an order by discounting the shipping cost by a fixed amount.
ShippingPercentageDiscount an order by discounting the shipping cost by a percentage.
FixedExceptProductsInListDiscount 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.
PercentageExceptProductsInListDiscount 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.
FixedProductsInListDiscount 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.
PercentageProductsInListDiscount 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:

TypeDescription
emailEqualsThe email provided MUST match the response's email.
cartTotalMinCart total MUST be at least the provided minimum.
shippingCostMaxThe maximum allowed shipping cost for the override to be applied.
shippingCostMinThe minimum allowed shipping cost for the override to be applied.
inCountriesShipping country must be in the list of countries.
useLimitPerCustomerLimit the amount of times a discount can be used, per email.
use_limit_reachedA 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:

KeyTypeDescription
foundbooleanWhether the discount is found.
validbooleanWhether the discount is valid.
kindstringType of discount to register. See Discount override types.
amountintegerDiscount amount.
conditionsarrayArray of conditions. See Discount override conditions.
paramsarrayParameters for discount (if any). See Discount override types.
messagestringMessage for discount (displayed on front end).
tag_linestringShould 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:

KeyTypeDescription
typestringAn enum indicating the stage of the order in Checkout. Possible values are initial and final.
items[].skustringThis line item's stock keeping unit.
items[].quantitystringThe order quantity of the item.
items[].idintegerThe unique identifier for the line item used by Checkout.
items[].variant_idstringThe variant id of the item on the platform.
items[].line_item_propertiesobjectAn object containing custom key-value pairs assigned to the line item.
order_idstringA unique identifier that is safe for public consumption.
shipping_address.first_namestringFirst name of the shipping recipient.
shipping_address.last_namestringLast name of the shipping recipient.
shipping_address.companystringCompany name of the shipping address.
shipping_address.address1stringLine 1 of the shipping address.
shipping_address.address2stringLine 2 of the shipping address.
shipping_address.phonestringPhone number of the shipping address.
shipping_address.citystringCity of the shipping address.
shipping_address.provincestringProvince or state of the shipping address.
shipping_address.province_codestringProvince or state code of the shipping address.
shipping_address.countrystringCountry of the shipping address.
shipping_address.country_codestringCountry code of the shipping address, using ISO-3166 standards.
shipping_address.postal_codestringPostal or zip code of the shipping address.
note_attributesobjectExtra data added to the order and pushed to the platform, defined with key and value pairs. Visible to the merchant.
cart_paramsobjectMetadata 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:

KeyTypeDescription
typestringThe stage of the order in Checkout.
items[].skustringThe item's stock keeping unit.
items[].variant_idstringThe item's variant id on the platform.
items[].quantityintegerThe item's quantity on the order.
items[].available_quantityintegerThe 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:

KeyTypeDescription
source_address.address1stringLine 1 of the source address.
source_address.address2stringLine 2 of the source address.
source_address.citystringCity of the source address.
source_address.provincestringProvince or state of the source address.
source_address.province_codestringProvince or state code of the source address, using ISO-3166.
source_address.countrystringCountry of the source address.
source_address.country_codestringCountry code of the source address, using ISO-3166 standards.
source_address.postal_codestringPostal or zip code of the source address.
destination_address.address1stringLine 1 of the destination address.
destination_address.address2stringLine 2 of the destination address.
destination_address.citystringCity of the destination address.
destination_address.provincestringProvince or state of the destination address.
destination_address.province_codestringProvince or state code of the destination address, using ISO-3166.
destination_address.countrystringCountry of the destination address.
destination_address.country_codestringCountry code of the destination address, using ISO-3166 standards.
destination_address.postal_codestringPostal or zip code of the destination address.
cartarrayThe cart array that contains line items.
cart[].titlestringName of the line item. Displayed in Bold Checkout admin and on platform.
cart[].product_titlestringName of the product.
cart[].variant_titlestringName of the variant.
cart[].imageurlURL for the line item's image asset.
cart[].propertiesobjectExtra metadata about the line item.
cart[].descriptionstringProduct description.
cart[].quantityintegerThe quantity of the line item.
cart[].priceintegerThe price of the product in cents.
cart[].total_priceintegerThe price of the product after being multiplied by quantity in cents.
cart[].line_item_idintegerIndex of the line item in the cart array.
cart[].line_item_keystringUnique identifier of this line item.
cart[].platform_variantobjectPlatform specific data related to the variant of this line item.
cart[].includes_taxbooleanWhether taxes are included in the price of the line item.
cart[].weightintegerWeight of the line item.
cart[].platform_variant_idintegerPlatform specific ID of the variant associated with this line item.
cart[].platform_product_idintegerPlatform specific ID of this product.
cart[].skustringThis line item's stock keeping unit.
note_attributesobjectExtra data added to the order and pushed to the platform, defined with key and value pairs. Visible to the merchant.
cart_paramsobjectMetadata 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:

KeyTypeDescription
namestringThe name of the shipping provider.
ratesarrayArray of shipping options returned from the 3rd party resource.
line_textarrayDescribes the shipping option (e.g. Expedited Shipping).
valuefloatValue of shipping rate in dollars (e.g. 10.50 = $10.50).
codestringA 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:

KeyTypeDescription
store_addressesarrayArray of available potential source addresses.
store_addresses[].provincestringProvince or state code of the available source address, using ISO-3166.
store_addresses[].countrystringCountry code of the available source address, using ISO-3166 standards.
store_addresses[].postal_codestringPostal or zip code of the available source address.
shipping_address.addressstringLine 1 of the destination address.
shipping_address.citystringCity of the destination address.
shipping_address.provincestringProvince or state code of the destination address, using ISO-3166.
shipping_address.countrystringCountry code of the destination address, using ISO-3166 standards.
shipping_address.postal_codestringPostal or zip code of the destination address.
warehouse_address.addressstringLine 1 of the warehouse that will ship the order.
warehouse_address.address2stringLine 2 of the warehouse that will ship the order.
warehouse_address.citystringCity of the warehouse that will ship the order.
warehouse_address.provincestringProvince or state of the warehouse that will ship the order.
warehouse_address.province_codestringProvince or state code of the warehouse that will ship the order, using ISO-3166 standards.
warehouse_address.countrystringCountry of the warehouse that will ship the order.
warehouse_address.country_codestringCountry code of the warehouse that will ship the order, using ISO-3166 standards.
warehouse_address.postal_codestringPostal or zip code of the warehouse that will ship the order.
sub_totalbooleanApply taxes to the subtotal.
shipping_totalbooleanApply taxes to the shipping total.
shipping_lines.selected_shipping_lineobjectThe selected shipping line for the order.
shipping_lines.selected_shipping_line.idstringThe unique identifier for the selected shipping line.
shipping_lines.selected_shipping_line.descriptionstringThe selected shipping line description.
shipping_lines.selected_shipping_line.amountintegerThe amount of the selected shipping line, in base currency units, using ISO-4217 standards.
shipping_lines.selected_shipping_line.codestringThe unique identifier code for the selected shipping line.
shipping_lines.available_shipping_linesarrayAvailable shipping lines that are configured in Checkout.
shipping_lines.available_shipping_lines[].idstringThe unique identifier for the avalable shipping line.
shipping_lines.available_shipping_lines[].descriptionstringThe available shipping line description.
shipping_lines.available_shipping_lines[].amountintegerThe amount of the available shipping line, in base currency units, using ISO-4217 standards.
shipping_lines.available_shipping_lines[].codestringThe unique identifier code for the available shipping line.
cartarrayThe cart array that contains line items.
cart[].titlestringName of the line item. Displayed in Bold Checkout admin and on platform.
cart[].product_titlestringName of the product.
cart[].variant_titlestringName of the variant.
cart[].imageurlURL for the line item's image asset.
cart[].propertiesobjectExtra metadata about the line item.
cart[].descriptionstringProduct description.
cart[].quantityintegerThe quantity of the line item.
cart[].priceintegerThe price of the product in cents.
cart[].total_priceintegerThe price of the product after being multiplied by quantity in cents.
cart[].line_item_idintegerIndex of the line item in the cart array.
cart[].line_item_keystringUnique identifier of this line item.
cart[].platform_variantobjectPlatform specific data related to the variant of this line item.
cart[].includes_taxbooleanWhether taxes are included in the price of the line item.
cart[].weightintegerWeight of the line item.
cart[].platform_variant_idintegerPlatform specific ID of the variant associated with this line item.
cart[].platform_product_idintegerPlatform specific ID of this product.
cart[].skustringThis line item's stock keeping unit.
note_attributesobjectExtra data added to the order and pushed to the platform, defined with key and value pairs. Visible to the merchant.
cart_paramsobjectMetadata 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:

KeyTypeDescription
line_itemsobjectTaxes that apply to individual line items.
shippingarrayTaxes that apply to the shipping total.
sub_totalarrayTaxes that apply to the order subtotal.
shipping.name and sub_total.namestringTax line name (e.g., GST).
shipping.rate and sub_total.ratestringDecimal rate of taxation (e.g., 0.05 is 5%).

The following table describes the line_items object:

KeyTypeDescription
{line_item_key}arrayThe key for this array must be one of the line item keys on the order.
{line_item_key}[].namestringTax line name (e.g., GST).
{line_item_key}[].ratestringDecimal rate of taxation (e.g., 0.05 is 5%).
{line_item_key}[].amountnumberOptional. 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"
}
]
}