NAV Navbar

Cashier Documentation

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

Example Successful Response

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

Requires modify_cart scope, also requires a plugin application.

This endpoint is currently only supported for the general platform. The return 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": "CAD"
            }
        ]
    }
}

Example Successful Response

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

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 return 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

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.

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-31 00:00:00.000000",
        "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.
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}/{signedJWTHere}/customer-info?uuid={App_UUID}&platform_type={platform_type} 

Example Iframe Source:

https://cashier.boldcommerce.com/bobs-store.bigcommerce.com/bigcommerce/{signedJWTHere}/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 the iframe with the ability to edit a customers credit cards for your shop

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.

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.

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:

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

Charge Order

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

Example Create Simple Charge:

{
  "idempotency_key": "AAAA2222CCCC4444"
}

Create a charge for an existing order.

Requires create_orders scope.

Request Parameters
Key Type Description
idempotency_key string An idempotency key to ensure Cashier does not double charge, max 32 characters.

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
      },
      "1": {
        "platform_variant_id": 20129965703268
      }
    }
  },
  "customer_id": 1,
  "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)
customer object (optional)
customer_id integer (optional - either customer_id or public_payment_method_id must be set)
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 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)


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
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:

{
  "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
      },
      "1": {
        "platform_variant_id": 20129965703268
      }
    }
  },
  "customer_id": 1,
  "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"
}

Requires read_orders scope.

Response 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)
customer object (optional)
customer_id integer (optional - either customer_id or public_payment_method_id must be set)
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)
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 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)


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)

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 authorize, 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 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",
            "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",
            "token": "ABCDEF777"
        }
    ]
}

Example Response

{
    "success": true,
    "import_result": {
        "customers": [
            {
                "email": "customers@example.com",
                "token": "ABCDEF777",
                "public_id": "12FF89",
                "card_id": "PUBLIC_CARD_ID"
            },
            {
                "email": "seconds@example.com",
                "token": "AHD8982",
                "public_id": "12FF890",
                "card_id": "PUBLIC_CARD_ID_2"
            }
        ],
        "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[].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 we’re able to successfully store, as well as a list of any failed imports.

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"
        },
        "1": {
            "public_id": "123AABBCC",
            "name": "Test USD",
            "is_dev": false,
            "currency": "USD",
            "source_type": "paypal"
        }
    }
}

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 array 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.

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.

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
}
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 any Amount

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

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.00
}

Example Create Refund for $200.00:

{
    "success": true,
    "amount_refunded": 200.00
}
Route Parameters
Key Description Example
order_id The Bold public_order_id identifier for the order. jhdhVh3OdvFNG...
Body Parameters
Key Type Description
amount int 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 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
}
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[].quantity int The quantity of line items to refund.
line_items[].restock_quantity int The quantity of line items to restock inventory for.

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

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.

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

Example Response

{
    "tax_rates": {
        "cart_taxes": [
            {
                "value": 0.04,
                "tax_name": "Tax-1"
            },
            {
                "value": 0.09,
                "tax_name": "Tax-2"
            }
        ],
        "shipping_taxes": [
            {
                "value": 0.04,
                "tax_name": "Tax-1"
            },
            {
                "value": 0.09,
                "tax_name": "Tax-2"
            }
        ],
        "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"
  },
  "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
}

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 and pre-tax 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 and post-shipping) in cents.

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.

  3. The customer is redirected to Cashier so that we can handle the checkout.

  4. 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.

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

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

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

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

  9. If an order fails, Cashier sends a webhook to you with the failed order details.

Processed Webhook

{
    "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"
        },
        "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.00,
            "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.00,
            "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, // $25.00
          "product_title": "Blue Item",
          "properties": [],
          "quantity": 1,
          "sku": "",
          "title": "Blue Item - Blue",
          "total_price": 2500, // $25.00
          "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 // $25.00
        }
      ],
      "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, // $1.00
          "source": "",
          "tag": "Shipping",
          "value": 100 // $1.00
        }
      ],
      "subtotal": 2500, // $25.00
      "tags": [],
      "tax_lines": [
        {
          "amount": 200, // $2.00
          "name": "GST",
          "rate": 0.05
        },
        {
          "amount": 125, // $1.25
          "name": "PST",
          "rate": "0.08000"
        }
      ],
      "total": 2925 // $29.25
    },
    "subscription": "Order",
    "type": "process"
}

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 following information as the order processed webhook; the only difference will be that the type is set to create.

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.

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.

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:

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"
                },
                "authorized": true,
                "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.
authorized boolean Must be set to true.
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.

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

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.
value numeric If fee_type is percentage, this is the percentage
If fee_type is fixed, this is the fixed amount.
taxable boolean Whether Cashier should charge sales tax for this fee.

ADD_FUTURE_PAYMENT

This action allows plugins to add a future payment to the order.

The outstanding balance of the order will be reduced by the future payment value.

Cashier will not charge the customer for this payment. The plugin is responsible for collecting this payment.

Requires add_payments scope.

Key Type Description
id string A unique identifier for the payment.
line_text string A short description (e.g., “First installment”).
value currency The amount to reduce the outstanding balance, specified in the same currency as the order.

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

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 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.

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

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.

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

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

Requires add_tags scope.

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_STATE

This action allows plugins to pass state to their checkout widgets.

APP_UPDATE_WIDGET

This action allows plugins to initialize and modify checkout widgets.

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.

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
different_billing_address boolean Whether to select “Use a different billing address” on the checkout page

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.

DISCOUNT_CART

{
    "success": true,
    "actions": [
        {
            "type": "DISCOUNT_CART",
            "data": {
                "discountPercentage": 5,
                "transformationMessage": "Money Saved"
            }
        }
    ]
}

The full discount value will be applied to the entire cart.

Requires modify_cart scope.

Key Type Description
discountPercentage integer Percentage to discount the cart by.
transformationMessage string Description of the discount for the order summary.

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.

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_SHIPPING

Requires provide_shipping_rates scope.

See Overrides.

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

OVERRIDE_INVENTORY

Requires provide_shipping_rates scope.

See Overrides.

Key Type Description
url url URL endpoint for Inventory 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

Allows a plugin to remove all payments previously created with the ADD_PAYMENT, ADD_AUTHORIZED_PAYMENT or ADD_FUTURE_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_FEE

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 credit card option in the payments section of checkout.

Requires require_stored_payment_method scope.

SET_LINE_ITEM_PRICE

{
    "success": true,
    "actions": [
        {
          "type": "SET_LINE_ITEM_PRICE",
          "data": {
              "line_item_key": "AABBCC123",
              "price": 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.
price integer The new price of the line item in cents (e.g. 150 = $1.50).

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_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.

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",
    "order_total": 2468
  },
  "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 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.
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.
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.
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_address Occurs every time Cashier starts validating the shipping or billing address.
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.

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 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:

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

The 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 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 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.50
        }
    ]
}
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 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:

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:

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

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:

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:

Subscriptions

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

There are two types of requests Cashier will send:

The following subscription topics are available:

Order

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 Shopify, when an order fails, or when an order is fulfilled.

OrderPartialFulfillment

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

PaymentGateway

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.

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
billing Appears in the billing address section, at the end under the phone number input.
billing_address_after Appears after the billing address section.
main_content_beginning Appears at the top of the .Main__Content element.
main_content_end Appears at the bottom of the .Main__Content element.
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 near the store logo.
line_items Appears below the line items.
payment_gateway Appears near the payment methods.
payments Appears above 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 below 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.
total Appears below the total section within the order summary.
total_top Appears above the total section within the order summary.
thank_you Appears on the order confirmation page.

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'
}, '*');
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.

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.

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.

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