Skip to main content

Plugin Actions

Plugins manipulate customer checkout via actions. This page includes details about the contents, effects, and scopes of each action.

To learn more about plugin behavior, refer to the conceptual Plugins page.

Action structure

Actions are structured as simple JSON objects, which your plugin includes in the response to a Checkout event.

Each action is included in the "actions" array and has the following keys:

KeyTypeDescription
typestringIdentifies the action to perform.
dataobjectContains parameters specific to the action type.

This code snippet demonstrates a response body that contains one action:

{
"success": true,
"actions": [
{
"type": "add_line_item_by_platform_variant",
"data": {
"platform_variant_id": 9153875214378,
"line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
"quantity": 1,
"properties": {
"gift_wrap": "yes"
},
"price": 1500,
"is_amendment": true
}
}
]
}

The "actions" array can contain any number of actions, including 0.

Actions and scopes

Each action has a corresponding scope that a merchant must approve.

Use the following table as a quick reference to determine which scopes your plugin requires.

ActionScope
add_cart_paramsmodify_order
add_disallowed_line_item_propertiesmodify_order
add_feeadd_fee
add_line_item_by_platform_variantadd_cart_item
add_line_item_propertymodify_cart
add_notemodify_order
add_note_attributemodify_order
add_shipping_lines_valuemodify_shipping
add_tagadd_tags
adjust_line_item_pricemodify_cart
change_billing_addressmodify_order
change_shipping_addressmodify_shipping_address
delay_payment_capturemodify_order
delay_platform_ordermodify_order
disable_order_confirmation_emailmodify_order_emails
discount_cartmodify_cart
discount_line_itemsmodify_cart
flag_order_as_bopismodify_shipping
multiply_shipping_lines_valuemodify_shipping
override_address_validateprovide_address_validation
override_discountprovide_discounts
override_inventoryprovide_shipping_rates
override_shippingprovide_shipping_rates
override_taxprovide_tax_rates
remove_feeadd_fee
remove_line_item_by_keymodify_cart
require_amendableamend_orders
set_currencymodify_currency
set_display_currencymodify_currency
set_gateway_currencymodify_currency
set_line_item_pre_ordermodify_cart
set_line_item_pricemodify_cart
set_line_item_shipping_addressmodify_cart
set_line_item_taxablemodify_cart
set_order_created_bymodify_order
set_payment_gatewaymodify_payment_gateways
set_shipping_ratemodify_shipping
set_split_order_conditionmodify_order

Shipping and address actions

add_shipping_lines_value

Adjusts the shipping total of an order by adding an amount to each of the order's shipping lines. You can reduce the shipping total by adding a negative amount. If lineText is provided, it replaces the existing description for each shipping rate in the order summary.

Scope

modify_shipping

Attributes
KeyTypeDescription
addintegerAmount to adjust the shipping total, in base currency units, using ISO-4217 standards.
lineTextstring(Optional) Description of the shipping cost for the order summary.
Example
{
"success": true,
"actions": [
{
"type": "add_shipping_lines_value",
"data": {
"add": 1250,
"lineText": "Expedited shipping"
}
}
]
}

change_shipping_address

Changes the shipping address on an order.

Scope

modify_shipping_address

Attributes
KeyTypeDescription
first_namestringFirst name.
last_namestringLast name.
companystringCompany name.
addressstringStreet number and name.
address2stringExtended address information.
phonestringPhone number.
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.
update_billingbooleanWhether to update the billing address to the previous shipping address.
different_billing_addressbooleanWhether to select “Use a different billing address” on the checkout page
note

When update_billing is set to true, this action triggers the billing_address_changed plugin event.

Example
{
"success": true,
"actions": [
{
"type": "change_shipping_address",
"data": {
"first_name": "John",
"last_name": "Doe",
"company": "Bold Commerce Ltd",
"address": "50 Fultz Blvd",
"address2": "Another Address Line",
"phone": "800-555-0100",
"city": "Winnipeg",
"province": "Manitoba",
"province_code": "MB",
"country": "Canada",
"country_code": "CA",
"postal_code": "R3Y 0L6",
"update_billing": true,
"different_billing_address": true
}
}
]
}

multiply_shipping_lines_value

Adjusts the shipping total of an order by multiplying each shipping line's value by a given amount. If lineText is provided, it replaces the existing description for each shipping rate in the order summary.

Scope

modify_shipping

Attributes
KeyTypeDescription
multiplierfloatThe amount by which to multiply the total shipping value on the order.
lineTextstring(Optional) Description of the shipping cost for the order summary.
Example
{
"success": true,
"actions": [
{
"type": "multiply_shipping_lines_value",
"data": {
"multiplier": 1.25,
"lineText": "The royal treatment"
}
}
]
}

set_shipping_rate

Sets the shipping rate on the order.

Scope

modify_shipping

Attributes
KeyTypeDescription
shipping_rate.priceintegerThe amount of the shipping rate, in base currency units, using ISO-4217 standards.
shipping_rate.namestringA human-readable name for the shipping rate.
shipping_rate.codestringA unique identifier for the shipping rate.
Example
{
"success": true,
"actions": [
{
"type": "set_shipping_rate",
"data": {
"shipping_rate": {
"price": 100,
"name": "Fixed rate",
"code": "fixed"
}
}
}
]
}

change_billing_address

Changes the billing address on the order. This action triggers the billing_address_changed plugin event.

Scope

modify_order

Attributes
KeyTypeDescription
first_namestringFirst name of the customer.
last_namestringLast name of the customer.
companystringCompany name of the billing address.
addressstringLine 1 of the billing address.
address2stringLine 2 of the billing address.
phonestringPhone number of the billing address.
citystringCity of the billing address.
provincestringProvince of the billing address.
province_codestringProvince code of the billing address.
countrystringCountry of the billing address.
country_codestringCountry code of the billing address.
postal_codestringPostal code of the billing address.
Example
{
"success": true,
"actions": [
{
"type": "change_billing_address",
"data": {
"first_name": "John",
"last_name": "Doe",
"company": "Bold Commerce Ltd",
"address": "50 Fultz Blvd",
"address2": "Another Address Line",
"phone": "800-555-0100",
"city": "Winnipeg",
"province": "Manitoba",
"province_code": "MB",
"country": "Canada",
"country_code": "CA",
"postal_code": "R3Y 0L6"
}
}
]
}

Metadata actions

add_cart_params

Adds cart parameters to the order. Cart parameters are key-value pairs that can consist of any metadata you want to add to the order.

note

Reusing the same keys for multiple add_cart_params actions overwrites existing values.

Scope

modify_order

Attributes
KeyTypeDescription
cart_paramsobjectObject containing one or more key-value pairs to be added to the order's cart parameters.
Example
{
"success": true,
"actions": [
{
"type": "add_cart_params",
"data": {
"cart_params": {
"custom_value": "test value"
}
}
}
]
}

add_note

Adds a note to the order.

Depending on the platform, notes may be shown in the platform UI. For example, in BigCommerce this note appears as a staff note attached to the order.

Scope

modify_order

Attributes
KeyTypeDescription
notestringThe note to be appended to the order.
Example
{
"success": true,
"actions": [
{
"type": "add_note",
"data": {
"note": "I'm a note"
}
}
]
}

add_note_attribute

Adds a new note attribute to the order. A note attribute is a key-value pair containing any kind of information about the order. Note attributes are useful for filtering orders by certain keys.

Scope

modify_order

Attributes
KeyTypeDescription
namestringName of the key for the new note attribute.
valuestringThe value of the new note attribute.
Example
{
"success": true,
"actions": [
{
"type": "add_note_attribute",
"data": {
"name": "example_attribute",
"value": "Some value"
}
}
]
}

add_tag

Adds a tag to the order.

Depending on the platform, tags may be shown in the platform UI.

Scope

add_tags

Attributes
KeyTypeDescription
namestringA tag which will be appended to the order.
Example
{
"success": true,
"actions": [
{
"type": "add_tag",
"data": {
"name": "this is a tag"
}
}
]
}

set_order_created_by

Sets the source application of the order, which helps to differentiate which orders originated from Checkout versus a plugin.

Scope

modify_order

Attributes
KeyTypeDescription
created_bystringThe originating system of the order.
Example
{
"success": true,
"actions": [
{
"type": "set_order_created_by",
"data": {
"created_by": "My Plugin"
}
}
]
}

Payment actions

delay_payment_capture

Delays the capture of payment on an order. The payment must be manually captured via the platform, Bold Checkout admin, or API call.

Using this action is equivalent to enabling Delayed Payment Capture in the Bold Checkout admin but does so for for an individual order instead of all orders.

Scope

modify_order

Parameters

None.

Example
{
"success": true,
"actions": [
{
"type": "delay_payment_capture",
"data": {}
}
]
}

set_payment_gateway

Sets the payment gateway that appears in Bold Checkout. Checkout displays only one payment gateway at a time.

Checkout displays a gateway based on the priority field and must be provided in ascending order. For example, a gateway with priority 1 is higher priority than a gateway with priority 2 or 3. Any gateways listed without a priority appear at the bottom of the list (in the order they were added).

The public_id for a specific gateway can be found by subscribing to the PaymentGateway plugin webhook. For more information, refer to the Plugin Webhooks page.

Scope

modify_payment_gateways

Attributes
KeyTypeDescription
gatewaysarrayList of gateways to prioritize.
public_idstringThe unique identifier for the gateway.
priorityinteger(Optional) The priority to assign to the specified gateway.
Example
{
"success": true,
"actions": [
{
"type": "set_payment_gateway",
"data": {
"gateways": [
{
"public_id": "gatewayId1",
"priority": 1
},
{
"public_id": "gatewayId2",
"priority": 2
}
]
}
}
]
}

Override actions

override_address_validate

Overrides the default Bold Checkout address validation behavior. For more information, refer to Override Default Checkout Behavior.

Scope

provide_address_validation

Attributes
KeyTypeDescription
urlstringURL endpoint for address validate override requests.
Example
{
"success": true,
"actions": [
{
"type": "override_address_validate",
"data": {
"url": "https://example.com/get-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"
}
]
}

override_discount

Overrides the default Bold Checkout discount behavior. For more information, refer to Override Default Checkout Behavior.

Scope

provide_discounts

Attributes
KeyTypeDescription
urlstringURL endpoint for discount override requests.
Example
{
"success": true,
"actions": [
{
"type": "override_discount",
"data": {
"url": "https://example.com/get-discount-rates"
}
}
]
}

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

override_inventory

Overrides the default Bold Checkout inventory check behavior. For more information, refer to Override Default Checkout Behavior.

Scope

provide_shipping_rates

Attributes
KeyTypeDescription
urlstringURL endpoint for inventory override requests.
Example
{
"success": true,
"actions": [
{
"type": "override_inventory",
"data": {
"url": "https://example.com/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
}
]
}

override_shipping

Overrides the default Bold Checkout shipping behavior. For more information, refer to Override Default Checkout Behavior.

Scope

provide_shipping_rates

Attributes
KeyTypeDescription
urlstringURL endpoint for shipping override requests.
Example
{
"success": true,
"actions": [
{
"type": "override_shipping",
"data": {
"url": "https://example.com/get-shipping-rates"
}
}
]
}

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

override_tax

Overrides the default Bold Checkout tax behavior. For more information, refer to Override Default Checkout Behavior.

Scope

provide_tax_rates

Attributes
KeyTypeDescription
urlstringURL endpoint for tax override requests.
Example
{
"success": true,
"actions": [
{
"type": "override_tax",
"data": {
"url": "https://example.com/get-tax-rates"
}
}
]
}

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

Line item actions

add_disallowed_line_item_properties

Defines line item properties to be added to the order but that should not be sent to the platform. You can use this action to track order metadata within Checkout without sending that metadata to the platform in the form of order notes.

Scope

modify_order

Attributes
KeyTypeDescription
disallowed_line_item_propertiesarrayProperties to exclude from line items when pushing order to platform.
Example
{
"type": "add_disallowed_line_item_properties",
"data": {
"disallowed_line_item_properties": ["is_prepaid", "is_gift"]
}
}

add_line_item_by_platform_variant

Adds a line item to the cart using a variant ID provided by the platform. If necessary, you can remove the line item with the remove_line_item_by_key action.

Scope

add_cart_item

Attributes
KeyTypeDescription
platform_variant_idintegerPlatform-specific ID of the variant associated with this line item.
line_item_keystring(Optional) Unique identifier of this line item.
quantityinteger(Optional) The quantity of the line item.
propertiesobject(Optional) Extra metadata about the line item.
priceinteger(Optional) Will override the price of the product with this value in cents.
is_amendmentboolean(Optional) If it is an amendment to a line item.
Example
{
"success": true,
"actions": [
{
"type": "add_line_item_by_platform_variant",
"data": {
"platform_variant_id": 9153875214378,
"line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
"quantity": 1,
"properties": {
"gift_wrap": "yes"
},
"price": 1500,
"is_amendment": true
}
}
]
}

add_line_item_property

Adds line item properties to a specific line item. A line item property is metadata, formatted as a key-value pair, that applies to a single line item.

Scope

modify_cart

Attributes
KeyTypeDescription
line_item_keystringUnique identifier of this line item.
namestringName of the key for the new property.
valuestringThe value of the new property.
Example
{
"success": true,
"actions": [
{
"type": "add_line_item_property",
"data": {
"line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
"property": {
"name": "color",
"value": "blue"
}
}
}
]
}

adjust_line_item_price

Adjusts a line item's price by the amount specified in value. A positive value increases the price and a negative value decreases the price.

Scope

modify_cart

Attributes
KeyTypeDescription
line_item_keystringUnique identifier of this line item.
valueintegerAmount to adjust the price in the base unit of your currency (e.g., 150 = $1.50).
Example
{
"success": true,
"actions": [
{
"type": "adjust_line_item_price",
"data": {
"line_item_key": "AABBCC123",
"value": 150
}
}
]
}

discount_line_items

Applies a given discount value to each line item specified.

Scope

modify_cart

Attributes
KeyTypeDescription
discount_typestringThe type of discount. Possible values are "percentage" or "fixed".
line_item_keysarrayThe list of line item keys to which the discount applies.
line_textstringDescription of the discount for the order summary.
valuenumericIf discount_type is percentage, this is the percentage. If discount_type is fixed, this is the fixed amount.
Example
{
"type": "discount_line_items",
"data": {
"line_item_keys": ["17255784153145:88efe753c99a31ae7059ff6089dd1c7c"],
"value": 10,
"line_text": "This is a plugin discount",
"discount_type": "percentage"
}
}

remove_line_item_by_key

Removes a line item previously created with add_line_item_by_platform_variant.

Scope

modify_cart

Attributes
KeyTypeDescription
line_item_keystringUnique identifier of this line item.
Example
{
"success": true,
"actions": [
{
"type": "remove_line_item_by_key",
"data": {
"line_item_key": "AABBCC123"
}
}
]
}

set_line_item_preorder

Sets a line item as a pre-order item. This action is not automatically enabled — please reach out to our partners department ([email protected]) to enable this feature.

Scope

modify_cart

Attributes
KeyTypeDescription
line_item_keystringUnique identifier of this line item.
pre_orderbooleanWhether the line item is a pre-order item.
Example
{
"success": true,
"actions": [
{
"type": "set_line_item_preorder",
"data": {
"line_item_key": "AABBCC123",
"pre_order": true
}
}
]
}

set_line_item_price

Sets the price of a line item.

Scope

modify_cart

Attributes
KeyTypeDescription
line_item_keystringUnique identifier of this line item.
valueintegerThe new price of the line item in the base unit of your currency (e.g., 150 = $1.50).
Example
{
"success": true,
"actions": [
{
"type": "set_line_item_price",
"data": {
"line_item_key": "AABBCC123",
"value": 150
}
}
]
}

set_line_item_shipping_address

Changes the shipping address of a line item. This action is not automatically enabled — please reach out to our partners department ([email protected]) to enable this feature.

Scope

modify_cart

Attributes
KeyTypeDescription
line_item_keystringUnique identifier of this line item.
first_namestringFirst name of the customer
last_namestringLast name of the customer.
companystringCompany name of the shipping address.
addressstringLine 1 of the shipping address.
address2stringLine 2 of the shipping address.
phonestringPhone number of the shipping address.
citystringCity of the shipping address.
provincestringProvince of the shipping address.
province_codestringProvince code of the shipping address.
countrystringCountry of the shipping address.
country_codestringCountry code of the shipping address.
postal_codestringPostal code of the shipping address.
Example
{
"success": true,
"actions": [
{
"type": "set_line_item_shipping_address",
"data": {
"line_item_key": "AABBCC123",
"first_name": "John",
"last_name": "Doe",
"company": "Bold Commerce Ltd",
"address": "50 Fultz Blvd",
"address2": "Another Address Line",
"phone": "800-555-0100",
"city": "Winnipeg",
"province": "Manitoba",
"province_code": "MB",
"country": "Canada",
"country_code": "CA",
"postal_code": "R3Y 0L6"
}
}
]
}

set_line_item_taxable

Indicates whether or not a line item is taxable.

Scope

modify_cart

Attributes
KeyTypeDescription
line_item_keystringUnique identifier of this line item.
taxablebooleanWhether or not the line item is taxable.
Example
{
"success": true,
"actions": [
{
"type": "set_line_item_taxable",
"data": {
"line_item_key": "AABBCC123",
"taxable": false
}
}
]
}

Miscellaneous actions

add_fee

Adds a fee to the order. If necessary, you can remove this fee with the remove_fee action.

Scope

add_fee

Attributes
KeyTypeDescription
idstringA unique identifier for this fee.
line_textstringA short description (e.g. "Gift wrapping").
fee_typestringIndicates the type of fee. Possible values are percentage or fixed.
taxablebooleanIndicates whether the fee is taxable.
valuenumericIf fee_type is percentage, this is the percentage. If fee_type is fixed, this is the fixed amount in dollars (e.g. 1.5 = $1.50).
is_amendmentboolean(Optional) If the fee is an amendment.
Example
{
"success": true,
"actions": [
{
"type": "add_fee",
"data": {
"id": "gift-wrap-123",
"line_text": "Gift wrapping",
"fee_type": "fixed",
"taxable": true,
"value": 1.5,
"is_amendment": false
}
}
]
}

delay_platform_order

Delays an order from being processed, for up to a maximum of 600 seconds. This action automatically sets an order to be amendable and therefore allows a plugin to amend an order after the customer reaches the thank you page during checkout. The customer does not have to remain on the thank you page for the order to be amendable. For example, if the customer closes the browser, the plugin can still amend the order if it does so within the time limit set by this action.

Scope

modify_order

Attributes
KeyTypeDescription
secondsintegerAmount of seconds to delay the order.
Example
{
"success": true,
"actions": [
{
"type": "delay_platform_order",
"data": {
"seconds": 120
}
}
]
}

disable_order_confirmation_email

Disables the order confirmation email that customers receive from Shopify after placing an order.

Scope

modify_order_emails

Attributes

None.

Example
{
"success": true,
"actions": [
{
"type": "disable_order_confirmation_email",
"data": {}
}
]
}

discount_cart

Applies a discount value to the entire cart.

If discountType is "percentage", use the discountPercentage field to indicate the discount as a percentage of the order total.

If discountType is "fixed", use the discountAmount field to indicate the discount as a flat rate.

Scope

modify_cart

Attributes
KeyTypeDescription
discountTypestringDetermines type of discount applied to cart. Possible values are fixed or percentage.
discountPercentageintegerPercentage to discount the cart by. Required if discountType is percentage.
discountAmountintegerAmount to discount the cart by in base currency units. Required if discountType is fixed. In base currency units using ISO-4217 standards.
transformationMessagestringDescription of the discount for the order summary.
platform_display_textstring(Optional) Description of the discount for the order summary on the platform.
Example
{
"success": true,
"actions": [
// Discount by percentage
{
"type": "DISCOUNT_CART",
"data": {
"discountType": "percentage",
"discountPercentage": 5, // 5% of order total
"transformationMessage": "Money saved",
"platform_display_text": "Money saved by plugin"
}
},
// Discount by fixed amount
{
"type": "DISCOUNT_CART",
"data": {
"discountType": "fixed",
"discountAmount": 500, // $5.00 if order is in USD
"transformationMessage": "Here's a bonus discount!",
"platform_display_text": "Money saved by plugin"
}
}
]
}

flag_order_as_bopis

Sets order as BOPIS (Buy Online, Pick Up In Store). This action hides the shipping section and sets shipping address as store's address.

Scope

modify_shipping

Attributes
KeyTypeDescription
flag_order_as_bopisstringIndicates whether to hide hidden_sections. Set to true to hide and false to unhide. It should be supported by setting data for shipping/billing addresses.
hidden_sectionsobjectList of all sections that should be hidden when BOPIS is turned on. Listed sections expect a bool values, true to hide and false to unhide section. Possible values include:shipping_address and saved_addresses.
note

The hidden sections default to shipping_address, but these must be explicitly specified as the default will be deprecated.

Example
{
"success": true,
"actions": [
{
"type": "flag_order_as_bopis",
"data": {
"flag_order_as_bopis": true,
"hidden_sections": {
"shipping_address": true,
"saved_addresses": true
}
}
}
]
}

remove_fee

Removes a fee previously created with add_fee.

Scope

add_fee

Attributes
KeyTypeDescription
idstringThe unique identifier of the fee to remove.
Example
{
"success": true,
"actions": [
{
"type": "remove_fee",
"data": {
"id": "gift-wrap-123"
}
}
]
}

require_amendable

Flags the order as amendable. Amendable orders can be changed after the customer has confirmed the order and before the order is processed. Changes to orders are referred to as amendments.

This action causes the amend_order event to be triggered after an order is submitted.

Scope

amend_orders

Attributes

None.

Example
{
"success": true,
"actions": [
{
"type": "require_amendable",
"data": {}
}
]
}

set_currency

Sets the currency of the order and exchange rate used on this order.

The exchange rate only affects shipping, tax, fee, and discount calculations. It is also used to convert the order back to the store currency if needed (such as when the order is created on the platform, or if the order total is converted to the store currency before making requests to a payment gateway.)

Scope

modify_currency

Attributes
KeyTypeDescription
currencystringThe ISO code of the currency.
ratenumberThe exchange rate between the store currency and the order.
format_stringstringA string describing how to display the currency.
Example: ${{amount}} with input 10.00 displays $10.00.
Example
{
"type": "set_currency",
"data": {
"currency": "USD",
"rate": 1.2567,
"format_string": "${{amount}}"
}
}

set_display_currency

Sets the display currency of the order and display exchange rate.

These values are not used in any calculation in Checkout and instead are intended for displaying orders to customers in different currencies.

Scope

modify_currency

Attributes
KeyTypeDescription
currencystringThe ISO code of the currency.
ratenumberThe exchange rate between the store currency and the order currency.
format_stringstringA string describing how to display the currency.
Example: ${{amount}} with input 10.00 displays $10.00.
Example
{
"type": "set_display_currency",
"data": {
"currency": "GBP",
"rate": 1.252005,
"format_string": "£{{amount}}"
}
}

set_gateway_currency

Sets Checkout to use a payment gateway's currency for the order.

note

Use the set_gateway_currency action if one gateway supports multiple currencies. Checkout only allows one currency assigned to each gateway.

Scope

modify_currency

Attributes
KeyTypeDescription
currencystringThe ISO code of the currency in the payment gateway.
Example
{
"type":"set_gateway_currency",
"data":{
"currency": "GBP"
}
}

set_split_order_condition

Sets the condition and policies on which to split a single order into two or more orders.

note

This action is not enabled by default and can only be used on private plugins. If you would like to enable it for your plugin, please reach out to [email protected] with the shop identifier for every store on which your plugin is installed.

It is possible to set multiple split order conditions on a single order. This results in the split orders being split themselves, provided the conditions you set in the split_order_condition_type are met. Split order policies are enacted in the order they are received from the plugin.

Scope

modify_order

Attributes
KeyTypeDescriptionPossible Values
split_order_policystringA policy describing how to create new orders.
  • CREATE_NEW_ORDER — creates two or more new orders and cancels the original order.
  • DIVIDE_ORDER — retains the original order and moves one or more line items to a new order.
split_order_condition_typestringThe condition on which to split the order.
  • PREORDER — creates one order that contains preorder items only, and a second order that contains regular items only.
  • SHIPPING_ADDRESS — organizes line items by shipping address and assigns each group of line items to its own order.
policy_typesobjectSpecify how to handle billing and how to split order-level costs. If values are not provided, they will be set to their default values.Refer to the Policy Types section for more information.
Policy Types

You can specify how to handle payment method authorization, shipping costs, and discounts across the split orders. Note that in all cases, the sum value of all split orders will equal the value of the original order.

KeyTypeDescriptionPossible Values
policy_types.BillingstringSpecifies how to handle payment method authorization. Default value is NEW_AUTH.
  • PARTIAL_SETTLEMENT — uses the existing payment method authorization for each resulting order.
  • NEW_AUTH with the CREATE_NEW_ORDER policy — adds a new payment method authorization for each resulting order.
  • NEW_AUTH with the DIVIDE_ORDER policy — uses the existing payment method authorization for the original order and adds a new authorization for each new order.
policy_types.ShippingCoststringSpecifies how to distribute the shipping cost over the split orders. Default value is FIRST.
  • FIRST — assigns all shipping costs to the first of the resulting orders.
  • LAST — assigns all shipping costs to the last resulting order.
  • ORDER_COUNT — splits shipping costs equally across all resulting orders.
  • ORDER_VALUE — splits shipping costs proportionately among resulting orders, according to order value.
policy_types.DiscountstringSpecifies how to distribute the discount value over the split orders. Default value is FIRST.
  • FIRST — assigns all discounts to the first of the resulting orders.
  • LAST — assigns all discounts to the last resulting order.
  • ORDER_COUNT — splits discounts equally across all resulting orders.
  • ORDER_VALUE — splits discounts proportionately among resulting orders.
  • ITEM — preserves line item-level discounts on each resulting order. Order-level discounts are still split evenly across resulting orders.
Example
{
"success": true,
"actions": [
{
"type": "set_split_order_condition",
"data": {
"split_order_policy": "CREATE_NEW_ORDER",
"split_order_condition_type": "PREORDER",
"policy_types": {
"Billing": "NEW_AUTH",
"ShippingCost": "ORDER_COUNT",
"Discount": "ORDER_VALUE"
}
}
}
]
}