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:
Key | Type | Description |
---|---|---|
type | string | Identifies the action to perform. |
data | object | Contains 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.
Action | Scope |
---|---|
add_cart_params | modify_order |
add_disallowed_line_item_properties | modify_order |
add_fee | add_fee |
add_line_item_by_platform_variant | add_cart_item |
add_line_item_property | modify_cart |
add_note | modify_order |
add_note_attribute | modify_order |
add_shipping_lines_value | modify_shipping |
add_tag | add_tags |
adjust_line_item_price | modify_cart |
change_billing_address | modify_order |
change_shipping_address | modify_shipping_address |
delay_payment_capture | modify_order |
delay_platform_order | modify_order |
disable_order_confirmation_email | modify_order_emails |
discount_cart | modify_cart |
discount_line_items | modify_cart |
flag_order_as_bopis | modify_shipping |
multiply_shipping_lines_value | modify_shipping |
override_address_validate | provide_address_validation |
override_discount | provide_discounts |
override_inventory | provide_shipping_rates |
override_shipping | provide_shipping_rates |
override_tax | provide_tax_rates |
remove_fee | add_fee |
remove_line_item_by_key | modify_cart |
require_amendable | amend_orders |
set_currency | modify_currency |
set_display_currency | modify_currency |
set_gateway_currency | modify_currency |
set_line_item_pre_order | modify_cart |
set_line_item_price | modify_cart |
set_line_item_shipping_address | modify_cart |
set_line_item_taxable | modify_cart |
set_order_created_by | modify_order |
set_payment_gateway | modify_payment_gateways |
set_shipping_rate | modify_shipping |
set_split_order_condition | modify_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
Key | Type | Description |
---|---|---|
add | integer | Amount to adjust the shipping total, in base currency units, using ISO-4217 standards. |
lineText | string | (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
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. |
phone | string | Phone number. |
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. |
update_billing | boolean | Whether to update the billing address to the previous shipping address. |
different_billing_address | boolean | Whether to select “Use a different billing address” on the checkout page |
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
Key | Type | Description |
---|---|---|
multiplier | float | The amount by which to multiply the total shipping value on the order. |
lineText | string | (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
Key | Type | Description |
---|---|---|
shipping_rate.price | integer | The amount of the shipping rate, in base currency units, using ISO-4217 standards. |
shipping_rate.name | string | A human-readable name for the shipping rate. |
shipping_rate.code | string | A 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
Key | Type | Description |
---|---|---|
first_name | string | First name of the customer. |
last_name | string | Last name of the customer. |
company | string | Company name of the billing address. |
address | string | Line 1 of the billing address. |
address2 | string | Line 2 of the billing address. |
phone | string | Phone number of the billing address. |
city | string | City of the billing address. |
province | string | Province of the billing address. |
province_code | string | Province code of the billing address. |
country | string | Country of the billing address. |
country_code | string | Country code of the billing address. |
postal_code | string | Postal 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.
Reusing the same keys for multiple add_cart_params
actions overwrites existing values.
Scope
modify_order
Attributes
Key | Type | Description |
---|---|---|
cart_params | object | Object 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
Key | Type | Description |
---|---|---|
note | string | The 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
Key | Type | Description |
---|---|---|
name | string | Name of the key for the new note attribute. |
value | string | The 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
Key | Type | Description |
---|---|---|
name | string | A 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
Key | Type | Description |
---|---|---|
created_by | string | The 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
Key | Type | Description |
---|---|---|
gateways | array | List of gateways to prioritize. |
public_id | string | The unique identifier for the gateway. |
priority | integer | (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
Key | Type | Description |
---|---|---|
url | string | URL 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:
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"
}
]
}
override_discount
Overrides the default Bold Checkout discount behavior. For more information, refer to Override Default Checkout Behavior.
Scope
provide_discounts
Attributes
Key | Type | Description |
---|---|---|
url | string | URL 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:
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"
}
override_inventory
Overrides the default Bold Checkout inventory check behavior. For more information, refer to Override Default Checkout Behavior.
Scope
provide_shipping_rates
Attributes
Key | Type | Description |
---|---|---|
url | string | URL 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:
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
}
]
}
override_shipping
Overrides the default Bold Checkout shipping behavior. For more information, refer to Override Default Checkout Behavior.
Scope
provide_shipping_rates