Bold Cashier Documentation

caution

• The documentation found on this page applies only to Bold Classic Checkout. If you are looking for Bold Headless Checkout API documentation, visit the Checkout section of the Developer Docs.

Welcome to the Bold Cashier API documentation.

Resources documented here are supported and available for use by third-party developers to build on the Cashier platform.

API

Access Token

Uninstall Plugin

If a plugin calls this endpoint it will be uninstalled.

DELETE /api/v1/{platform}/{shop}/oauth/access_token

Requires modify_access_token scope.

Address

Validate Address

POST /api/v1/{platform}/{shop}/address/validate

Example Validate Address Request Body

{
  "address": {
    "country_code": "CA",
    "postal_code": "R3Y0L6",
    "province": "Manitoba"
  }
}

Example Validate Address Success Response Body

{
  "success": true,
  "is_valid": true
}

Calling this endpoint will allow you to validate an address using the same criteria as the Cashier checkout.

Requires read_shop_settings scope.

Request Parameters

Key	Type	Description
country_code	string	Country names represented through the ISO 3166-1 alpha-2 standard format. (e.g., CA = Canada)
postal_code	string	Can be a postal code or zip code.
province	string	Name of a province or state.

Authentication

Access Token

Cashier API requests require that an access token be included in the header of each API request. An example would be the following:

X-Bold-Checkout-Access-Token: your-token-here

Route Parameters

Key	Description	Example
platform	The eCommerce platform of the shop.	shopify
shop	Platform-unique identifier for the shop.	agitated-darwin.myshopify.com

Cart

Create From JSON

POST /api/v1/{platform}/{shop}/carts/create_from_json

Example Create Cart From JSON

{
  "cart": {
    "id": "GEO0R30lkEdFekrt",
    "weight": 100,
    "item_count": 3,
    "requires_shipping": true,
    "currency": "CAD",
    "override_shipping": true,
    "line_items": [
      {
        "id": 112233,
        "quantity": 2,
        "title": "Product Title",
        "variant_title": "Variant Title",
        "weight": 50,
        "taxable": true,
        "image": "https://example.com/thing.jpg",
        "requires_shipping": true,
        "price": "2000"
      },
      {
        "id": 112234,
        "quantity": 1,
        "title": "The Thing",
        "variant_title": "The Thing - Red",
        "weight": 50,
        "taxable": false,
        "image": "https://example.com/red-thing.png",
        "requires_shipping": true,
        "price": 2500
      }
    ]
  },
  "customer": {
    "id": 334455,
    "email": "john.smith@boldcommerce.com",
    "first_name": "John",
    "last_name": "Smith",
    "addresses": [
      {
        "first_name": "John",
        "last_name": "Smith",
        "company": "Bold Commerce",
        "address1": "50 Fultz Blvd",
        "address2": "",
        "city": "Winnipeg",
        "province": "Manitoba",
        "country": "Canada",
        "zip": "R3Y 0L6",
        "country_code": "CA",
        "province_code": "MB",
        "default": true
      }
    ]
  },
  "shipping_lines": [
    {
      "display_text": "Slow Shipping",
      "value": 1000
    },
    {
      "display_text": "Fast Shipping",
      "value": 4000
    }
  ]
}

Example Successful Response

{
  "success": true,
  "cart_id": "GEO0R30lkEdFekrt"
}

Requires modify_cart scope, also requires a plugin application.

Request Parameters

Key	Type	Description
cart.id	string	A unique identifier for the cart. A new cart ID will be generated if not provided.

This endpoint is currently only supported for the general platform. The response will be a cart_id that will be valid for 3 minutes. You can optionally pass in the cart ID and Cashier will use the one provided instead of randomly generating one.

Create the signature by creating a string of the request parameters like this:

"cart_id=124789:shop=agitated_darwin.myshopify.com"

Then sign it with your application secret using HMAC with sha256, like the following PHP example.

hash_hmac('sha256', $parameterString, $applicationSecret);

The URL created will need to look like this example:

https://cashier.boldcommerce.com/general/checkout/load-json-cart?client_id={client ID}&shop=agitated_darwin.myshopify.com&cart_id=124789&signature=6b4b60b6619069d93f48261ca2a58b2c02aabdf6b486ee27fc321f0ecbcc3b59

Optional Parameters

The example to the right shows all the values that can be set, the following are optional in the cart object:

Key	Type	Description
currency	string	Allows the order to be set to a different currency than the store default.
customer	object	This is used for two things. If the customer's id is present, we treat this as a logged in customer, which means you must have authenticated the user. This allows the customer to save their credit cards for reuse. The rest of the details are used to pre-populate the checkout form for the customer. Multiple addresses can be provided and the customer will be able to choose from that list when they checkout.
override_shipping	boolean	Skips the cashier shipping service and presents the shipping lines that are included. Setting this to true makes cart.shipping_lines mandatory.
shipping_lines	object	Only required if cart.override_shipping is set to true. We will present these shipping options to the customer instead of looking up the shipping rates.

Create From SKUs

POST /api/v1/{platform}/{shop}/carts/create_from_sku

Example Create Cart From SKUs

{
  "cart": {
    "items": [
      {
        "sku": "1234-ABC",
        "quantity": 1,
        "line_item_properties": {
          "colour": "blue"
        }
      },
      {
        "sku": "456-HJKY",
        "quantity": 2
      }
    ],
    "platform_customer_id": 123,
    "cart_params": {
      "currency_iso_name": "CAD"
    }
  }
}

Example Successful Response

{
  "success": true,
  "cart_id": "GEO0R30lkEdFekrt"
}

Requires modify_cart scope.*

This endpoint is used to create a single use URL that can be used to start a Cashier checkout session as the customer provided in customer_id without any credentials having to be entered. The response will be a cart_id that will be valid for 3 minutes.

Create the signature by creating a string of the request parameters like this:

"cart_id=124789:shop=agitated_darwin.myshopify.com"

Then sign it with your application secret using HMAC with sha256, like the following PHP example.

hash_hmac('sha256', $parameterString, $applicationSecret);

The URL created will need to look like this example:

https://cashier.boldcommerce.com/shopify/checkout/load-sku-cart?client_id={client ID}&shop=agitated_darwin.myshopify.com&cart_id=124789&signature=6b4b60b6619069d93f48261ca2a58b2c02aabdf6b486ee27fc321f0ecbcc3b59

*This endpoint is currently only supported for Shopify shops.

Request Parameters

Cart JSON Object

Key	Type	Description
items	array	SKU objects.
platform_customer_id	string	Optional customer ID. Can refer to the platform customer ID or the Bold public customer ID. If present the cart will be constructed as if this customer was logged in.
cart_params	array	Array of Key:Value pairs that can be passed into Cashier (Optional).

SKU Objects

Key	Type	Description
sku	string	The SKU of the product.
quantity	integer	Number of this SKU in the cart.
line_item_properties	array	Optional line item properties.

Create From Variant IDs

POST /api/v1/{platform}/{shop}/carts/create_from_variant

Example Create Cart From Variant IDs

{
  "cart": {
    "items": [
      {
        "variant_id": "qwerty12345",
        "quantity": 1,
        "line_item_properties": {
          "colour": "blue"
        }
      },
      {
        "variant_id": "54321ytrewq",
        "quantity": 2
      }
    ],
    "platform_customer_id": 123,
    "cart_params": {
      "currency_iso_name": "CAD"
    }
  }
}

Example Successful Response

{
  "success": true,
  "cart_id": "GEO0R30lkEdFekrt"
}

Requires modify_cart scope.*

This endpoint is used to create a single use URL that can be used to start a Cashier checkout session as the customer provided in customer_id without any credentials having to be entered. The response will be a cart_id that will be valid for 3 minutes.

Create the signature by creating a string of the request parameters like this:

"cart_id=124789:shop=agitated_darwin.myshopify.com"

Then sign it with your application secret using HMAC with sha256, like the following PHP example.

hash_hmac('sha256', $parameterString, $applicationSecret);

The URL created will need to look like this example:

https://cashier.boldcommerce.com/shopify/checkout/load-variant-cart?client_id={client ID}&shop=agitated_darwin.myshopify.com&cart_id=124789&signature=6b4b60b6619069d93f48261ca2a58b2c02aabdf6b486ee27fc321f0ecbcc3b59

*This endpoint is not supported for General Platform shops.

Request Parameters

Cart JSON Object

Key	Type	Description
items	array	Variant ID objects.
platform_customer_id	string	Optional customer ID. Can refer to the platform customer ID or the Bold public customer ID. If present the cart will be constructed as if this customer was logged in.
cart_params	array	Array of Key:Value pairs that can be passed into Cashier (Optional).

SKU Objects

Key	Type	Description
variant_id	string	The variant ID of the product.
quantity	integer	Number of this variant in the cart.
line_item_properties	array	Optional line item properties.

Customer

Find By Platform ID

GET /api/v1/{platform}/{shop}/customer/find?platform_customer_id={platform_customer_id}

Example Response

{
  "success": true,
  "customers": [
    {
      "public_customer_id": "AABBCC123",
      "email": "example@boldcommerce.com",
      "platform_customer_id": 1234
    }
  ]
}

Requires read_customers scope.

Response Parameters

Key	Type	Description
public_customer_id	string	The customer's unique identifier.
email	string	The customer's email.
platform_customer_id	integer	The customer's ID on the corresponding platform.

create

POST /api/v1/{platform}/{shop}/customer/create

{
  "platform_id": "A-12",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@test.com"
}

Requires modify_customers scope.

Request Parameters

Key	Type	Description
platform_id	string	The customer's unique identifier on platform.
first_name	string	The customer's first name.
last_name	string	The customer's last name.
email	string	The customer's email.

Example Successful Response

{
  "success": true,
  "customer": {
    "id": 28,
    "platform_customer_id": "-12",
    "platform": "shopify",
    "name": "John Smith",
    "email": "john.smith@test.com",
    "public_id": "D0hRLAH4fQXrNYDlCGUwr1TjO2CemzGABYnZKhdtmxzQLfXjzsEtozHzMlZla9ji"
  }
}

Cards

GET /api/v1/{platform}/{shop}/customer/{public_customer_id}/cards

Example Response

{
  "success": true,
  "cards": [
    {
      "public_id": "upupdowndownleftrightleftrightba",
      "cc_type": "Visa",
      "expiration": {
        "date": "2021-08",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "last_four": "1111",
      "is_default": true
    }
  ]
}

This endpoint lets you retrieve a list of credit cards associated with a given customer.

Requires modify_customer scope.

Response Parameters

Key	Type	Description
cards	array	List of credit cards associated with customer.
cards[].public_id	string	Unique identifier for the credit card.
cards[].cc_type	string	Credit card brand.
cards[].expiration	array	Credit card expiration date information. Format is YYYY-MM.
cards[].last_four	integer	Last four credit card digits.
cards[].is_default	boolean	Whether or not this credit card is the customer's default credit card.

Stored Cards Iframe

https://cashier.boldcommerce.com/{shop}/{platform}/{signedJWT}/customer-info?uuid={App_UUID}&platform_type={platform_type}

Example Iframe Source:

https://cashier.boldcommerce.com/bobs-store.bigcommerce.com/bigcommerce/{signedJWT}/customer-info?uuid={App_UUID}&platform_type={platform_type}

Response:

{
  "success": true,
  "errors": {},
  "customer": {
    "id": 0,
    "platform_customer_id": 123456,
    "platform": "bigcommerce",
    "name": "John Smith",
    "email": "example@example.com",
    "public_id": "G07M7GAO36IBJJIN2FC4WUNU34QRNMPBOZT20FRGDBB3L9T0FFYNRJ41DC6ACQXH"
  }
}

This loads an iframe with the ability to edit a customer's credit cards for your shop. This route requires a signed JSON Web Token (JWT) as a route parameter.

The JWT payload should contain the `public_customer_id` as a claim, with the value being the public ID that belongs to the customer for which you want to edit credit cards. It should also be signed with your plugin's API secret.

Request Parameters

The iframe source requires both route and query params as follows:

Key	Type	Description
shop	string	Required Public customer id
first_name	string	Required Customer first name
last_name	string	Required Customer last name
email	string	Customer email address
platform_customer_id	string	Public ID used to identify the gateway

Error Responses

Response Status Codes

Code	Meaning
400	Bad Request
401	Unauthorized -- Your access token is missing or invalid for this shop.
403	Forbidden -- You do not have the required scope for this request.
404	Not Found
422	Unprocessable -- Your request has errors.

Fulfillments

Fulfill Items

POST /api/v1/{platform}/{shop}/orders/{order_id}/fulfill_items

Example Basic Request

{
  "items": [
    {
      "line_item_key": "key12345",
      "quantity": 2
    }
  ]
}

Basic Request Successful Response

{
  "capture_details": {
    "subtotal": 1234,
    "total": 1677,
    "tax_total": 432,
    "fee_total": 111,
    "discount_total": 53,
    "shipping_total": 12,
    "transaction_details": [
      {
        "gateway": "Test Gateway",
        "gateway_id": "qwertyasdf",
        "amount": 1677,
        "transaction_id": "key_1234",
        "reference_transaction_id": null,
        "response_code": null,
        "created_at": "2020-12-20 23:11:25",
        "status": "success"
      }
    ]
  }
}

Example Detailed Request

{
  "items": [
    {
      "line_item_key": "key12345",
      "quantity": 2,
      "capture_data": { "akey": "thevalue" }
    },
    {
      "line_item_key": "key54321",
      "quantity": 1
    }
  ],
  "amount": 1000,
  "idempotent_key": "wdfasydfgkluhasdfs",
  "capture_data": { "cust_id": 123412234 }
}

Detailed Request Successful Response

{
  "capture_details": {
    "subtotal": 1000,
    "total": 1000,
    "tax_total": 0,
    "fee_total": 0,
    "discount_total": 0,
    "shipping_total": 0,
    "transaction_details": [
      {
        "gateway": "Test Gateway",
        "gateway_id": "qwertyasdf",
        "amount": 333,
        "transaction_id": "key_45784",
        "reference_transaction_id": null,
        "response_code": null,
        "created_at": "2020-12-20 23:11:23",
        "status": "failed",
        "gateway_error": "declined"
      },
      {
        "gateway": "Test Gateway",
        "gateway_id": "qwertyasdf",
        "amount": 1000,
        "transaction_id": "key_1234",
        "reference_transaction_id": null,
        "response_code": null,
        "created_at": "2020-12-20 23:11:25",
        "status": "success"
      }
    ]
  }
}

Error Response

{
  "errors": [
    {
      "message": "Insufficient unfulfilled item quantity to fulfill requested items",
      "type": "fulfillment",
      "field": "item",
      "severity": "critical"
    }
  ]
}

Requires create_orders scope.

Route Parameters

Key	Description	Example
order_id	The Bold public_order_id identifier for the order.	jhdhVh3OdvFNG...

Body Parameters

Key	Type	Description
items	array	Items to fulfill.
items[].line_item_key	string	Unique identifier for the line item. If not present either sku or variant_id must be set.
items[].quantity	integer	Quantity of the item to fulfill.
items[].capture_data	object	(optional) Additional item specific transaction data for specific payment gateway integrations.
amount	integer	(optional) Amount in cents to capture on fulfillment. If not included it be calculated based from fulfilled items.
idempotent_key	string	(optional) A unique identifier for this transaction.
capture_data	object	(optional) Additional fulfillment transaction data for specific payment gateway integrations.
send_to_platform	boolean	(optional) Send fulfillment of items to platform

Response Parameters

Key	Type	Description
capture_details	object	Financial details on the capture that occurred from the fulfillment.

capture_details Object

Key	Type	Description
subtotal	integer	Total of item prices excluding fees, taxes, shipping, and discounts.
total	integer	Total of captured amount.
tax_total	integer	Total tax value included in capture.
fee_total	integer	Total fee value included in capture.
discount_total	integer	Total discount value included in capture.
shipping_total	integer	Total shipping value included in capture.
transaction_details	array	Details on each individual capture transaction.

transaction_details Object

Key	Type	Description
gateway	string	Name of the payment gateway this transaction was processed on.
gateway_id	string	Identifier for the payment gateway this transaction was processed on.
amount	integer	Amount in cents that this transaction is for.
transaction_id	string	Payment gateway transaction ID.
reference_transaction_id	string	Reference payment gateway transaction ID.
response_code	string	Additional payment gateway response code.
created_at	string	Date and time the transaction was completed.
status	string	Status of the transaction. Possible values: failed, success.
gateway_error	string	Error message included if transaction failed.

Gift Cards

Gift card balance

GET /api/v1/shopify/{shop}/gift_cards/balance

Example Request Option 1

{
  "gift_card": {
    "card_number": "SADWIUWRFNRVDTZB",
    "security_key": 124
  }
}

Example Request Option 2

{
  "gift_card": {
    "public_payment_method_id": "Lo3XG3ndaZ4K2poiyWtQtOPhHf1rxDDx8wYSNz9Q9GA4sEuo9kvMEY2Y2tc7o4y9"
  }
}

Example Response

{
  "success": true,
  "gift_card_balance": 1000
}

Calling this endpoint will return remaining balance for a valid gift card.

Requires create_gift_cards scope.

Request Parameters

Key	Type	Description
card_number	string	Gift card number.
security_key	integer	PIN for above gift card number.
public_payment_method_id	string	Payment public id string for the saved gift card.

Response Parameters

Key	Type	Description
gift_card_balance	integer	Remaining balance for a valid gift card.
message	string	Message detailing whether or not the gift card balance can be provided.

Retrieve saved gift cards for a customer

GET /api/v1/shopify/{shop}/customer/saved_gift_cards

Example Request

{
  "customer": {
    "public_id": "i2FLPPiHDXuAu85n0gtG9sDcXUXeN7N1BHVGA10zZEdzE5pUogTOQjSAnyrH6hNz"
  }
}

Example Response

{
  "success": true,
  "count": 3,
  "cards": [
    {
      "payment_public_id": "P44qfpucJ1dsQjuZopMpFuQNyKCv7Eui0JLCHq9y1ytE669TlqGChkrl92xxhTXy",
      "card_number": "SADWIUWRFNRVDTZB",
      "balance": 1000,
      "status": "valid"
    },
    {
      "payment_public_id": "dpHczf969NebD78dija2EYApefXaOwbmwgs1rgAX80JpLnKG2Rq8e8xjxyS4uUON",
      "card_number": "NPXEDTAUJHLSSTID",
      "balance": 0,
      "error": "Gift card is not valid due to 0 balance",
      "status": "invalid"
    },
    {
      "payment_public_id": "y1UrSibhm5JwefpGGOOPtVBcDJq8OSpFR8f7WYZ6aTCQmsjtwngCVTI3Dd3yfCoL",
      "card_number": "603628782342581270181",
      "balance": 1500,
      "status": "valid"
    }
  ]
}

Calling this endpoint will return a list of gift cards saved for a customer with remaining balance left on the card.

Requires create_gift_cards scope.

Request Parameters

Key	Type	Description
public_id	string	The customer's unique identifier.

Response Parameters

Key	Type	Description
payment_public_id	string	Payment unique identifier associated with a saved gift card.
card_number	string	Saved gift card number for the above payment_public_id.
balance	integer	Remaining balance for a valid gift card.
message	string	Message detailing whether or not the list of saved gift cards can be provided.
status	string	Shows validity of a gift card.
error	string	Error will be shown to indicate reason of an invalid status.

Validate and save gift card

GET /api/v1/shopify/{shop}/gift_cards/validate_and_save_gift_card

Example Request

{
  "customer": {
    "public_id": "A4aPb5ko5bptK1rRtvpZwapPvcVo5dwxRitcGzhixwWTT1qO2mKJEBZ5zHMWWoO0"
  },
  "gift_card": {
    "card_number": "SADWIUWRFNRVDTZB",
    "security_key": 124,
    "remember": true
  }
}

Example Response

{
  "success": true,
  "validation_result": "Gift card is valid",
  "payment_public_id": "3eC7ueNBpslL9csh9RVt2RNXcr9x5V09tdDXbAagSNgHmTAzvUqiML7h2yDwFvRu"
}

Calling this endpoint will return a message if gift card is valid or not and if remember is set to true for a valid gift card it will be saved in the DB and will also return payment_public_id

Requires create_gift_cards scope.

Request Parameters

Key	Type	Description
public_id	string	The customer's unique identifier.
card_number	string	Gift card number.
security_key	integer	PIN for above gift card number.
remember	boolean	Whether or not we need to save the valid gift card.

Response Parameters

Key	Type	Description
validation_result	string	Gift card is valid or not.
payment_public_id	string	Payment unique identifier associated with a saved gift card.
message	string	Message detailing whether or not the gift card can be validated and saved.

Orders

Authorize Order

POST /api/v1/{platform}/{shop}/orders/{order_id}/authorize

Example Successful Response:

{
  "success": true,
  "order": {
    "example": ""
  }
}

Example Failed Response:

{
  "success": false,
  "errors": ["Error Authorizing", "Card Declined"]
}

Authorizes a payment with the necessary gateway.

Requires create_orders scope.

Cancel

POST /api/v1/{platform}/{shop}/orders/{order_id}/cancel

Example Cancel Order With Reason post body:

{
  "reason_for_cancelation": "rejected"
}

Example Successful response:

{
  "success": true
}

Example Failed Response:

{
  "success": false,
  "errors": ["Order not found"]
}

Cancels the orders and voids any pending authorizations on the order. Cannot cancel orders that have already been partially fulfilled, refunded or captured. An optional reason_for_cancelation post body can be included in the request*.

• Cancellation reason for Shopify shops only supports: customer,inventory,fraud,declined and other

Requires create_orders scope.

Cart

POST /api/v1/{platform}/{shop}/orders/{order_id}/cart

Example Create / Update Cart:

{
  "identifier": "e3b00de148bc30ebad2f300f0f7c9e87",
  "currency_template": "${{amount}}",
  "notes": "some notes",
  "requires_shipping": 1,
  "cart_completed": 0,
  "items": {
    "0": {
      "sku": "CAN5416219681",
      "visible": 1,
      "quantity": 1,
      "requires_shipping": 1,
      "taxable": 1
    },
    "1": {
      "identifier": "8510523777-28735080385",
      "_action": "delete"
    }
  }
}

Create a cart for an existing order.

Requires create_orders scope.

Request Parameters

Key	Type	Description
identifier	string	Cart identifier.
currency_template	string	Currency template (eg., ${{amount}} ).
notes	string	(Optional)
requires_shipping	boolean
cart_completed	boolean	(Optional)
items	array	(Optional) Cart line items.

Cart line items parameters

Key	Type	Description
_action	string	value = delete
sku	string
identifier	string	Cart line item identifier.
price	integer	$581.99 = 58199
visible	boolean	0 or 1
quantity	integer
title	string
image	string	URL
requires_shipping	boolean
weight	integer
weight_unit	string
taxable	boolean
product_description	string
product_title	string
variant_title	string

Cart Line Item

POST /api/v1/{platform}/{shop}/orders/{order_id}/cart/line_item

Example Create / Update Cart Line Item:

{
  "line_item_key:": "32179970211914:11e6517066a534719d66451928184d3c",
  "identifier": "8510523777-28735080388",
  "price": 58998,
  "visible": 1,
  "quantity": 1,
  "title": "test title",
  "requires_shipping": 1,
  "weight": 1900,
  "taxable": 1,
  "product_description": "test description"
}

Example Delete Cart Line Item:

{
  "identifier": "8510523777-28735080385",
  "_action": "delete"
}

Requires create_orders scope.

Request Parameters

Key	Type	Description
_action	string	value = delete
line_item_key	string	Unique identifier for the line item.
identifier	string	Cart line item identifier.
price	integer	$581.99 = 58199
visible	boolean	0 or 1
quantity	integer
title	string
image	string	URL
requires_shipping	boolean	0 or 1
weight	integer
weight_unit	string
taxable	boolean	0 or 1
product_description	string
product_title	string
variant_title	string

Create Order

POST /api/v1/{platform}/{shop}/orders/create

{
  "charge": 1,
  "currency": "CAD",
  "money_format": "${{amount}}",
  "exchange_rate": 1.33,
  "cart": {
    "cart_token": "41nUJjkDJPGbk2Xw1XWB92dFOy9OW96YPxLm8iOb",
    "identifier": "e3b00de148bc30ebad2f300f0f7c9e87",
    "currency_template": "${{amount}}",
    "items": {
      "0": {
        "sku": "CAN5416219681",
        "visible": 1,
        "quantity": 1,
        "requires_shipping": 1,
        "taxable": 1,
        "fees": [
          {
            "label_language_key": "Gift Wrap",
            "value": 1000,
            "taxable": true,
            "display_inline": true,
            "taxes": [
              {
                "rate_name": "gst",
                "rate": 0.05
              },
              {
                "rate_name": "pst",
                "rate": 0.07
              }
            ],
            "show_description": false,
            "description_language_key": "some descriptive text here"
          }
        ]
      },
      "1": {
        "platform_variant_id": 20129965703268
      }
    }
  },
  "customer_id": 1,
  "platform_customer_id": "3ckMaPAmyrv6zMf8749pU2ULXfjgkaLZ",
  "public_payment_method_id": "ABCDEF0",
  "payment_details": {
    "0": {
      "public_payment_method_id": "ABCDEF1",
      "amount": 10
    },
    "1": {
      "public_payment_method_id": "ABCDEF2",
      "amount": null
    }
  },
  "customer": {
    "email": "test@test.com",
    "first_name": "John",
    "last_name": "Smith"
  },
  "shipping_address": {
    "first_name": "John",
    "last_name": "Smith",
    "company_name": "Google",
    "address": "50 Fultz",
    "address2": "Unit B",
    "city": "Winnipeg",
    "country_code": "CA",
    "province_code": "MB",
    "postal_code": "R3K0C4"
  },
  "billing_address": {
    "first_name": "Jonny",
    "last_name": "Smitty",
    "company_name": "Google",
    "address": "50 Fultz",
    "city": "Winnipeg",
    "country_code": "CA",
    "province_code": "MB",
    "postal_code": "R3K0C4"
  },
  "shipping": {
    "cost": 1400,
    "rate_name": "Canada Post Expedited Parcel"
  },
  "taxes": {
    "0": {
      "value": 0.04,
      "tax_name": "GST"
    },
    "1": {
      "value": 0.03,
      "tax_name": "PST"
    }
  },
  "shipping_taxes": {
    "0": {
      "rate": 0.02,
      "tax_name": "GST"
    },
    "1": {
      "rate": 0.01,
      "tax_name": "PST"
    }
  },
  "discounts": [
    {
      "code": "E1CDF184E777F232"
    },
    {
      "line_text": "Test discount",
      "value": 10,
      "type": "percent"
    }
  ],
  "note": "some notes",
  "send_receipt": 1
}

Requires create_orders scope.

Request Parameters

Key	Type	Description
authorize	boolean	Whether the order is authorized but payment capture should be deferred. (optional, default is false, ignored if charge is true)
billing_address	object	See Billing/Shipping Addresses (optional, default is shipping_address)
cart	object
cart_params	array	An array of key/value pairs. Each key must be a string. (optional)
charge	boolean	Whether to charge this order immediately. The payment gateway associated with the public_payment_method_id will be used -- or, if that is not set, the default payment gateway for the customer, specified by the customer_id, will be used. (optional, default is false)
currency	string	(optional)	Currency ISO code the order should be created in.
customer	object	(optional)
customer_id	integer	(optional - either customer_id or public_payment_method_id or payment_details or platform_customer_id for multiple payments must be set )
platform_customer_id	string	(optional - either customer_id or public_payment_method_id or payment_details or platform_customer_id for multiple payments must be set ). Value can be 0 to create a new bold platform customer and generate a new random platform customer id. Otherwise, if a different value is passed, checkout will try to find the bold platform customer, or will create a new one if not found.
discounts	array	(optional)
exchange_rate	float	(optional)
fraud_details	array	An array of JSON objects describing the results of fraud analysis performed on the order. (optional)
idempotency_key	string	A unique identifier for this transaction. (optional)
money_format	string	(optional)
note	string	A note attached to the order. (optional)
send_receipt	boolean	A flag the sets to send the receipt through e-mail or not, overriding the platform configuration. (optional)
note_attributes	array	An array of key/value pairs. Each key must be a string, and each value must be of type string, number, or boolean. (optional)
public_payment_method_id	string	(optional - either customer_id or public_payment_method_id or payment_details or platform_customer_id for multiple payments must be set )
payment_details	array	Multiple payments can be done by providing array of payment ids and amounts. Amounts total will be capped to the order total. In presence of amount with 0 or null, order balance which is not covered by amounts total will be charged at the end. (optional - either customer_id or public_payment_method_id or payment_details must be set )
prevent_amendments	boolean	Setting this to true prevents the api_amend_order event from being dispatched to shop plugins during order creation. (optional, defaults to false)
shipping_address	object	See Billing/Shipping Addresses (optional)
shipping	object	(optional, must be set if charge is true)
shipping_taxes	array	An array of objects. (optional)
tags	array	An array of strings. (optional)
taxes	array	An array of objects. (optional)
fees	array	Adds line item fee and apply taxes if they are specified and taxable is set to true. (optional)

Discounts can be:

Key	Type	Description
code	string	Discount code.

OR:

Key	Type	Description
line_text	string	Short description.
value	numeric	If type is fixed, this is the discount in cents If type is percent, this is the discount percentage If type is free_shipping, this is ignored If type is shipping_fixed, this is the shipping discount in cents If type is shipping_percent, this is the shipping discount percentage.
type	string	Possible values: fixed, percent, free_shipping, shipping_fixed, shipping_percent.

Cart must be:

Key	Type	Description
cart_token	string
items	array	An array of objects - see cart line item. Additionally, an item's platform_variant_id may be set to a valid variant ID (number). Any cart line item parameters not set will be filled by data from the variant specified. Note that order creation will not fail because of missing line item parameters; however, missing line item data may cause undefined behaviour later in the order life cycle.

Shipping can be:

Key	Type	Description
cost	number	(optional, defaults to 0)
rate_name	string	(optional)

Taxes can be:

Key	Type	Description
value	number	(optional, defaults to 0)
tax_name	string	(optional)

Shipping Taxes can be:

Key	Type	Description
rate	number	(optional, defaults to 0)
tax_name	string	(optional)

Customer

POST /api/v1/{platform}/{shop}/orders/{order_id}/customer

Example Create / Update Customer:

{
  "info": {
    "email": "test@test.com",
    "first_name": "John",
    "last_name": "Smith"
  },
  "shipping_address": {
    "first_name": "John",
    "last_name": "Smith",
    "company": "Google",
    "address": "50 Fultz",
    "address2": "Suite 33",
    "city": "Winnipeg",
    "country": "Canada",
    "country_code": "CA",
    "province": "Manitoba",
    "province_code": "MB",
    "postal_code": "R3K0C4",
    "phone": "2049274231"
  },
  "billing_address": {
    "first_name": "John",
    "last_name": "Smith",
    "company": "Google",
    "address": "50 Fultz",
    "address2": "Suite 33",
    "city": "Winnipeg",
    "country": "Canada",
    "country_code": "CA",
    "province": "Manitoba",
    "province_code": "MB",
    "postal_code": "R3K0C4",
    "phone": "2049274231"
  }
}

Create / Update a customer for an existing order.

Requires create_orders scope.

Request Parameters

Key	Type	Description
email	string
first_name	string
last_name	string
customer_id	integer	(Optional) Bold customer ID.
shipping_address	array	See here
billing_address	array	See here

Fraud Details

POST /api/v1/{platform}/{shop}/orders/{order_id}/fraud_details

Requires modify_fraud_details scope.

Request Parameters

Key	Type	Description
fraud_details	object	A JSON object describing the results of fraud analysis performed on the order.

Get Order

GET /api/v1/{platform}/{shop}/orders/{order_id|public_order_id}

Example Response:

{
  "success": true,
  "order": {
    "cart_params": {
      "currency_iso_name": "CAD",
      "custom_value": "test value"
    },
    "currency": "CAD",
    "currency_info": {
      "code": "CAD",
      "format": "${{amount}}",
      "format_with_currency": "${{amount}} CAD",
      "symbol": "$",
      "show_iso_code": true
    },
    "customer": {
      "id": 3140600,
      "public_customer_id": "xX9o4UiUXNANCCRJ8ChnU1JyLJRuiw5DM0MdEJA9hRYIQ1hRaLlUUCvgb1CEpwxw",
      "platform_customer_id": 304591274026,
      "core_info": {
        "id": 0,
        "first_name": "Test",
        "last_name": "Customer",
        "email": "example@boldcommerce.com"
      },
      "shipping_address": {
        "first_name": "Test",
        "last_name": "Customer",
        "company": "Bold Commerce",
        "address1": "50 Fultz Boulevard",
        "address2": "",
        "phone": "5551231234",
        "city": "Winnipeg",
        "province": "Manitoba",
        "province_code": "MB",
        "country": "Canada",
        "country_code": "CA",
        "zip": "R3Y0L6"
      },
      "billing_address": {
        "first_name": "Test",
        "last_name": "Customer",
        "company": "Bold Commerce",
        "address1": "50 Fultz Boulevard",
        "address2": "",
        "phone": "5551231234",
        "city": "Winnipeg",
        "province": "Manitoba",
        "province_code": "MB",
        "country": "Canada",
        "country_code": "CA",
        "zip": "R3Y0L6"
      }
    },
    "discounts": [
      {
        "line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
        "value": 1150,
        "lineText": "Money saved",
        "tag": "Discount",
        "discount_type": "percent",
        "discount_percent": 5,
        "application_uuid": null
      }
    ],
    "exchange_rate": "1.000000000000",
    "fees": [
      {
        "value": 150,
        "lineText": "Gift wrapping",
        "tag": "Fee",
        "id": "gift-wrap-123",
        "taxable": false
      }
    ],
    "fulfillment_status": "unfulfilled",
    "id": 13251887,
    "includes_tax": 0,
    "line_items": [
      {
        "id": 21391545,
        "title": "Test Product",
        "product_title": "Test Product",
        "variant_title": null,
        "image": "https://cdn.shopify.com/s/files/1/2715/2606/products/test_product.png?v=1569238900",
        "properties": {
          "test_prop": "some sort of line item property"
        },
        "description": "",
        "quantity": 1,
        "price": 23000,
        "total_price": 23000,
        "visible": 1,
        "available_quantity": 0,
        "updated_quantity": 0,
        "line_item_id": 4303130558506,
        "line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
        "inventory_policy": null,
        "platform_variant": {
          "id": 9153875214378,
          "barcode": "",
          "compare_at_price": 230,
          "fulfillment_service": "manual",
          "grams": 100,
          "inventory_management": "shopify",
          "inventory_policy": "continue",
          "option1": "Default Title",
          "option2": "",
          "option3": "",
          "position": 1,
          "price": 230,
          "product_id": 727610359850,
          "requires_shipping": 1,
          "sku": "",
          "taxable": 1,
          "tax_code": "",
          "title": "Default Title",
          "inventory_quantity": -144,
          "old_inventory_quantity": -144,
          "image_id": 0,
          "created_at": "2018-01-08 22:57:03",
          "updated_at": "2020-02-03 21:55:00",
          "inventory_item_id": 9170708824106,
          "product": {
            "id": 727610359850,
            "myshopify_domain": "example.myshopify.com",
            "handle": "test",
            "product_type": "",
            "published_scope": "web",
            "template_suffix": "",
            "title": "Test Product",
            "vendor": "example",
            "tags": "Test Tag",
            "featured_image_id": 2603046273066,
            "created_at": "2018-01-08 22:57:03",
            "updated_at": "2020-02-03 21:55:00"
          }
        },
        "includes_tax": 0,
        "weight": 100,
        "requires_shipping": 1,
        "note": "",
        "platform_variant_id": 9153875214378,
        "platform_product_id": 727610359850,
        "sku": "",
        "fees": [
          {
            "value": 1000,
            "taxable": true,
            "inline": false,
            "show_description": false,
            "label_language_key": "Gift Wrap",
            "description_language_key": "some descriptive text here"
          }
        ]
      }
    ],
    "note": "This is a note",
    "note_attributes": {
      "_language_iso_code": "",
      "note": "This is a note attribute"
    },
    "order_source": "cashier",
    "order_source_name": "cashier",
    "payments": [
      {
        "value": 25746,
        "lineText": "Paid with by credit card",
        "brand": "visa",
        "id": "51",
        "tag": "Credit",
        "driver": "Test Gateway",
        "currency": "CAD",
        "status": "finalized",
        "uuid": null
      }
    ],
    "platform_details": {
      "order_name": "#1679",
      "order_token": "ed1a8a91a2ff85f6f63463fb3419b0f9",
      "order_created_at": "2020-02-03T16:54:59-05:00"
    },
    "platform_friendly_identifier": "1679",
    "platform_order_id": "1956779032618",
    "public_order_id": "abc123",
    "removed_line_items": [],
    "requires_shipping": true,
    "resumable_url": "https://cashier.boldcommerce.com/shopify/example.myshopify.com/order/abc123",
    "shipping_is_taxed": 0,
    "shipping_lines": [
      {
        "id": "",
        "value": 1123,
        "price": 1123,
        "lineText": "Canada Post Expedited Parcel",
        "name": "Canada Post Expedited Parcel",
        "code": "DOM.EP",
        "source": "",
        "tag": "Shipping",
        "delivery_date": "",
        "delivery_range": "",
        "delivery_days": ""
      }
    ],
    "subtotal": 23000,
    "tags": ["test_tag"],
    "tax_lines": [
      {
        "name": "GST",
        "amount": 1093,
        "rate": 0.05,
        "tag": "",
        "translation_key": ""
      },
      {
        "name": "PST",
        "amount": 1530,
        "rate": 0.07,
        "tag": "",
        "translation_key": ""
      }
    ],
    "total": 25746,
    "deferred_capture_payment": false,
    "cart_id": "13427937",
    "accepts_marketing": false
  }
}

Requires read_orders scope.

Response Parameters

Key	Type	Description
cart_params	array	An array of key/value pairs.
currency	string	Currency ISO code the order should be created in.
currency_info	object	Formatting information about the order's currency.
customer	object	Customer associated with the order.
customer.id	integer	Bold customer ID.
customer.public_customer_id	string	The customer's unique identifier.
customer.platform_customer_id	integer	The customer’s ID on the corresponding platform.
customer.core_info	object	Customer's personal information.
customer.shipping_address	object	See Billing/Shipping Addresses.
customer.billing_address	object	See Billing/Shipping Addresses.
discounts[]	array	Array of discount objects applied to the order.
discounts[].line_item_key	string	Unique identifier for the line item the discount is applied to.
discounts[].value	numeric	If the discount_type is fixed, this is the discount in cents. If the discount_type is percent, this is the discount percentage. If the discount_type is free_shipping, this is ignored. If the discount_type is shipping_fixed, this is the shipping discount in cents. If the discount_type is shipping_percent, this is the shipping discount percentage.
discounts[].lineText	string	Description of the discount.
discounts[].tag	string	Arbitrary tag added to the discount.
discounts[].discount_type	string	Possible values: fixed, percent, free_shipping, shipping_fixed, shipping_percent.
discounts[].discount_percent	integer	Percent of discount if the discount_type is set to percent.
exchange_rate	string	The order's exchange rate.
fees[]	array	Array of fees applied to the order.
fees[].value	integer	Value of the fee in cents.
fees[].lineText	string	Description of the fee.
fees[].tag	string	Tag added to the fee.
fees[].id	array	ID assigned to the fee.
fees[].taxable	boolean	Whether or not the fee is taxable.
fulfillment_status	string	The fulfillment status of the order. Can be unfulfilled, partial, fulfilled or null if the order hasn't been sent to the platform yet.
id	integer	Bold order ID.
includes_tax	boolean	Whether or not the order has tax included in the price.
line_items[]	array	An array of the line items purchased with the order along with their corresponding platform variant.
note	string	A note attached to the order.
note_attributes	object	An array of key/value pairs.
order_source	string	Source of the order.
order_source_name	string	Human readable name of the order source.
payments[]	array	Array of payments applied to the order.
payments[].value	integer	Value of the payment in cents.
payments[].lineText	string	Description of the payment.
payments[].brand	string	Brand of the payment.
payments[].id	string	ID assigned to the payment.
payments[].tag	string	Tag added to the payment.
payments[].driver	string	Driver Cashier used to process this payment.
payments[].currency	string	Currency ISO code of this payment.
payments[].status	string	Status of the payment.
payments[].uuid	string	If a plugin is acting as the payment gateway for this payment, this is the plugin's unique identifier.
platform_details	object	Platform specific order details.
platform_friendly_identifier	string	Shop specific ID of the order.
platform_order_id	string	Platform specific order ID.
public_order_id	string	Bold's unique identifier for the order.
removed_line_items[]	array	Array of line items that have been removed from the order.
requires_shipping	boolean	Whether or not an order requires shipping.
resumable_url	url	A URL that lets you resume the order in it's current state.
shipping_is_taxed	boolean	Whether or not the shipping value of the order is taxed.
shipping_lines[]	array	Array of shipping lines associated with the order.
subtotal	integer	The total order value pre-shipping, pre-tax, and pre-discounts in cents.
tags	array	An array of tags added to the order.
tax_lines[]	array	An array of tax lines associated with the order.
tax_lines[].name	string	The name of the tax line.
tax_lines[].amount	integer	The amount of the tax in cents.
tax_lines[].rate	numeric	The tax rate.
tax_lines[].tag	string	A tag associated with the tax line.
tax_lines[].translation_key	string	A translation key associated with the tax line.
total	integer	The total order value with shipping, tax, and discounts included in cents.
deferred_capture_payment	boolean	Whether or not the order is set to defer payment capture.
cart_id	string	ID of the Bold cart.
accepts_marketing	boolean	Whether or not the order is set to accept marketing material.

Payment Via Plugin

POST /api/v1/{platform}/{shop}/orders/{order_id}/add_payment

Example Add Payment Request Body

{
  "type": "plugin",
  "uuid": "AAAA-BBBB-CCCC-DDDD",
  "value": 100,
  "currency": "CAD",
  "gateway_name": "Test Gateway",
  "line_text": "Test payment",
  "metadata": {
    "note": "for the car"
  }
}

Example Add Payment Success Response Body

{
  "success": true,
  "order": {
    "id": 5,
    "payments": [
      {
        "value": 100,
        "lineText": "Test payment",
        "brand": "Test Gateway",
        "tag": "Plugin",
        "driver": "plugin_v2",
        "currency": "CAD",
        "status": "awaitingPreAuth",
        "uuid": "AAAA-BBBB-CCCC-DDDD",
        "metadata": {
          "note": "for the car"
        }
      }
    ]
  }
}

Example Add Payment Error Response Body

{
  "success": false,
  "errors": {
    "code": "order_payment_validation_failed",
    "message": "Invalid request parameters",
    "service": "cashier",
    "service_type": "cashier",
    "side": "cashier"
  }
}

This endpoint lets you add a payment to an order where a plugin acts as the payment gateway (e.g., Bold Loyalty Points).

Requires create_orders scope.

Request Parameters

Key	Type	Description
type	string	Must be set to "plugin" in order to add a plugin payment.
uuid	string	Unique identifier of the plugin acting as the payment gateway for this payment.
value	integer	The amount to reduce the outstanding balance.
currency	string	The currency code for the payment.
gateway_name	string	Name of the payment gateway for display.
line_text	string	Short description of the payment.
metadata	object	(Optional) Extra information about the payment.

Re-Authorize Order

POST /api/v1/{platform}/{shop}/orders/{order_id}/reauthorize

Attempt to authorize the order for the outstanding balance. Cashier will create new payment transactions for each payment that is currently authorized, failed or voided.

Re-Charge Order

POST /api/v1/{platform}/{shop}/orders/{order_id}/recharge

Attempt to charge the order for the outstanding balance. Cashier will create new payment transactions for each payment that is currently authorized, failed or voided, authorize them, and then capture the authorization. It will also authorize and capture any existing pending transactions.

Shipping/Billing Addresses

POST /api/v1/{platform}/{shop}/orders/{order_id}/customer/shippingAddress

POST /api/v1/{platform}/{shop}/orders/{order_id}/customer/billingAddress

Example Create / Update Address:

{
  "first_name": "John",
  "last_name": "Smith",
  "company": "Google",
  "address": "50 Fultz",
  "address2": "Suite 33",
  "city": "Winnipeg",
  "country": "Canada",
  "country_code": "CA",
  "province": "Manitoba",
  "province_code": "MB",
  "postal_code": "R3K0C4",
  "phone": "2049274231"
}

Create/update a customer's shipping/billing addresses for an existing order. Order's customer must exist.

Requires create_orders scope.

Request Parameters

Key	Type	Description
first_name	string
last_name	string
company	string
address	string
address2	string
city	string
country	string
country_code	string
province	string
province_code	string
postal_code	string
phone	string

Shipping Lines

POST /api/v1/{platform}/{shop}/orders/{order_id}/shipping

Example Create / Update Shipping:

{
  "cost": 2000,
  "rate_name": "Canada Post Expedited Parcel"
}

Example Delete Shipping:

{
  "rate_name": "Canada Post Expedited Parcel"
}

Create / update / delete a shipping lines for an existing order.

Requires create_orders scope.

Request Parameters

Key	Type	Description
cost	integer
rate_name	string

Taxes

POST /api/v1/{platform}/{shop}/orders/{order_id}/tax

POST /api/v1/{platform}/{shop}/orders/{order_id}/shipping_tax

Example Create / Update Tax:

{
  "value": 0.04,
  "tax_name": "PST"
}

Example Delete Tax:

{
  "tax_name": "PST"
}

Create/update/delete taxes for an existing order.

Requires create_orders scope.

Request Parameters

Key	Type	Description
value	float
tax_name	string	e.g. "GST"

Payments

Customer Batch Import

POST /api/v1/{platform}/{shop}/payments/import

Example Import Request

{
  "gateway_public_id": "AABBCC123",
  "customer_list": [
    {
      "email": "customerOne@example.com",
      "first_name": "Customer",
      "last_name": "One",
      "brand": "VISA",
      "last_four": 4242,
      "expiration_year": 2099,
      "expiration_month": 4,
      "platform_id": "12345",
      "tracking_id": "myTrackingId",
      "token": "SuCuReCuStomerToken"
    },
    {
      "email": "customerTwo@example.com",
      "first_name": "Customer",
      "last_name": "Two",
      "brand": "VISA",
      "last_four": 4141,
      "expiration_year": 2099,
      "expiration_month": 4,
      "platform_id": "67853",
      "tracking_id": "otherTrackingId",
      "token": "ABCDEF777"
    }
  ]
}

Example Response

{
  "success": true,
  "import_result": {
    "customers": [
      {
        "email": "customers@example.com",
        "token": "ABCDEF777",
        "public_id": "12FF89",
        "payment_method_id": "PUBLIC_CARD_ID",
        "tracking_id": "cust_0001"
      },
      {
        "email": "seconds@example.com",
        "token": "AHD8982",
        "public_id": "12FF890",
        "payment_method_id": "PUBLIC_CARD_ID_2",
        "tracking_id": "cust_0004"
      }
    ],
    "failed_tokens": [
      {
        "email": "bad@example",
        "token": "ABCDEF777",
        "reason": "Invalid Email Address"
      }
    ],
    "import_count": 2
  },
  "errors": {}
}

This endpoint will allow you to create customers and store their payment gateway tokens on Cashier. You will need to use the gateway ID provided by the /payments/gateways endpoint.

Requires create_customers scope.

Request Parameters

Key	Type	Description
gateway_public_id	string	Public ID used to identify the gateway.
customer_list	array	List of Customer Payment tokens to import.
customer_list[].email	string	Customer email address.
customer_list[].first_name	string	Customer first name.
customer_list[].last_name	string	Customer last name.
customer_list[].brand	string	Credit Cart Brand, optional for none credit card payment tokens.
customer_list[].last_four	integer	Last four credit card digits, optional for none credit card payment tokens.
customer_list[].expiration_year	integer	Credit card expiration year, optional for none credit card payment tokens.
customer_list[].expiration_month	integer	Credit card expiration month, optional for none credit card payment tokens.
customer_list[].platform_id	string	External customer ID, Shopify Customer ID for example.
customer_list[].tracking_id	string	User-defined identifier for this customer.
customer_list[].token	string	Tokenization payment method from the payment gateway.

Cashier will attempt to store every customer in the list. We do not validate the tokens on the gateway during this operation. The response will contain a list of customers that we were able to successfully store, as well as a list of any failed imports.

Customer Import

POST /api/v1/{platform}/{shop}/payments/customer_import

Example Import Request

{
  "gateway_public_id": "AABBCC123",
  "customer": {
    "email": "CustomerOne@example.com",
    "first_name": "Customer",
    "last_name": "One",
    "platform_id": "12345",
    "tracking_id": "myTrackingId",
    "token": "SeCuReCuStomerToken"
  }
}

Example Response

{
  "success": true,
  "import_result": {
    "customers": [
      {
        "email": "CustomerOne@example.com",
        "token": "SuCuReCuStomerToken",
        "public_id": "12FF89",
        "payment_method_id": "PUBLIC_CARD_ID",
        "tracking_id": "myTrackingId"
      }
    ],
    "failed_tokens": [],
    "import_count": 1
  },
  "errors": {}
}

This endpoint will allow you to create a single customer and store their payment gateway token on Cashier. Payment method information will be retrieved from the payment gateway using the provided token. Support for payment information retrieval depends on the payment gateway specified. You will need to use the gateway ID provided by the /payments/gateways endpoint.

Requires create_customers scope.

Request Parameters

Key	Type	Description
gateway_public_id	string	Public ID used to identify the gateway.
customer	array	Customer information and token to import.
customer.email	string	Customer email address.
customer.first_name	string	Customer first name.
customer.last_name	string	Customer last name.
customer.platform_id	string	External customer ID, Shopify Customer ID for example.
customer.tracking_id	string	User-defined identifier for this customer.
customer.token	string	Tokenization payment method from the payment gateway.

On success, the response will contain details on the stored customer.

List Payment Gateways

GET /api/v1/{platform}/{shop}/payments/gateways

Example Response:

{
  "success": true,
  "gateways": {
    "0": {
      "public_id": "AABBCC123",
      "name": "Test",
      "is_dev": false,
      "currency": "CAD",
      "source_type": "cc",
      "capabilities": {
        "0": "supports_void_pre_auth"
      }
    },
    "1": {
      "public_id": "123AABBCC",
      "name": "Test USD",
      "is_dev": false,
      "currency": "USD",
      "source_type": "paypal",
      "capabilities": {
        "0": "supports_void_pre_auth"
      }
    }
  }
}

This endpoint allows you to retrieve a list of payment gateways that the merchant has configured. This is used when importing to specify which gateway the token is for.

Requires read_payment_gateways scope.

Request Parameters

None

Response Parameters

Key	Type	Description
gateways	object	List of Payment Gateways.
gateways[].public_id	string	Unique identifier for the gateway.
gateways[].name	string	The gateway name.
gateways[].is_dev	boolean	Whether or not this gateway is a dev gateway.
gateways[].currency	string	The currency code for the gateway.
gateways[].source_type	string	The source type of the gateway.
gateways[].capabilities	object	List of the capabilities of the gateway. Differs for each gateway.

Test Customer Import

POST /api/v1/{platform}/{shop}/payments/test_import

Example Request:

{
  "gateway_public_id": "AABBCC123",
  "customer": {
    "email": "customer@example.com",
    "first_name": "Cust",
    "last_name": "Omer",
    "brand": "VISA",
    "last_four": 4242,
    "expiration_year": 2099,
    "expiration_month": 4,
    "platform_id": "12345",
    "token": "SuCuReCuStomerToken"
  }
}

Response:

{
  "success": true,
  "errors": {},
  "customer_gateway_details": {}
}

Specific details vary depending on the payment gateway provider

This allows you to test a customer payment token against the selected gateway to confirm that you are going to attempt the import against the correct gateway. This validation is performed by attempting to retrieve the details of the customer from the payment gateway using the provided token.

Requires read_customers scope.

Request Parameters

Key	Type	Description
gateway_public_id	string	Public ID used to identify the gateway.
customer	object	JSON object of the customer to test with.
customer.email	string	Customer email address.
customer.first_name	string	Customer first name.
customer.last_name	string	Customer last name.
customer.brand	string	Credit cart brand, optional for none credit card payment tokens.
customer.last_four	integer	Last four credit card digits, optional for none credit card payment tokens.
customer.expiration_year	integer	Credit card expiration year, optional for none credit card payment tokens.
customer.expiration_month	integer	Credit card expiration month, optional for none credit card payment tokens.
customer.platform_id	string	External customer ID, Shopify Customer ID for example.
customer.token	string	Tokenization payment method from the payment gateway.

Capturing Payments

There are two ways to capture payments: capturing the full amount, or capturing a flat amount. All payment endpoints require the add_payments scope.

Full capture

POST /api/v1/{platform}/{shop}/orders/{order_id}/payment/capture

This captures the entire order, all shipping, taxes, etc.

Example Capture whole order post body:

{
  "re-auth": true,
  "idempotent_key": "ABC123"
}

Example Capture whole order response. Transaction details are dependent on the payment gateway used.

{
  "success": true,
  "order_total": 1456,
  "amount_remaining": 0,
  "total_paid": 1456,
  "transactions": [
    {
      "gateway": "Stripe Default Name",
      "gateway_id": "bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi",
      "amount": 1456,
      "transaction_id": "ch_1GvDW4JhIKSKpq8w9SoshRef",
      "reference_transaction_id": null,
      "response_code": null
    }
  ]
}

Route Parameters

Key	Description	Example
order_id	The Bold public_order_id identifier for the order.	jhdhVh3OdvFNG...

Body Parameters

Key	Type	Description
re-auth	boolean	Whether or not Cashier should attempt to re-authorize payment if the authorize transaction has been used or expired.
idempotent_key	string	Idempotency Key

Partial capture

POST /api/v1/{platform}/{shop}/orders/{order_id}/payment/capture/amount

This captures a flat amount of money against the order total (shipping, taxes, etc included).

Example Capture flat amount post body:

{
  "amount": 1000,
  "re-auth": true,
  "idempotent_key": "ABC123"
}

Example Capture flat amount response. Transaction details are dependent on the payment gateway used.

{
  "success": true,
  "order_total": 4300,
  "amount_remaining": 4200,
  "total_paid": 100,
  "transactions": [
    {
      "gateway": "Stripe Default Name",
      "gateway_id": "bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi",
      "amount": 100,
      "transaction_id": "ch_1GvDW4JhIKSKpq8w9SoshRef",
      "reference_transaction_id": null,
      "response_code": null
    }
  ]
}

Route Parameters

Key	Description	Example
order_id	The Bold public_order_id identifier for the order.	jhdhVh3OdvFNG...

Body Parameters

Key	Type	Description
amount	integer	Amount in pennies to capture against the order total.
re-auth	boolean	Whether or not Cashier should attempt to re-authorize payment if the authorize transaction has been used or expired.
idempotent_key	string	Idempotency Key

Refunds

There are three refund endpoints available: Full Refund, Refund by line item, and Refund Flat Amount. All refund endpoints require the create_orders scope.

Full Refund

POST /api/v1/{platform}/{shop}/orders/{order_id}/refund

This refunds the entire order, all shipping, and restocks all line items (if applicable).

Example Create Refund for Whole Order post body:

{
  "email_notification": false,
  "reason_for_refund": "Product arrived broken"
}

Example Create Refund for Whole Order response:

{
  "success": true,
  "amount_refunded": 200.0,
  "transaction_details": [
    {
      "errors": [],
      "success": true,
      "transaction_number": "payment-12345",
      "amount": 200.0
    }
  ]
}

Route Parameters

Key	Description	Example
order_id	The Bold public_order_id identifier for the order.	jhdhVh3OdvFNG...

Body Parameters

Key	Type	Description
email_notification	boolean	Whether or not Cashier will send the customer an email notification. If true, an email will be sent.
reason_for_refund	string	The note attached to the refund.
refund_data	object	(optional) Additional refund transaction data for specific payment gateway integrations.

Refund any Amount

POST /api/v1/{platform}/{shop}/orders/{order_id}/refund/arbitrary_amount

This end point tries to refund has much of the requested refund as possible against any captured transactions on the order. This endpoint does not perform any currency conversions.

Example Create Refund for $200.00:

{
  "reason_for_refund": "Product arrived broken",
  "amount": 200.0
}

Example Create Refund for $200.00:

{
  "success": true,
  "amount_refunded": 200.0,
  "transaction_details": [
    {
      "errors": [],
      "success": true,
      "transaction_number": "payment-12345",
      "amount": 200.0
    }
  ]
}

Route Parameters

Key	Description	Example
order_id	The Bold public_order_id identifier for the order.	jhdhVh3OdvFNG...

Body Parameters

Key	Type	Description
amount	float	The amount to refund against the order. We will try to refund as much of this amount as possible.
reason_for_refund	string	The note attached to the refund.
refund_data	object	(optional) Additional refund transaction data for specific payment gateway integrations.

Refund by Line Item

POST /api/v1/{platform}/{shop}/orders/{order_id}/refund/item

This refunds a specific line item, and optionally restocks the item's inventory.

Example Create Refund for Line Item request:

{
  "email_notification": false,
  "reason_for_refund": "Product arrived broken",
  "line_items": [
    {
      "variant_id": 123456789,
      "quantity": 1,
      "restock_quantity": 0
    }
  ]
}

Example Create Refund for Line Item response:

{
  "success": true,
  "refunded_amount": 1.11,
  "transaction_details": [
    {
      "errors": [],
      "success": true,
      "transaction_number": "payment-12345",
      "amount": 1.11
    }
  ]
}

Example 2 Create Refund for Line Item request:

{
  "email_notification": false,
  "reason_for_refund": "Product arrived broken",
  "line_items": [
    {
      "sku": "4011",
      "quantity": 1,
      "restock_quantity": 0,
      "refund_data": { "banana": true }
    }
  ]
}

Example 2 Create Refund for Line Item response:

{
  "success": true,
  "refunded_amount": 2.13,
  "transaction_details": [
    {
      "errors": ["Failed to refund on payment gateway: Refund Declined"],
      "success": false,
      "transaction_number": "fks72ngf01ndjks",
      "amount": 2.13
    },
    {
      "errors": [],
      "success": true,
      "transaction_number": "payment-12345",
      "amount": 1.11
    },
    {
      "errors": [],
      "success": true,
      "transaction_number": "payment-67890",
      "amount": 1.02
    }
  ]
}

Route Parameters

Key	Description	Example
order_id	The Bold public_order_id identifier for the order.	jhdhVh3OdvFNG...

Body Parameters

Key	Type	Description
email_notification	boolean	Whether or not Cashier will send the customer an email notification. If true, an email will be sent.
reason_for_refund	string	The note attached to the refund.
line_items	array	The line items this refund is being issued against. Can be identified by variant_id or sku.
line_items[].variant_id	int	The identifier for an individual line item.
line_items[].sku	string	The identifier for an individual line item.
line_items[].line_item_key	string	The identifier for an individual line item.
line_items[].quantity	int	The quantity of line items to refund.
line_items[].restock_quantity	int	The quantity of line items to restock inventory for.
line_items[].refund_data	object	(optional) Additional refund transaction data for specific payment gateway integrations.
amount	float	(optional) The amount to refund against the order in dollars. We will try to refund as much of this amount as possible if it is set, if not we will calculate amount from the requested items.
refund_data	object	(optional) Additional refund transaction data for specific payment gateway integrations.

Refund by Flat Amount

POST /api/v1/{platform}/{shop}/orders/{order_id}/refund/amount

This refunds a set amount of order, refunding against the provided transaction ID.

Example Create Refund Flat Amount request:

{
  "email_notification": false,
  "reason_for_refund": "Product arrived broken",
  "transactions": [
    {
      "platform_transaction_id": 123456789,
      "amount": 81.94
    }
  ]
}

Example Create Refund Flat Amount response:

{
  "success": true
}

Route Parameters

Key	Description	Example
order_id	The Bold public_order_id identifier for the order.	jhdhVh3OdvFNG...

Body Parameters

Key	Type	Description
email_notification	boolean	Whether or not Cashier will send the customer an email notification. If true, an email will be sent.
reason_for_refund	string	The note attached to the refund.
transactions	array	The list of transactions to refund.
transactions[].platform_transaction_id	int	The identifier of the transaction to refund.
transactions[].amount	int	The amount to refund to the provided transaction.

Shipping Rates

Shipping Rates For Cart

POST /api/v1/{platform}/{shop}/shipping_lines

Example Request

{
  "order": {
    "customer": {
      "shipping_address": {
        "address": "50 Fultz Blvd",
        "city": "Winnipeg",
        "country_code": "CA",
        "province_code": "MB",
        "postal_code": "R3Y 0L6"
      }
    },
    "items": [
      {
        "price": 500,
        "quantity": 1,
        "grams": 250
      },
      {
        "price": 300,
        "quantity": 2,
        "grams": 150
      }
    ]
  }
}

Requires read_shipping_lines scope.

Request Parameters

Key	Type	Description
order.customer.shipping_address	object	The destination shipping address. See Shipping/Billing Addresses
order.items	array	The line items to be shipped
order.items[].price	currency	Price of the line item
order.items[].quantity	integer	Quantity of the line item
order.items[].grams	integer	Weight of the product in grams

Example Response

{
  "success": true,
  "shipping_lines": [
    {
      "id": 0,
      "shipping": {
        "name": "fixed rate",
        "price": 500,
        "free_shipping": false,
        "code": "fixed rate"
      }
    },
    {
      "id": 1,
      "shipping": {
        "name": "percentage rate",
        "price": 138,
        "free_shipping": false,
        "code": "percentage rate"
      }
    }
  ]
}

Response Parameters

Key	Type	Description
shipping_lines	array	The shipping rates returned from the configured carrier(s).

Shop

Basic Shop Information

GET /api/v1/{platform}/{shop}/shop

Example Response

{
  "success": true,
  "shop": {
    "domain": "myshop.example.com",
    "name": "example-shop",
    "is_delayed_payment_capture_enabled": true
  }
}

Requires read_shop_settings scope.

Request Parameters

None

Response Parameters

Key	Type	Description
domain	string	The domain of the shop.
name	string	The name of the shop.
is_delayed_payment_capture_enabled	boolean	The shop's setting for allowing payment capture to be delayed by default.

Get Shop App Fee

GET /api/v1/{platform}/{shop}/shop/fees

Example Response

{
  "type": "percent",
  "value": 0.0025
}

Requires read_shop_settings scope.

Request Parameters

None

Response Parameters

Key	Type	Description
type	string	The type of fee, percent or fixed.
value	float	The value of the fee. (e.g., 0.0025 would be 0.25%)

Is Cashier Enabled

GET /api/v1/{platform}/{shop}/shop/enabled

Example Response

{
  "enabled": true
}

Requires read_shop_settings scope.

Request Parameters

None

Response Parameters

Key	Type	Description
enabled	boolean	Whether Cashier is enabled.

Tax Rates

Tax Rates for Customer

POST /api/v1/{platform}/{shop}/tax_rates

Example Request

{
  "order": {
    "customer": {
      "shipping_address": {
        "country": "Canada",
        "country_code": "CA",
        "province_code": "MB",
        "postal_code": "R3Y 0L6"
      }
    },
    "items": [
      {
        "quantity": 1,
        "price": 3495,
        "grams": 1000
      }
    ]
  }
}

Example Response

{
  "tax_rates": {
    "cart_taxes": {
      "0": {
        "name": "GST",
        "amount": 175,
        "rate": "0.0500"
      },
      "1": {
        "name": "PST",
        "amount": 245,
        "rate": "0.0700"
      }
    },
    "shipping_taxes": {
      "0": {
        "name": "GST",
        "amount": 40,
        "rate": "0.0500",
        "translation_key": "_gst"
      },
      "1": {
        "name": "PST",
        "amount": 56,
        "rate": "0.0700",
        "translation_key": "_pst"
      }
    },
    "tax_shipping": true,
    "taxes_included": false
  }
}

Requires read_tax_rates scope.

Request Parameters

Key	Type	Description
order.customer.shipping_address	object	The destination shipping address. See Shipping/Billing Addresses

Response Parameters

Key	Type	Description
tax_rates.cart_taxes	array	The tax rates which apply to the line items.
tax_rates.shipping_taxes	array	(Optional) The tax rates which apply to the shipping method.
tax_rates.tax_shipping	boolean	Whether tax applies to the shipping method.
tax_rates.taxes_included	boolean	Whether tax is included in the line item prices.

Zones

Custom Shipping Rates

GET /api/v1/{platform}/{shop}/zones/{zone_id}/custom_shipping_rates

Example Response

{
  "success": true,
  "custom_shipping_rates": [
    {
      "enabled": 1,
      "lower_bound": 0,
      "upper_bound": 9999,
      "no_upper_bound": 0,
      "price": 500,
      "name": "CustomShipping1",
      "fee_type": 0,
      "base_on_weight": 0
    },
    {
      "enabled": 1,
      "lower_bound": 5,
      "upper_bound": 10,
      "no_upper_bound": 0,
      "price": 10,
      "name": "CustomShipping2",
      "fee_type": 1,
      "base_on_weight": 0
    }
  ]
}

This endpoint lets you get a list of all the custom shipping rates associated with a specific zone.

Requires read_shipping_zones scope

Request Parameters

None

Example Error Response Body

{
  "success": false,
  "errors": ["Zone 123 does not exist"]
}

Response Parameters

Key	Type	Description
custom_shipping_rates	array	The custom shipping rates associated with the given zone ID.

Has Region For Address

POST /api/v1/{platform}/{shop}/zones/{zone_id}/has_region

Example Request

{
  "country_code": "CA",
  "province_code": "MB"
}

This endpoint enables you check if a given address has a region within a specific zone.

Requires read_shipping_zones scope

Request Parameters

Key	Type	Description
country_code	string	ISO code for country.
province_code	string	ISO code for province.

Example Response Where Region Was Found

{
  "success": true,
  "has_region": true,
  "message": "Region found for the address provided."
}

Example Responses Where Region Was Not Found

{
  "success": true,
  "has_region": false,
  "message": "Could not find matching region for the address provided."
}

{
  "success": true,
  "has_region": false,
  "message": "Could not find matching country for the code provided."
}

{
  "success": true,
  "has_region": false,
  "message": "Could not find matching province for the code provided."
}

Response Parameters

Key	Type	Description
has_region	boolean	Whether the zone has a region defined for the given address.
message	string	Message detailing whether or not the region was found.

List Zones

GET /api/v1/{platform}/{shop}/zones

Example Response

{
  "success": true,
  "zones": [
    {
      "id": 1,
      "name": "Canada",
      "zone_type": "shipping",
      "default_zone": true,
      "is_hidden": false,
      "is_enabled": true
    },
    {
      "id": 2,
      "name": "World default",
      "zone_type": "tax",
      "default_zone": false,
      "is_hidden": false,
      "is_enabled": true
    }
  ]
}

This endpoint enables you to get all of the zones for a given shop.

Requires read_zones scope.

Request Parameters

None

Response Parameters

Key	Type	Description
name	string	The name of the zone.
zone_type	string	The type of zone (e.g., warehouse, shipping, tax).
default_zone	boolean	Whether the zone is the default one.
is_hidden	boolean	Whether the zone is hidden in Cashier admin.
is_enabled	boolean	Whether the zone is enabled.

Analytics

Cashier allows custom tracking scripts to execute after the order is completed.

JavaScript Globals

Example BOLD.order

{
  "id": 3596173495,
  "cart_params": {
    "custom_tracking_id": "1234"
  },
  "currency": "CAD",
  "customer": {
    "email": "customer@example.com",
    "first_name": "",
    "last_name": "",
    "tags": "",
    "accepts_marketing": false
  },
  "billing_address": {
    "address1": "50 Fultz blvd",
    "address2": "",
    "city": "Winnipeg",
    "company": "Bold Commerce",
    "country": "Canada",
    "country_code": "CA",
    "first_name": "Test",
    "last_name": "User",
    "phone": "204-808-8095",
    "province": "Manitoba",
    "province_code": "MB"
  },
  "discounts": {
    "lines": [
      {
        "value": 399,
        "lineText": "10PERCENT",
        "tag": "Discount",
        "discount_type": "percent",
        "discount_percent": 10,
        "application_uuid": null
      }
    ],
    "total": 399
  },
  "line_items": [
    {
      "sku": "mediumtreefinch",
      "title": "Medium tree finch",
      "price": 3995,
      "quantity": 1,
      "total_price": 3995,
      "platform_variant_id": 25676780168,
      "platform_product_id": 7869320840
    }
  ],
  "shipping_address": {
    "address1": "50 Fultz blvd",
    "address2": "",
    "city": "Winnipeg",
    "company": "Bold Commerce",
    "country": "Canada",
    "country_code": "CA",
    "first_name": "Test",
    "last_name": "User",
    "phone": "204-808-8095",
    "province": "Manitoba",
    "province_code": "MB"
  },
  "subtotal": 3995,
  "total_shipping": 500,
  "total_tax": 520,
  "total": 5015,
  "resumable_url": "https://example.com/order/abc123",
  "public_order_id": "abc123"
}

Example BOLD.order with Recurring Orders Data

{
  "customer": {
    "email": "customer@example.com",
    "first_name": "",
    "last_name": "",
    "tags": "",
    "accepts_marketing": false
  },
  "billing_address": {
    "first_name": "Test",
    "last_name": "User",
    "company": "Bold Commerce",
    "address1": "50 Fultz blvd",
    "address2": "",
    "city": "Winnipeg",
    "country": "Canada",
    "country_code": "CA",
    "province": "Manitoba",
    "province_code": "MB",
    "postal_code": "r3y0l6",
    "phone": "204-808-8095"
  },
  "shipping_address": {
    "first_name": "Test",
    "last_name": "User",
    "company": "Bold Commerce",
    "address1": "50 fultz blvd",
    "address2": "",
    "city": "Winnipeg",
    "country": "Canada",
    "country_code": "CA",
    "province": "Manitoba",
    "province_code": "MB",
    "postal_code": "r3y0l6",
    "phone": "204-808-8095"
  },
  "line_items": [
    {
      "sku": "BLUEBOLD",
      "title": "Blue Item",
      "product_title": "Blue Item",
      "variant_title": null,
      "price": 2500,
      "quantity": 1,
      "total_price": 2500,
      "platform_variant_id": 13234326700132,
      "platform_product_id": 1438083121252,
      "properties": {
        "frequency_num": "1",
        "frequency_type": "2",
        "frequency_type_text": "Week(s)",
        "group_id": "563",
        "discounted_price": "$25.00",
        "_ro_discount_percentage": "50",
        "_ro_unformatted_price": "2500",
        "total_recurrences": "3",
        "Recurring Order": "Every 1 Week(s)"
      }
    }
  ],
  "shipping_line": {
    "name": "Testing",
    "price": 100,
    "free_shipping": false,
    "code": "Testing"
  },
  "currency": "CAD",
  "currency_format": "${{amount}}",
  "exchange_rate": 1,
  "total": 2925,
  "total_remaining": 2925,
  "payments": [],
  "discounts": [
    {
      "value": 250,
      "lineText": "RODISCOUNT",
      "tag": "Discount",
      "discount_type": "percent",
      "discount_percent": "10.00",
      "application_uuid": null
    }
  ],
  "resumable_url": "https://example.com/order/abc123",
  "public_order_id": "abc123"
}

Cashier defines the following globals for use by custom tracking scripts:

Key	Description
BOLD.order	The completed order.
BOLD.order.id	The identifier for the order.
BOLD.order.cart_params	Cart parameters associated with the order.
BOLD.order.currency	The currency the order was processed in.
BOLD.order.customer	The customer that placed the order.
BOLD.order.billing_address	The address connected to the order payment.
BOLD.order.discounts	The collection of discounts applied to the order.
BOLD.order.line_items	An array of the line items purchased with the order.
BOLD.order.line_items[].sku	The Stock Keeping Unit identifier for the purchased line item.
BOLD.order.line_items[].title	The title of the purchased line item.
BOLD.order.line_items[].price	The price of the purchased line item in cents.
BOLD.order.line_items[].quantity	The quantity of the purchased line item.
BOLD.order.line_items[].total_price	The total price of the purchased line item in cents.
BOLD.order.line_items[].platform_variant_id	The platform-specific identifier for the purchased line item's variant.
BOLD.order.line_items[].platform_product_id	The platform-specific identifier for the purchased line item's product.
BOLD.order.shipping_address	The address where the order will be shipped to.
BOLD.order.subtotal	The total order value pre-shipping, pre-tax, and pre-discounts in cents.
BOLD.order.total_shipping	The shipping cost of the order in cents.
BOLD.order.total_tax	The amount of tax for the order in cents.
BOLD.order.total	The final order price (post-tax, post-shipping, and post-discounts) in cents.
BOLD.order.resumable_url	A URL that lets you resume the order in it’s current state.
BOLD.order.public_order_id	Bold’s unique identifier for the order.

General Platform

Cashier can be integrated with custom eCommerce platforms using the General Platform API. This allows websites to handle all other facets of an online store while using Cashier to process payments and finalize orders.

Checkout Button

The request sent when the customer checks out should have the following parameters:

https://cashier.boldcommerce.com/general/{$store_url}/{$cart_id}?bold_cart_params={$cart_params}

Key	Type	Description
store_url	string	The shop’s domain name as registered with Cashier.
cart_id	integer	A unique ID generated by your system that allows Cashier to find the contents and data relating to a particular cart.
cart_params	string	Additional optional fields used by third-party plugins to function.

Getting the Cart

GET https://www.example_shop.com/cart?cart_id=1234

Example response:

{
  "cart": {
    "id": 1234,
    "weight": 100,
    "item_count": 3,
    "requires_shipping": true,
    "currency": "CAD",
    "override_shipping": true,
    "line_items": [
      {
        "id": 112233,
        "quantity": 2,
        "title": "Product Title",
        "variant_title": "Variant Title",
        "weight": 50,
        "taxable": true,
        "image": "https://example.com/thing.jpg",
        "requires_shipping": true,
        "price": "2000"
      },
      {
        "id": 112234,
        "quantity": 1,
        "title": "The Thing",
        "variant_title": "The Thing - Red",
        "weight": 50,
        "taxable": false,
        "image": "https://example.com/red-thing.png",
        "requires_shipping": true,
        "price": 2500
      }
    ],
    "customer": {
      "id": 334455,
      "email": "john.smith@boldcommerce.com",
      "first_name": "John",
      "last_name": "Smith",
      "addresses": [
        {
          "first_name": "John",
          "last_name": "Smith",
          "company": "Bold Commerce",
          "address1": "50 Fultz Blvd",
          "address2": "",
          "city": "Winnipeg",
          "province": "Manitoba",
          "country": "Canada",
          "zip": "R3Y 0L6",
          "country_code": "CA",
          "province_code": "MB",
          "default": true
        }
      ]
    },
    "shipping_lines": [
      {
        "display_text": "Slow Shipping",
        "value": 1000
      },
      {
        "display_text": "Fast Shipping",
        "value": 4000
      }
    ]
  }
}

To ensure the validity and integrity of a cart, Cashier does not accept any data pertaining to the order from the customer’s browser request. Instead, the browser request contains a cart_id and Cashier contacts your eCommerce platform to get the order’s contents and details.

We’ll make a GET request over HTTPS to any endpoint specified with the cart_id as the parameter.

Optional Parameters

The example to the right shows all the values that can be set, the following are optional in the cart object:

Key	Type	Description
currency	string	Allows the order to be set to a different currency than the store default.
customer	object	This is used for two things. If the customer's id is present, we treat this as a logged in customer, which means you must have authenticated the user. This allows the customer to save their credit cards for reuse. The rest of the details are used to pre-populate the checkout form for the customer. Multiple addresses can be provided and the customer will be able to choose from that list when they checkout.
override_shipping	boolean	Skips the cashier shipping service and presents the shipping lines that are included. Setting this to true makes cart.shipping_lines mandatory.
shipping_lines	object	Only required if cart.override_shipping is set to true. We will present these shipping options to the customer instead of looking up the shipping rates.

Order

Lifecycle

1. The customer interacts with your website and selects their products, which are added to a cart/order.

2. A Checkout button on your website is pointed to https://cashier.boldcommerce.com/general/{your_domain_here}/{cart_id} (see the Checkout Button Details section below for information on required parameters), and the customer is redirected to Cashier so that we can handle the checkout.

3. Cashier uses the cart_id from the request and makes an API call to your eCommerce platform to ask for data on the cart/order.

4. Using the data about the cart returned from the API call, Cashier starts a customer checkout session.

5. The customer proceeds through the checkout flow, completing shipping information and entering payment details. Once their submission is finished, Cashier processes the order. If the order is processed without error, a webhook will be sent to you.

6. Cashier sends an additional webhook to you with the completed order details, if the order contains items that can be fulfilled immediately.

7. When an order is fulfilled, Cashier sends a webhook to you with the fulfilled order details.

8. If an order fails to get created for any reason, such as malformed data, Cashier sends a webhook to you with the failed order details.

Plugins

API Endpoints

Uninstall Callback URL

Cashier will POST to this endpoint if the shop owner chooses to uninstall the plugin.

Cashier adds a query string to the request:

• platform: the eCommerce platform which the shop belongs to
• shop: the platform-unique identifier for the shop

Checkout Actions

Example Cashier Event Response:

{
  "success": true,
  "actions": [
    {
      "type": "ADD_NOTE",
      "data": {
        "note": "This note was added by a Cashier plugin"
      }
    },
    {
      "type": "APP_UPDATE_WIDGET",
      "data": {
        "name": "example_widget",
        "type": "external_link",
        "position": "line_items",
        "text": "Click here to read our return policy",
        "icon": "https://example.com/returns.png",
        "link_url": "https://example.com/return-policy"
      }
    }
  ]
}

Checkout actions are how plugins manipulate the customer checkout.

Inspired by Redux, actions are simple JSON objects.

Key	Type	Description
type	string	Identifies the action to perform
data	object	Contains parameters specific to the action type

**NOTE:** Cashier assumes all actions sent by a plugin have been verified beforehand and found legitimate. It is the responsibility of the plugin to make sure an action is not fraudulent before sending the action to Cashier.

ADD_AUTHORIZED_PAYMENT

This action allows plugins to add an authorized payment to the order.

{
  "success": true,
  "actions": [
    {
      "type": "ADD_AUTHORIZED_PAYMENT",
      "data": {
        "currency": "USD",
        "value": 27500000,
        "line_text": "I.O.U.",
        "gateway_name": "Honour System",
        "metadata": {
          "note": "for the car"
        },
        "reference_id": "ABCD1234"
      }
    }
  ]
}

Requires add_payments scope.

Key	Type	Description
currency	string	ISO 4217 currency code.
value	currency	The amount to reduce the outstanding balance.
line_text	string	Description of the payment method for the order summary.
gateway_name	string	Name of the payment gateway for display.
metadata	object	(Optional) Extra information about the payment.
reference_id	string	Your reference ID for the payment.

ADD_CART_PARAMS

{
  "success": true,
  "actions": [
    {
      "type": "ADD_CART_PARAMS",
      "data": {
        "cart_params": {
          "custom_value": "test value"
        }
      }
    }
  ]
}

Add custom cart parameters to the order.

NOTE: Reusing the same keys for multiple ADD_CART_PARAMS actions will overwrite existing values.

Requires modify_order scope.

Key	Type	Description
cart_params	object	Object containing Key:Value pairs that will be added to the order's cart params.

ADD_DISALLOWED_LINE_ITEM_PROPERTIES

{
  "success": true,
  "actions": [
    {
      "type": "ADD_DISALLOWED_LINE_ITEM_PROPERTIES",
      "data": {
        "disallowed_line_item_properties": ["test_property", "another_test_property"]
      }
    }
  ]
}

This action allows plugins to specify which line item properties should not be visible in the order notes, after the order is processed.

Requires modify_order scope.

Key	Type	Description
disallowed_line_item_properties	array	Keys for the line item properties that will be hidden.

ADD_FEE

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

Requires add_fee scope. Can be removed by the REMOVE_FEE action.

Key	Type	Description
id	string	A unique identifier for this fee
line_text	string	A short description (e.g. "Gift wrapping").
fee_type	string	percentage or fixed.
taxable	boolean	required
value	numeric	If 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_amendment	boolean	(Optional) If it is the fee is an amendment.

ADD_LINE_ITEM

{
  "success": true,
  "actions": [
    {
      "type": "ADD_LINE_ITEM",
      "data": {
        "id": 12345,
        "title": "Test Product",
        "image": "https://example.com/thing.jpg",
        "properties": {
          "gift_wrap": "yes"
        },
        "description": "A test product.",
        "quantity": 1,
        "price": 1500,
        "taxable": true,
        "weight": 2,
        "weight_unit": "kg",
        "line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
        "product_title": "Test Product",
        "variant_title": "Test Variant",
        "platform_variant_id": 9153875214378,
        "platform_type": "shopify",
        "sku": "TEST_SKU",
        "is_amendment": true
      }
    }
  ]
}

Add a line item to the cart. Can be removed with the REMOVE_LINE_ITEM_BY_KEY action.

Requires add_cart_item scope.

Key	Type	Description
id	integer	A unique identifier for ths line item.
title	string	Combined name of the line item.
image	string	(Optional) Image URL for the line item.
properties	object	Extra metadata about the line item (Optional).
description	string	Product description.
quantity	integer	The quantity of the line item.
price	integer	The price of the product in cents.
taxable	boolean	Whether the line item is taxable or not.
weight	integer	Weight of the line item.
weight_unit	string	Unit of the weight.
line_item_key	string	Unique identifier of this line item.
product_title	string	Name of the product.
variant_title	string	Name of the variant.
platform_variant_id	integer	Platform specific ID of the variant associated with this line item.
platform_type	string	Which eCommerce platform this line item belongs to.
sku	string	(Optional) The SKU of the line item.
is_amendment	boolean	(Optional) If it is an amendment to a line item.

ADD_LINE_ITEM_BY_PLATFORM_VARIANT

{
  "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 a line item to the cart. Can be removed with the REMOVE_LINE_ITEM_BY_KEY action.

Requires add_cart_item scope.

Key	Type	Description
platform_variant_id	integer	Platform specific ID of the variant associated with this line item.
line_item_key	string	(Optional) Unique identifier of this line item.
quantity	integer	(Optional) The quantity of the line item.
properties	object	(Optional) Extra metadata about the line item.
price	integer	(Optional) Will override the price of the product with this value in cents.
is_amendment	boolean	(Optional) If it is an amendment to a line item.

ADD_LINE_ITEM_PROPERTY

{
  "success": true,
  "actions": [
    {
      "type": "ADD_LINE_ITEM_PROPERTY",
      "data": {
        "line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
        "property": {
          "name": "test_prop",
          "value": "some sort of property"
        }
      }
    }
  ]
}

Allows a plugin to add line item properties to a specific line item.

Requires the modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.
name	string	Name of the key for the new property.
value	string	The value of the new property.

ADD_NOTE

{
  "success": true,
  "actions": [
    {
      "type": "ADD_NOTE",
      "data": {
        "note": "I'm a note"
      }
    }
  ]
}

Requires modify_order scope.

Key	Type	Description
note	string	A note which will be appended to the order.

ADD_NOTE_ATTRIBUTE

Requires modify_order scope.

{
  "success": true,
  "actions": [
    {
      "type": "ADD_NOTE_ATTRIBUTE",
      "data": {
        "name": "example_attribute",
        "value": "Some value"
      }
    }
  ]
}

Allows a plugin to add a new custom note attribute to the order.

Key	Type	Description
name	string	Name of the key for the new note attribute.
value	string	The value of the new note attribute.

ADD_PAYMENT

Requires add_payments scope.

{
  "success": true,
  "actions": [
    {
      "type": "ADD_PAYMENT",
      "data": {
        "currency": "USD",
        "value": 27500000,
        "line_text": "I.O.U.",
        "gateway_name": "Honour System",
        "metadata": {
          "note": "for the car"
        }
      }
    }
  ]
}

Key	Type	Description
currency	string	ISO 4217 currency code.
value	currency	The amount to reduce the outstanding balance.
line_text	string	Description of the payment method for the order summary.
gateway_name	string	Name of the payment gateway for display.
metadata	object	(Optional) Extra information about the payment.

ADD_SHIPPING_LINES_VALUE

Requires modify_shipping scope.

{
  "success": true,
  "actions": [
    {
      "type": "ADD_SHIPPING_LINES_VALUE",
      "data": {
        "add": 150,
        "lineText": "Example value."
      }
    }
  ]
}

Allows a plugin to adjust the shipping total of an order, this includes lowering the price by supplying a negative integer. The text description of this adjustment will replace the description of the regular shipping rate in the order summary.

Key	Type	Description
add	integer	Amount in cents to adjust the shipping total. (e.g. 150 = $1.50).
lineText	string	Description of the additional shipping cost for the order summary.

ADD_TAG

{
  "success": true,
  "actions": [
    {
      "type": "ADD_TAG",
      "data": {
        "name": "this is a tag"
      }
    }
  ]
}

Requires add_tags scope.

Adds a tag to the order. This will push the tag to the platform if supported.

Key	Type	Description
name	string	A tag which will be appended to the order.

ADJUST_LINE_ITEM_PRICE

{
  "success": true,
  "actions": [
    {
      "type": "ADJUST_LINE_ITEM_PRICE",
      "data": {
        "line_item_key": "AABBCC123",
        "value": 150
      }
    }
  ]
}

Allows a plugin to adjust a line item by the amount specified in value. A positive value will increase the price and a negative value will decrease the price.

Requires the modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.
value	integer	Amount in cents to adjust the price (e.g. 150 = $1.50).

APP_UPDATE_WIDGET

This action allows plugins to initialize and modify checkout widgets.

CHANGE_BILLING_ADDRESS

{
  "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": "204-678-9087",
        "city": "Winnipeg",
        "province": "Manitoba",
        "province_code": "MB",
        "country": "Canada",
        "country_code": "CA",
        "postal_code": "R3Y 0L6"
      }
    }
  ]
}

This action allows a plugin to change the billing address on an order. This action triggers the billing_address_changed plugin event.

Requires modify_order scope.

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 shipping address
address	string	Line 1 of the shipping address
address2	string	Line 2 of the shipping address
phone	string	Phone number of the shipping address
city	string	City of the shipping address
province	string	Province of the shipping address
province_code	string	Province code of the shipping address
country	string	Country of the shipping address
country_code	string	Country code of the shipping address
postal_code	string	Postal code of the shipping address

CHANGE_SHIPPING_ADDRESS

{
  "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": "204-678-9087",
        "city": "Winnipeg",
        "province": "Manitoba",
        "province_code": "MB",
        "country": "Canada",
        "country_code": "CA",
        "postal_code": "R3Y 0L6",
        "update_billing": true,
        "different_billing_address": true
      }
    }
  ]
}

This action allows a plugin to change the shipping address on an order. This action triggers the shipping_address_changed plugin event.

Requires modify_shipping_address scope.

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 shipping address
address	string	Line 1 of the shipping address
address2	string	Line 2 of the shipping address
phone	string	Phone number of the shipping address
city	string	City of the shipping address
province	string	Province of the shipping address
province_code	string	Province code of the shipping address
country	string	Country of the shipping address
country_code	string	Country code of the shipping address
postal_code	string	Postal code of the shipping address
update_billing	boolean	Whether to update the billing address to the previous shipping address. When this key is set to true, Cashier will send the billing_address_changed plugin event.
different_billing_address	boolean	Whether to select "Use a different billing address" on the checkout page

CLEAR_CHANGE_SHIPPING_ADDRESS

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

Allows a plugin to clear all changes to shipping address previously created with the CHANGE_SHIPPING_ADDRESS action. This action will only clear shipping address changes by this plugin. User-entered data will not be removed.

Requires modify_shipping_address scope.

This action has no parameters.

DELAY_PAYMENT_CAPTURE

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

Allows a plugin to delay the payment capture on an order. This is equivalent to enabling Delay Payment Capture in the Cashier admin, but for an individual order.

Requires modify_order scope.

This action has no parameters.

DELAY_PLATFORM_ORDER

{
  "success": true,
  "actions": [
    {
      "type": "DELAY_PLATFORM_ORDER",
      "data": {
        "seconds": 120
      }
    }
  ]
}

Allows a plugin to delay an order from being processed up to a maximum of 600 seconds. This action automatically sets an order to be amendable and allows a plugin to amend an order after the customer reaches the thank you page during checkout. The customer doesn't 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 as long as it does so within the time limit set by this action.

Requires modify_order scope.

Key	Type	Description
seconds	integer	Amount of seconds to delay the order.

DISABLE_ORDER_CONFIRMATION_EMAIL

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

Allows a plugin to disable the order confirmation email customers receive from Shopify after placing an order.

Requires modify_order_emails scope.

This action has no parameters.

DISCOUNT_CART

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

Applies a discount value to the entire cart.

If discountType is percentage, the discountPercentage field determines the deduction on the cart as a percentage of the order total. If discountType is fixed, the discountAmount field determines the deduction on the cart in base currency units using ISO-4217 standards.

Requires modify_cart scope.

Key	Type	Description
discountType	fixed or percentage	Determines type of discount applied to cart.
discountPercentage	integer	Percentage to discount the cart by. Required if discountType is percentage
discountAmount	integer	Amount to discount the cart by in base currency units. Required if discountType is fixed
transformationMessage	string	Description of the discount for the order summary.
platform_display_text	string	(Optional) Description of the discount for the order summary on the platform.

DISCOUNT_LINE_ITEMS

{
  "type": "DISCOUNT_LINE_ITEMS",
  "data": {
    "line_item_keys": ["17255784153145:88efe753c99a31ae7059ff6089dd1c7c"],
    "value": 10,
    "line_text": "This is a plugin discount",
    "discount_type": "percentage"
  }
}

The full discount value will be applied to each line item specified.

Requires modify_cart scope.

Key	Type	Description
discount_type	string	percentage or fixed.
line_item_keys	array	The list of line item keys to which the discount applies.
line_text	string	Description of the discount for the order summary.
value	numeric	If discount_type is percentage, this is the percentage If discount_type is fixed, this is the fixed amount.

HIDE_ALL_WALLET_PAY_GATEWAYS

Hides all wallet payment gateways or express payment gateways during checkout.

Requires modify_payment_methods scope.

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

HIDE_WALLET_PAY_GATEWAYS_BY_ID

Hides wallet payment gateways or express payment gateways based on public id during checkout.

Requires modify_payment_methods scope.

{
  "success": true,
  "actions": [
    {
      "type": "HIDE_WALLET_PAY_GATEWAYS_BY_ID",
      "data": {
        "public_payment_gateway_ids": [
          "WYlbwlX40PG84TLXxv1j0a36x4kNLWGDjiOlcLuYHLxDOOrA59m19ShFCHRjqzXc",
          "u8UlNCfO5YaB7eGDUMYyATyrLJO7SiazwWhoYUBrRM5cibxUlxJfhvlTVpXWHIUa"
        ]
      }
    }
  ]
}

Key	Type	Description
public_payment_gateway_ids	array	Array of shop payment gateway public id.

FLAG_ORDER_AS_BOPIS

Set Order as Bopis (Buy Online, Pick Up in Store) will hide shipping section and plugin will set shipping address as stores address.

Requires modify_shipping scope.

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

Key	Type	Description
flag_order_as_bopis	string	true to hide and false to unhide by plugin. It should be supported by setting data for shipping/billing addresses.
hidden_sections	object	List 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. Valid sections:
		shipping_address: Hides the shipping address section.
		saved_addresses: Hides the saved address section (when a customer is logged in).

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

MODIFY_THANK_YOU_REDIRECT

Provide an alternate "thank you" page to redirect to after completing a checkout.

Requires modify_thank_you_redirect scope.

{
  "success": true,
  "actions": [
    {
      "type": "MODIFY_THANK_YOU_REDIRECT",
      "data": {
        "url": "https://my-store.platform.com/thank-you"
      }
    }
  ]
}

Key	Type	Description
url	string	Valid URL.

MULTIPLY_SHIPPING_LINES_VALUE

Allows a plugin to multiply the total shipping amount.

{
  "type": "MULTIPLY_SHIPPING_LINES_VALUE",
  "data": {
    "multiplier": "2.0",
    "lineText": "Rush Shipping"
  }
}

Key	Type	Description
multiplier	numeric	Amount to multiply the total shipping value by.
lineText	string	Description of the multiplier. Will show up on the platform order under the Shipping section.

OVERRIDE_ADDRESS_VALIDATE

Requires provide_address_validation scope.

See Overrides.

Key	Type	Description
url	url	URL endpoint for AddressValidate override requests.

OVERRIDE_DISCOUNT

Requires provide_discounts scope.

See Overrides.

Key	Type	Description
url	url	URL endpoint for Discount override requests.

OVERRIDE_INVENTORY

Requires provide_shipping_rates scope.

See Overrides.

Key	Type	Description
url	url	URL endpoint for Inventory override requests.

OVERRIDE_SHIPPING

Requires provide_shipping_rates scope.

See Overrides.

Key	Type	Description
url	url	URL endpoint for Shipping override requests.

OVERRIDE_TAX

Requires provide_tax_rates scope.

See Overrides.

Key	Type	Description
url	url	URL endpoint for Tax override requests.

REMOVE_ALL_PAYMENTS

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

Allows a plugin to remove all payments previously created with the ADD_PAYMENT or ADD_AUTHORIZED_PAYMENT actions.

This action will not remove payments added by Cashier or by other plugins.

Requires add_payments scope.

This action has no parameters.

REMOVE_INDIVIDUAL_PAYMENT

{
  "success": true,
  "actions": [
    {
      "type": "REMOVE_INDIVIDUAL_PAYMENT",
      "data": {
        "id": "456"
      }
    }
  ]
}

Allows a plugin to remove individual payment previously created with the ADD_PAYMENT actions.

This action will not remove payments added by Cashier or by other plugins.

Requires add_payments scope.

Key	Type	Description
id	string	The unique identifier of the payment to remove.

REMOVE_FEE

{
  "success": true,
  "actions": [
    {
      "type": "REMOVE_FEE",
      "data": {
        "id": "gift-wrap-123"
      }
    }
  ]
}

Allows a plugin to remove a fee previously created with ADD_FEE.

Requires add_fee scope.

Key	Type	Description
id	string	The unique identifier of the fee to remove.

REMOVE_LINE_ITEM_BY_KEY

{
  "success": true,
  "actions": [
    {
      "type": "REMOVE_LINE_ITEM_BY_KEY",
      "data": {
        "line_item_key": "AABBCC123"
      }
    }
  ]
}

Allows a plugin to remove a line item previously created with ADD_LINE_ITEM or ADD_LINE_ITEM_BY_PLATFORM_VARIANT.

Requires modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.

REQUIRE_AMENDABLE

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

Flags the order as amendable which triggers the amend_order event after the order has been submitted.

Requires amend_orders scope.

This action has no parameters.

REQUIRE_STORED_PAYMENT_METHOD

{
  "success": true,
  "actions": [
    {
      "type": "REQUIRE_STORED_PAYMENT_METHOD",
      "data": {
        "require_stored_payment_method": true
      }
    }
  ]
}

Automatically selects the Remember this credit card option in the payments section of checkout. This will show an error message indicating this order requires a payment method if a storable method (PayPal, Credit Card) is not entered when completing an order.

Requires require_stored_payment_method scope.

SET_EXTERNAL_REDIRECT_URL

Allows a plugin to trigger a redirect away from Checkout. This action only works in response to the app_hook plugin event.

Before using this action, you must notify Bold of the URL to which you intend to redirect, so that the domain can be allow-listed. This is a security measure to prevent fraudulent redirects from occurring. You can create a support ticket here.

{
  "success": true,
  "actions": [
    {
      "type": "SET_EXTERNAL_REDIRECT_URL",
      "data": {
        "external_redirect_url": "www.example-payment-gateway.com/payments"
      }
    }
  ]
}

Requires modify_redirect scope.

SET_LINE_ITEM_POSITION

{
  "success": true,
  "actions": [
    {
      "type": "SET_LINE_ITEM_POSITION",
      "data": {
        "line_item_key": "AABBCC123",
        "position": 1
      }
    }
  ]
}

Allows a plugin to re-arrange the order in which line items appear in the summary of the checkout page.

Line items with a position will be sorted in ascending order, with any line item missing a position being placed at the end.

Requires the modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.
position	integer	The position for this line item to be placed in relative to other line items.

SET_LINE_ITEM_PRE_ORDER

{
  "success": true,
  "actions": [
    {
      "type": "SET_LINE_ITEM_PRE_ORDER",
      "data": {
        "line_item_key": "AABBCC123",
        "pre_order": true
      }
    }
  ]
}

Allows a plugin to set a line item as a pre-order item. Please reach out to our partners department to enable this feature.

Requires the modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.
pre_order	boolean	Whether the the line item is a pre-order item.

SET_LINE_ITEM_PRICE

{
  "success": true,
  "actions": [
    {
      "type": "SET_LINE_ITEM_PRICE",
      "data": {
        "line_item_key": "AABBCC123",
        "value": 150
      }
    }
  ]
}

Allows a plugin to set the price of a line item.

Requires the modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.
value	integer	The new price of the line item in cents (e.g. 150 = $1.50).

SET_LINE_ITEM_SHIPPING_ADDRESS

{
  "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": "204-678-9087",
        "city": "Winnipeg",
        "province": "Manitoba",
        "province_code": "MB",
        "country": "Canada",
        "country_code": "CA",
        "postal_code": "R3Y 0L6"
      }
    }
  ]
}

This action allows a plugin to change the shipping address of a line item. Please reach out to our partners department to enable this feature.

Requires modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.
first_name	string	First name of the customer
last_name	string	Last name of the customer
company	string	Company name of the shipping address
address	string	Line 1 of the shipping address
address2	string	Line 2 of the shipping address
phone	string	Phone number of the shipping address
city	string	City of the shipping address
province	string	Province of the shipping address
province_code	string	Province code of the shipping address
country	string	Country of the shipping address
country_code	string	Country code of the shipping address
postal_code	string	Postal code of the shipping address

SET_LINE_ITEM_TAXABLE

{
  "success": true,
  "actions": [
    {
      "type": "SET_LINE_ITEM_TAXABLE",
      "data": {
        "line_item_key": "AABBCC123",
        "taxable": false
      }
    }
  ]
}

Allows a plugin to set whether or not a line item is taxable.

Requires the modify_cart scope.

Key	Type	Description
line_item_key	string	Unique identifier of this line item.
taxable	boolean	Whether or not the line item is taxable.

SET_MANDATE

{
  "success": true,
  "actions": [
    {
      "type": "SET_MANDATE",
      "data": {
        "mandate_message": "The terms of the mandate."
      }
    }
  ]
}

Merchant-initiated transactions require an agreement (also known as a “mandate”) between the store and the customer. 'SET_MANDATE' allows a plugin to set the terms of the mandate that the customer can opt into. We display the terms of the mandate when the customer opts into allowing a payment gateway (with 3D Secure enabled) to save their credit card information.

Requires the modify_order scope.

Key	Type	Description
mandate_message	string	The terms of the mandate.

SET_ORDER_CREATED_BY

{
  "success": true,
  "actions": [
    {
      "type": "SET_ORDER_CREATED_BY",
      "data": {
        "created_by": "My Plugin"
      }
    }
  ]
}

This action allows a plugin to set the source application of the order, which can be helpful in differentiating between orders originating in Checkout versus a plugin.

Requires the modify_order scope.

Key	Type	Description
created_by	string	The originating system of the order.

SET_PAYMENT_GATEWAY

{
  "success": true,
  "actions": [
    {
      "type": "SET_PAYMENT_GATEWAY",
      "data": {
        "gateways": [
          {
            "public_id": "gatewayId1",
            "priority": 1
          },
          {
            "public_id": "gatewayId2",
            "priority": 2
          }
        ]
      }
    }
  ]
}

This action allows a plugin to dictate which payment gateway appears in Checkout. Gateways will appear in Checkout based on the "priority" field provided in ascending order, i.e. a gateway with priority 1 is higher priority than a gateway with priority 2+. Any gateways listed without a priority will appear at the bottom of the list in the order they appeared. The "public_id" for a specific gateway can be found in the Payment Gateway webhook or the List Payment Gateways endpoint.

Requires the modify_payment_gateways scope.

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.

SET_SHIPPING_RATE

Sets the shipping rate of the order.

Requires modify_shipping scope.

{
  "success": true,
  "actions": [
    {
      "type": "SET_SHIPPING_RATE",
      "data": {
        "shipping_rate": {
          "price": 100,
          "name": "fixed rate",
          "code": "fixed rate"
        }
      }
    }
  ]
}

Key	Type	Description
price	integer	Price of the rate.
name	string	Shipping friendly name for this rate.
code	string	Unique identifier for this rate.

SET_SPLIT_ORDER_CONDITION

Sets the condition and policies to split an order on. Please reach out to our partners department to enable this feature.

Requires modify_order scope.

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

Key	Type	Description
split_order_policy	string	How to create the new orders. Possible values are CREATE_NEW_ORDER and DIVIDE_ORDER
split_order_condition_type	string	The condition split the order on. Possible values are PREORDER and SHIPPING_ADDRESS
policy_types	object	Policies specify how to handle billing and how to split order level costs. If values are not provided they will be set to their default value.
policy_types.Billing	object	Specifies how to handle authorizing payment methods. Possible values are NEW_AUTH and PARTIAL_SETTLEMENT. Default value is NEW_AUTH
policy_types.ShippingCost	object	Specifies how to distribute the shipping cost over the split orders. Possible values are FIRST, LAST, ORDER_COUNT and ORDER_VALUE. Default value is FIRST
policy_types.Discount	object	Specifies how to distribute the discount value over the split orders. Possible values are FIRST, LAST, ORDER_COUNT, ORDER_VALUE ITEM. Default value is FIRST

Checkout Events

Plugins can manipulate a customer's ongoing checkout session by sending actions in response to events.

Event Dispatch URL

This is where Cashier will POST to with various information about the checkout session depending on event type. This includes order data, customer data, the cart and more. See the sidebar for an example.

Example Event Request Body:

{
  "cart": {
    "total_weight": 0,
    "item_count": 2,
    "requires_shipping": null,
    "bold_cart_id": 145,
    "cart_token": "19ef770ca493359fb7cfb955e76e1da9",
    "public_token": "b8e310398168cc8824182045cc8cabde750af025",
    "attributes": [],
    "line_items": [[]],
    "subtotal": 2468
  },
  "cart_params": [],
  "customer": {
    "core_info": {
      "first_name": "Bold",
      "last_name": "McBoldstein",
      "tags": "Bold",
      "public_id": "1h6j893jsdfewwe",
      "customer_id": 1234,
      "email": "test@boldcommerce.com",
      "billing_type": "same",
      "accepts_marketing": false
    },
    "shipping": {
      "first_name": "Bold",
      "last_name": "McBoldStein",
      "company": "Bold Commerce LTD",
      "address": "50 Fultz Blvd",
      "address2": "Another line",
      "city": "Winnipeg",
      "country": "Canada",
      "country_code": "CA",
      "province": "Manitoba",
      "province_code": "MB",
      "postal_code": "R3Y 1L6",
      "phone": "1 (234) 567-8901"
    },
    "billing": {
      "first_name": "Bold",
      "last_name": "McBoldStein",
      "company": "Bold Commerce LTD",
      "address": "50 Fultz Blvd",
      "address2": "Another line",
      "city": "Winnipeg",
      "country": "Canada",
      "country_code": "CA",
      "province": "Manitoba",
      "province_code": "MB",
      "postal_code": "R3Y 1L6",
      "phone": "1 (234) 567-8901"
    },
    "addresses": []
  },
  "order_id": 145,
  "properties": {},
  "idempotent_key": null,
  "shipping_lines": [],
  "tax_lines": [],
  "discount_lines": [],
  "order": {
    "order_source": "cashier",
    "order_source_name": "cashier",
    "public_order_id": "lakjfoihiuh223u82989vhsinvd0s9f8",
    "customer": {
      "id": 23,
      "public_customer_id": 22345345346,
      "platform_customer_id": 23,
      "core_info": [],
      "shipping_address": [],
      "billing_address": []
    },
    "currency": "SEK",
    "exchange_rate": "1.000000000000",
    "fees": [
      {
        "id": "gift-wrap-1",
        "value": 150,
        "lineText": "Gift wrapping",
        "tag": "Fee",
        "taxable": false
      }
    ],
    "order_total": 2468,
    "resumable_url": "https://example.com/order/abc123",
    "shipping": [
      {
        "id": "abc123",
        "value": 5000,
        "price": 5000,
        "lineText": "Express Rate",
        "name": "Express Rate",
        "code:": "Express Rate",
        "source": "",
        "tag": "Shipping",
        "delivery_date": "",
        "delivery_range": "",
        "delivery_days": ""
      }
    ],
    "note": "",
    "note_attributes": [],
    "tags": []
  },
  "language_iso": "fr",
  "event": "initialize_checkout"
}

Note: There will be times when all event response data is not populated. For example, on the initialize_checkout event, we will not have customer and shipping data filled out.

Event	Description
amend_order	Occurs after the customer completes checkout if the order is amendable.
api_amend_order	Occurs when an order is created via the API.
app_hook	Plugin-specific event triggered by a checkout widget.
billing_address_changed	Occurs after sending a CHANGE_BILLING_ADDRESS plugin action or a CHANGE_SHIPPING_ADDRESS action with update_billing set to true
discount_code_added	Occurs after a discount code has been successfully added.
discount_code_removed	Occurs after a discount code has been successfully removed.
initialize_app	Occurs once per full page load during checkout.
initialize_checkout	Occurs exactly once when the customer enters the checkout.
initialize_currency	When using Multi-Currency, indicates when currency is initialized. Note that this is before currency changes the prices in Cashier.
initialize_payment_gateway	Occurs when the payment gateway is first initialized.
order_changed	Occurs when the order is changed.
order_submitted	Occurs right before an order is submitted for pre-auth and payment has not yet been captured.
received_shipping_lines	Occurs after shipping lines are calculated.
shipping_address_changed	Occurs after sending a CHANGE_SHIPPING_ADDRESS plugin action.
toggle_billing_address	Occurs when the customer changes the Billing Address type from Same as shipping address to Use a different billing address or vice-versa.
validating_shipping_lines	Occurs when a shipping line is selected or the Continue to payment method button is clicked.

HTTP Signatures

Here is an example of signature verification using the 99designs/http-signatures package:

<?php
use HttpSignatures;
use Symfony\Component\HttpFoundation\Request;

$context = new HttpSignatures\Context([
    'keys' => ['api_secret' => getenv('CASHIER_CLIENT_SECRET'),
    'algorithm' => 'hmac-sha256',
]);

$request = Request::createFromGlobals();
$valid = $context->verifier()->isValid($request);

if (!$valid) {
    abort(401);
}

CASHIER_CLIENT_SECRET is your plugin's pre-shared secret key issued by Cashier.

Plugins must verify Cashier's HTTP signature to ensure that incoming requests are legitimate.

Overrides

Example Cashier Event Response which adds a shipping override:

{
  "success": true,
  "actions": [
    {
      "type": "OVERRIDE_SHIPPING",
      "data": {
        "url": "https://example.com/get-shipping-rates"
      }
    }
  ]
}

Plugins can override default Cashier functionality. Cashier will send a POST request to all override URLs provided.

Override Types

Type	Scope	Description
AddressValidate	provide_address_validation	Add an override for customer address validation.
Discount	provide_discounts	Add an override for discount codes.
Inventory	provide_shipping_rates	Add an override for inventory checks.
Shipping	provide_shipping_rates	Add an override for providing shipping rates.
Tax	provide_tax_rates	Add an override for calculating taxes.

AddressValidate

The POST request sent from Cashier for an override to be verified by the 3rd party app:

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

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 name.
province_code	string	ISO code for province.
country	string	Country name.
country_code	string	ISO code for country.
postal_code	string	Postal code / zip.
phone	string	Phone number.

Example of response that Cashier is expecting:

{
  "valid": false,
  "errors": [
    {
      "field": "postal_code",
      "error_message": "Code not valid for country and province"
    }
  ],
  "warnings": [
    {
      "field": "address",
      "warning_message": "Could not verify street address"
    }
  ]
}

Response

Key	Type	Description
valid	boolean	Whether the address is valid.
errors	array	Errors to display which the customer must fix before continuing.
errors[].field	string	The input field which the error corresponds to.
errors[].error_message	string	The error message to display.
warnings	array	Warnings to display which will not prevent the customer from continuing.
warnings[].field	string	The input field which the warning corresponds to.
warnings[].warning_message	string	The warning message to display.

Discount

Discount Types

Type	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.
PercentageExceptProductsInList	Discount an order's products except the provided list of products by a percentage.
FixedProductsInList	Discount an order's products that are in the provided list of products by a fixed amount.
PercentageProductsInList	Discount an order's products that are in the provided list of products by a percentage.

Discount Params

The parameters listed below are required for the following discount types:

• FixedExceptProductsInList
• PercentageExceptProductsInList
• FixedProductsInList
• PercentageProductsInList

Key	Type	Description
itemKeys	array	The list of line item keys which the discount applies to.

Example of a discount condition:

{
  "conditions": [
    {
      "name": "cartTotalMin",
      "params": {
        "value": "1"
      }
    }
  ]
}

Discount 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	(boolean) use_limit_reached	Limit the amount of times a discount can be used, per email

The POST request sent from Cashier for an override to be verified by the third-party app:

{
  "discount": "WINTERSALE",
  "platform_id": "example.myshopify.com",
  "platform": "shopify",
  "email_address": "customer@example.com"
}

Request

Key	Type	Description
discount	string	Discount code to verify.
shop	string	Platform-specific identifier.
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.

Example of response that Cashier is expecting:

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

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.
amount	integer	Discount amount.
conditions	array	Array of conditions.
params	array	Parameters for discount (if any) See Discount Params.
message	string	Message for discount (displayed on front end).
tag_line	string	Should always be set to Discount.

Inventory

The POST request sent from Cashier for an override to be verified by the 3rd party app:

{
  "type": "initial",
  "items": [
    {
      "sku": "AABBCC",
      "quantity": 1,
      "id": 1234
    }
  ],
  "shipping_address": {
    "first_name": "Jon",
    "last_name": "McBold",
    "company": "Bold",
    "address1": "50 Fultz Blvd",
    "address2": "Apt 100",
    "phone": "555-555-5555",
    "city": "Winnipeg",
    "province": "Manitoba",
    "province_code": "MB",
    "country": "Canada",
    "country_code": "CA",
    "postal_code": "R2K3S4"
  }
}

Request

Key	Type	Description
type	string	Values are initial or final. Used to indicate if this is the inventory check issued when the page first loads, or the final inventory check Cashier performs before processing the order.
items	array	Array of items. These are the items that Cashier to checking the inventory of
shipping_address	object	Only present on the final inventory check.

Item

Key	Type	Description
sku	string	The Item SKU
quantity	int	How many of this SKU are in the cart we're doing the inventory check for.
id	int	This is the Cart line item ID.

Response

Example Response:

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

The only difference from the request sent by Cashier is to add the available_quantity to the response.

Key	Type	Description
available_quantity	int	How many items are actually in inventory.

If the available quantity returned is less the number of that SKU in the cart, Cashier will fail the inventory check and redirect the customer to a page that will allow them to adjust their cart.

Shipping

The POST request sent from Cashier for an override to be verified by the 3rd party app:

{
  "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, //This could also be pounds, ounces or kilograms
        "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"
  }
}

Request

Key	Type	Description
cart	array	The cart array that contains line items.
source_address	object	The address that is being shipped FROM.
destination_address	object	Address that is being shipped TO.
cart[].title	string	Combined name of the line item.
cart[].product_title	string	Name of the product.
cart[].variant_title	string	Name of the variant.
cart[].image	url	URL for the line item's image asset.
cart[].properties	object	Extra metadata about the line item.
cart[].description	string	Product description.
cart[].quantity	integer	The quantity of the line item.
cart[].price	integer	The price of the product in cents.
cart[].total_price	integer	The price of the product after being multiplied by quantity in cents.
cart[].line_item_id	integer	Index of the line item in the cart array.
cart[].line_item_key	string	Unique identifier of this line item.
cart[].platform_variant	object	Platform specific data related to the variant of this line item.
cart[].includes_tax	boolean	Whether taxes are included in the price of the line item.
cart[].weight	integer	Weight of the line item.
cart[].platform_variant_id	integer	Platform specific ID of the variant associated with this line item.
cart[].platform_product_id	integer	Platform specific ID of this product.
cart[].sku	string	This line item's stock keeping unit.

Example of response that Cashier is expecting:

{
  "name": "My Custom Shipping Override",
  "rates": [
    {
      "line_text": "EXTERNAL SHIPPING SOURCE OVERNIGHT EXPRESS",
      "value": 15
    },
    {
      "line_text": "EXTERNAL ECONOMY SHIPPING 5-7 BUSINESS DAYS",
      "value": 10.5
    }
  ]
}

Response

Key	Type	Description
name	string	Type of override to register.
rates	array	Array of rates returned from the 3rd party resource.
line_text	array	Describes the shipping line (e.g. Expedited Shipping).
value	float	Value of shipping rate in dollars (e.g. 10.50 = $10.50).

Tax

The POST request sent from Cashier for an override to be verified by the 3rd party app:

{
  "store_addresses": [
    {
      "province": "MB",
      "country": "CA",
      "postal_code": "R2G4W3"
    }
  ],
  "shipping_address": {
    "province": "MB",
    "country": "CA",
    "postal_code": "R2K3S4"
  },
  "sub_total": 1,
  "shipping_total": 1
}

Request

Key	Type	Description
store_addresses	array	Array of source (FROM) addresses.
shipping_address	object	Destination (TO) address.
sub_total	boolean	Apply taxes to the subtotal.
shipping_total	boolean	Apply taxes to the shipping total.

Key	Type	Description
province	string	ISO code for province.
country	string	ISO code for country.
postal_code	string	Postal code / zip.

Example of response that Cashier is expecting:

{
  "shipping": [
    {
      "rate": 0.01,
      "name": "VAT"
    }
  ],
  "sub_total": [
    {
      "rate": 0.05,
      "name": "GST"
    },
    {
      "rate": 0.08,
      "name": "PST"
    }
  ]
}

Response

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

Payments

Plugins can act as payment gateways during checkout.

When a plugin uses the ADD_PAYMENT action, that plugin takes responsibility for authorizing, capturing, and refunding that payment for that order.

Orders may have multiple payments. For example, the customer may use a gift card against a portion of their order and a credit card for the remainder.

Authorize Endpoint

Example Authorize Request Body

{
  "order": {
    /* ... */
  },
  "payment": {
    "reference_id": "",
    "currency": "USD",
    "value": 27500000,
    "metadata": {
      "note": "for the car"
    }
  }
}

Example Authorize Success Response Body

{
  "success": true,
  "reference_id": "payment-12345"
}

Example Authorize Error Response Body

{
  "success": false,
  "error": "Payment exceeds maximum value"
}

This endpoint is responsible for obtaining payment authorization and responding with success or an error.

Cashier will POST to this endpoint once for each payment that the plugin has added to the order.

After all payments are successfully authorized, Cashier will send the order to the eCommerce platform.

If any payment authorization fails, the customer is returned to the Payment Method section of the checkout and an error message is displayed.

Capture Endpoint

Example Capture Request Body

{
  "order": {
    /* ... */
  },
  "payment": {
    "reference_id": "payment-12345",
    "currency": "USD",
    "value": 27500000,
    "metadata": {
      "note": "for the car"
    }
  }
}

Example Capture Success Response Body

{
  "success": true,
  "reference_id": "payment-12345"
}

Example Capture Error Response Body

{
  "success": false,
  "error": "Authorization expired"
}

This endpoint is responsible for capturing a payment following successful authorization.

Cashier will POST to this endpoint once for each payment that the plugin has added to the order.

If all payments are successfully captured, the order is marked as captured.

If any payment capture request fails, Cashier will retry and the merchant may be notified.

Refund Endpoint

Example Refund Request Body

{
  "order": {},
  "payment": {
    "reference_id": "payment-12345",
    "currency": "USD",
    "value": 27500000,
    "metadata": {
      "note": "for the car"
    }
  }
}

Example Refund Success Response Body

{
  "success": true,
  "reference_id": "payment-12345"
}

Example Refund Error Response Body

{
  "success": false,
  "error": "Refund amount is greater than captured amount"
}

This endpoint is responsible for cancelling authorized payments and refunding captured payments.

Cashier will POST to this endpoint once for each authorized payment that the plugin has added to the order.

Redirection Endpoints

Authorize Redirect URL

Example Request Body

{
  "client_id": "d5cb40ab-05af-4168-b1e0-a37660824779",
  "client_secret": "kjjcEyJdRzn1dusPU5aAChHZC1s3DWHS0ZdRKgxxIUbEPf6wqPRZTpJjUPmUj116",
  "code": "mnU8xUaGr1ACMDl793tnJEN7gBmT9SN8YLFcmRh7q72hIsy61HeYfHRUyjW0SxSL",
  "grant_type": "authorization_code"
}

Example Response Body

{
  "shop": "agitated-darwin.myshopify.com",
  "platform": "shopify",
  "access_token": "yPdckrPdqOHkyBkx0spIgNhXLi5jI8uXaNxXvJqOJ7g0N2ljAvJqBGpgEsclsfkt",
  "scope": "add_tags provide_discounts",
  "token_type": "bearer"
}

If the shop owner accepts the scopes requested by the plugin, they will be redirected to this endpoint.

Cashier adds a query string to the request:

• platform: the eCommerce platform which the shop belongs to
• shop: the platform-unique identifier for the shop
• code: a temporary authorization code

The plugin can call Cashier's API to exchange the authorization code for an access token:

POST https://cashier.boldcommerce.com/api/v1/{platform}/{shop}/oauth/access_token

with the following request body:

• client_id: the plugin's unique client identifier issued by Cashier
• client_secret: the plugin's secret key issued by Cashier
• code: the provided authorization code
• grant_type: the exact string "authorization_code"

If the authorization code is valid, Cashier will respond with the following key-value pairs:

• shop
• platform
• access_token
• scope
• token_type

Install Redirect URL

This is where Cashier will redirect the shop owner's browser when they choose to install the plugin.

Cashier adds a query string to the request:

• platform: the eCommerce platform which the shop belongs to (e.g. Shopify)
• shop: the platform-unique identifier for the shop (e.g. your-store.myshopify.com)

This endpoint is responsible for redirecting the shop owner back to Cashier with the plugin's desired API scopes:

https://cashier.boldcommerce.com/api/v1/{platform}/{shop}/oauth/authorize?client_id={client_id}&scope={scope}&response_type=code

where:

• {platform} and {shop} are replaced by their corresponding values from the initial request
• {client_id} is replaced by the plugin's unique client identifier issued by Cashier (The application UUID)
• {scope} is replaced by a space-delimited list of desired API scopes (e.g. add_payments amend_orders)

Webhook Subscriptions

Plugins can subscribe to webhooks to receive new data automatically when specific events occur within Cashier.

There are two types of requests Cashier will send:

• init is sent when a shop owner installs the plugin within Cashier
• stream is sent when data pertaining to the topic changes

The following subscription topics are available:

• Order
• OrderPartialFulfillment
• PaymentGateway

Order

{
  "data": {
    "cart_params": [],
    "currency": "CAD",
    "customer": {
      "billing_address": {
        "address1": "50 Fultz Blvd",
        "address2": "",
        "city": "Winnipeg",
        "company": "",
        "country": "Canada",
        "country_code": "CA",
        "first_name": "Test",
        "last_name": "Customer",
        "phone": "",
        "province": "Manitoba",
        "province_code": "MB",
        "zip": "R3Y0L6"
      },
      "core_info": {
        "email": "example@example.com",
        "first_name": "Test",
        "id": 123456789,
        "last_name": "Customer"
      },
      "fees": [
        {
          "id": "gift-wrap-1",
          "value": 150,
          "lineText": "Gift wrapping",
          "tag": "Fee",
          "taxable": false
        }
      ],
      "id": 1,
      "platform_customer_id": 123456789,
      "public_customer_id": "kYfE7pu5YMO5uZDe5tUtYHhsmrGczQdO4JoIkBhNkDmdsaQN1oy50QFJs8kczLkO",
      "shipping_address": {
        "address1": "50 Fultz Blvd",
        "address2": "",
        "city": "Winnipeg",
        "company": "",
        "country": "Canada",
        "country_code": "CA",
        "first_name": "Test",
        "last_name": "Customer",
        "phone": "",
        "province": "Manitoba",
        "province_code": "MB",
        "zip": "R3Y0L6"
      }
    },
    "discounts": [],
    "exchange_rate": "1.000000000000",
    "fulfillment_status": "unfulfilled",
    "id": 154,
    "includes_tax": 0,
    "line_items": [
      {
        "available_quantity": 0,
        "description": "",
        "id": 155,
        "image": "https://cdn.shopify.com/s/files/1/0039/9818/7631/products/bold-blue_small.png?v=1536159288",
        "includes_tax": 0,
        "inventory_policy": null,
        "line_item_id": 1501403316335,
        "line_item_key": "13332793229423:624aaea9ee36ab34a6611f09526b59a2",
        "note": "",
        "platform_product_id": 1495124050031,
        "platform_variant": {
          "barcode": "",
          "compare_at_price": 25.0,
          "created_at": "2018-09-05 10:52:55",
          "fulfillment_service": "manual",
          "grams": 0,
          "id": 13332793229423,
          "image_id": 4134691799151,
          "inventory_item_id": 0,
          "inventory_management": null,
          "inventory_policy": "deny",
          "inventory_quantity": -6,
          "old_inventory_quantity": -6,
          "option1": "Blue",
          "option2": null,
          "option3": null,
          "position": 1,
          "price": 25.0,
          "product": {
            "created_at": "2018-09-05 10:52:55",
            "featured_image_id": 4134691799151,
            "handle": "green-item",
            "id": 1495124050031,
            "myshopify_domain": "example.myshopify.com",
            "product_type": "",
            "published_scope": "web",
            "tags": "test",
            "template_suffix": null,
            "title": "Blue Item",
            "updated_at": "2018-09-05 11:35:00",
            "vendor": "bold-example"
          },
          "product_id": 1495124050031,
          "requires_shipping": 1,
          "sku": "",
          "taxable": 1,
          "title": "Blue",
          "updated_at": "2018-09-25 16:54:35"
        },
        "platform_variant_id": 13332793229423,
        "price": 2500,
        "product_title": "Blue Item",
        "properties": [],
        "quantity": 1,
        "sku": "",
        "title": "Blue Item - Blue",
        "total_price": 2500,
        "updated_quantity": 0,
        "variant_title": "Blue",
        "visible": 1,
        "weight": 0
      }
    ],
    "note": "",
    "note_attributes": [],
    "order_source": "cashier",
    "order_source_name": "cashier",
    "payments": [
      {
        "brand": "visa",
        "currency": "CAD",
        "driver": "Test Gateway",
        "id": "63",
        "lineText": "1111",
        "public_payment_method_id": "ggeYjOsMH4CerCuQ26RKoG5vTYRNjAZA18SADd7tlnVpy6Jep1IBl2B1MXNI1g5J",
        "status": "preAuthed",
        "tag": "Credit",
        "uuid": null,
        "value": 2500
      }
    ],
    "platform_details": {
      "order_created_at": "2018-09-25T12:54:33-04:00",
      "order_name": "#1009",
      "order_token": "1a2e32b960eb64ac5fe80322212bbc00"
    },
    "platform_friendly_identifier": "1009",
    "platform_order_id": "626935169135",
    "public_order_id": "yrRnHivogUOg4KYzSEVX18UQFHW02vCbYPIaLN5UllZP3Il5e9Kd9DB4ueCI1G86",
    "removed_line_items": [],
    "shipping_is_taxed": 0,
    "shipping_lines": [
      {
        "code": "rate",
        "delivery_date": "",
        "delivery_days": "",
        "delivery_range": "",
        "id": "",
        "lineText": "rate",
        "name": "rate",
        "price": 100,
        "source": "",
        "tag": "Shipping",
        "value": 100
      }
    ],
    "subtotal": 2500,
    "tags": [],
    "tax_lines": [
      {
        "amount": 200,
        "name": "GST",
        "rate": 0.05
      },
      {
        "amount": 125,
        "name": "PST",
        "rate": "0.08000"
      }
    ],
    "total": 2925
  },
  "subscription": "Order",
  "type": "process"
}

The init request is empty.

The stream request can be sent on four separate occasions: when a new order is successfully processed, when it is pushed to the platform, when an order fails, or when an order is fulfilled. A more detailed look at the order lifecycle can be found here. Note that Checkout expects either a 200 (OK) or 202 (Accepted) response; any other response will be regarded as a failure and will result in the webhook being re-sent.

Processed Webhook

When the order is processed and validated, we will fire off an order processed webhook within 5 minutes with the following information. This webhook occurs before the order created webhook.

Created Webhook

When the order is completed, we will fire off an order created webhook within 5 minutes with the same information as the order processed webhook the only difference will be that the type is set to create.

Fulfilled Webhook

When the order is fulfilled, we will fire off an order fulfilled webhook within 5 minutes with the same information as the order processed webhook the only difference will be that the type is set to fulfill.

Failed Webhook

When an order fails, we will fire off an order failed webhook within 5 minutes with the same information as the order processed webhook the only difference will be that the type is set to fail.

OrderPartialFulfillment

{
  "data": {
    "public_order_id": "rB1GgSBkvGZaxlUoEqsS0nPw8rcNzZjpVH9phOoOLSkQtD7lzRgIopoaGO3rKr6J",
    "platform_order_id": 1384591687722,
    "total_value": 24000,
    "total_shipping_value": 1000,
    "shipping_subtotal": 750,
    "shipping_tax": 250,
    "fulfilled_at": "2019-09-12 21:43:30",
    "item_count": 1,
    "total_discount": 0,
    "total_fees": 0,
    "total_tax": 0,
    "fulfilled_items": [
      {
        "id": 2869,
        "sku": "",
        "variant_id": 9153875214378,
        "platform_order_line_item_id": 2975582322730,
        "value": 23000,
        "quantity": 1,
        "total_value": 23000,
        "total_discount": 0,
        "discounts": [],
        "total_tax": 0,
        "taxes": [],
        "total_fee": 0,
        "fees": []
      }
    ],
    "tracking_company": "Shipment Tracking R Us",
    "tracking_number": "AB123",
    "tracking_url": "https://www.testcompany.com/trackinginfo/trackingnumber",
    "location_id": 12345
  }
}

The stream request is sent every time a merchant partially fulfills or fully fulfills an order.

PaymentGateway

{
  "data": {
    "currency": "CAD",
    "is_dev": 1,
    "name": "Test Gateway!",
    "public_id": "BVFQOAst2IKEMfJEUcyVoqBbCw2nqgibu9GcQWcm451KLo8SiAvoOyTKubvoqi9t",
    "restrict_conversion": false,
    "source_type": "cc"
  },
  "subscription": "PaymentGateway",
  "type": "delete"
}

The init request sends a list of all current connected payment gateways in Cashier.

The stream request is sent every time a merchant creates, updates, or deletes a payment gateway in Cashier.

ShopContactInfo

{
  "data": {
    "contact_info": {
      "domain": "www.merchantstore.myshopify.com",
      "email": "merchant-notification-email@email.com"
    }
  },
  "subscription": "ShopContactInfo",
  "type": "update"
}

This subscription requires the read_shop_contact_info scope.

The stream request is sent every time a merchant updates their shop contact info in Shopify.

Widgets

Embedded Widgets

Pages embedded into the checkout (via Iframe Widgets or Modal Widgets) can communicate with Cashier using postMessage.

Example Widget

Example Embedded Page:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <script>
      // Start listening for messages from Cashier:
      window.addEventListener("message", function (event) {
        let message = event.data;
        switch (message.type) {
          case "checkout/receive_order":
            console.log("Received order data", message.payload);
            break;
        }
      });

      // Set the height of the iframe containing this embedded page:
      parent.postMessage(
        {
          type: "checkout/resize_frame",
          payload: { height: 100 },
        },
        "*"
      );

      // Request order data from Cashier:
      parent.postMessage(
        {
          type: "checkout/request_order",
        },
        "*"
      );
    </script>
  </head>
  <body>
    <h1>Hello, Cashier!</h1>
  </body>
</html>

Here is an example implementation of a widget (see right)

1. First, the widget starts listening for message events in order to receive the checkout/receive_order message later.
2. It sends checkout/resize_frame to resize its container to 100px in height. This makes the widget visible in the checkout. Widgets are hidden until they resize themselves for the first time.
3. It sends checkout/request_order to request the current order data from Cashier.
4. Cashier responds to the widget by sending checkout/receive_order with the current order data.
5. The message event listener is called, which logs the order data to the browser console.

Positions

Position	Description
above_header	Appears at the very top of the page, above the header section.
below_actions	Appears near the bottom of the page, below the "action" buttons (Complete order, Continue to Shipping Method, etc).
billing	Appears in the billing address section, at the end under the phone number input.
billing_address_after	Appears after the billing address section.
customer_info	Appears near the customer email input.
discount	Appears below the discount code input.
discount_top	Appears above the discount code input.
header	Appears below the store logo in the main header.
line_items	Appears below the line items.
logo	Appears above the store logo inside the main header.
main_content_beginning	Appears at the top of the .Main__Content element.
main_content_end	Appears at the bottom of the .Main__Content element.
payment_gateway_top	Appears between the heading and the credit card sections.
payment_gateway	Appears near the payment methods.
payment_method_top	Appears above the payment methods.
payments	Appears below the payments section within the order summary.
payments_top	Appears above the payments section within the order summary.
price_summary	Appears below the price summary (Subtotal) section within the order summary.
price_summary_top	Appears above the price summary (Subtotal) section within the order summary.
shipping_address_before	Appears right before the shipping address section.
shipping	Appears in the shipping address section, at the end under the phone number input.
shipping_lines	Appears near the shipping methods.
summary_above_header	Appears above the order summary section.
summary_top	Appears at the top of the order summary section, below the Summary header.
thank_you	Appears on the order confirmation page.
total	Appears below the total section within the order summary.
total_top	Appears above the total section within the order summary.

Receiving Messages

window.addEventListener("message", function (event) {
  let message = event.data;
  switch (message.type) {
    case "checkout/receive_order":
      console.log("Received order data", message.payload);
      break;
  }
});

Message Type	Description
checkout/receive_order	This is Cashier's response to checkout/request_order.

Sending Messages

parent.postMessage(
  {
    type: "checkout/app_hook",
    payload: {
      hook: "example_hook",
      data: { foo: "bar" },
    },
  },
  "*"
);

parent.postMessage(
  {
    type: "checkout/resize_frame",
    payload: { height: 100 },
  },
  "*"
);

parent.postMessage(
  {
    type: "checkout/close_frame",
  },
  "*"
);

parent.postMessage(
  {
    type: "checkout/request_order",
  },
  "*"
);

parent.postMessage(
  {
    type: "checkout/process_order",
  },
  "*"
);

parent.postMessage(
  {
    type: "checkout/modal_open",
    payload: {
      uuid: "123-abc",
      click_url: "https://example.com/widget",
      frame_origin: "https://example.com",
    },
  },
  "*"
);

Message Type	Description
checkout/app_hook	Send an app_hook event to the plugin which created the widget.
checkout/resize_frame	Resize the iframe containing the widget.
checkout/close_frame	Remove the iframe containing the widget.
checkout/request_order	Request the current order state from Cashier. Cashier will respond with a checkout/receive_order message.
checkout/process_order	Triggers order processing.
checkout/modal_open	Opens the iframe as a modal window

Types

App Hook Widget

Example APP_UPDATE_WIDGET action for an 'app_hook' widget

{
  "type": "APP_UPDATE_WIDGET",
  "data": {
    "name": "example_widget",
    "type": "app_hook",
    "position": "line_items",
    "text": "Click here to send an 'example_hook' to the plugin",
    "icon": "https://example.myshopify.com/icon.png",
    "click_hook": "example_hook"
  }
}

This type of widget will send an app_hook event to your plugin when the customer clicks on it.

Key	Type	Description
name	string	Unique identifier for this widget.
type	string	Must be the exact value app_hook.
position	string	Must be one of the valid positions.
text	string	Visible text within the widget.
icon	url	(Optional) Image URL to display within the widget.
click_hook	string	Custom value that Cashier will send to your plugin in the app_hook event.

External Link Widget

Example APP_UPDATE_WIDGET action for an 'external_link' widget

{
  "type": "APP_UPDATE_WIDGET",
  "data": {
    "name": "example_widget",
    "type": "external_link",
    "position": "line_items",
    "text": "Click here to read our return policy",
    "icon": "https://example.myshopify.com/icon.png",
    "link_url": "https://example.myshopify.com/returns"
  }
}

This type of widget will open a new tab/window when the customer clicks on it.

Key	Type	Description
name	string	Unique identifier for this widget.
type	string	Must be the exact value external_link.
position	string	Must be one of the valid positions.
text	string	Visible text within the widget.
icon	url	(Optional) Image URL to display within the widget.
link_url	url	URL of the page to open as a new tab/window.

Iframe Widget

Example APP_UPDATE_WIDGET action for an 'iframe' widget

{
  "type": "APP_UPDATE_WIDGET",
  "data": {
    "name": "example_widget",
    "type": "iframe",
    "position": "payments",
    "source": "https://example.com/example_widget",
    "frame_origin": "https://example.com"
  }
}

This type of widget embeds a page from your application directly within the checkout page.

Key	Type	Description
name	string	Unique identifier for this widget.
type	string	Must be the exact value iframe.
position	string	Must be one of the valid positions.
source	url	URL of the page to embed inside the widget.
frame_origin	origin	The embedded page must match this origin in order to communicate with Cashier via postMessage.

Modal Widget

Example APP_UPDATE_WIDGET action for a 'modal' widget

{
  "type": "APP_UPDATE_WIDGET",
  "data": {
    "name": "example_widget",
    "type": "modal",
    "position": "payments",
    "text": "Click here to open a dialog with content in it",
    "icon": "https://example.myshopify.com/icon.png",
    "click_url": "https://example.com/example_content",
    "frame_origin": "https://example.com"
  }
}

When the customer clicks this type of widget, Cashier will open a dialog and embed a page from your application within it.

Key	Type	Description
name	string	Unique identifier for this widget.
type	string	Must be the exact value modal.
position	string	Must be one of the valid positions.
text	string	Visible text within the widget.
icon	url	(Optional) Image URL to display within the widget.
click_url	url	URL of the page to embed inside the dialog.
frame_origin	origin	The embedded page must match this origin in order to communicate with Cashier via postMessage.

NOTE: The frame_origin must not be a path, it has to be a base domain. For example https://www.google.ca is a valid origin, whereas https://www.google.ca/other/path is not