Custom Checkout Integration
Step-by-step details for setting up a custom checkout provider for Mason apps
Merchants can integrate a custom checkout provider for accelerated checkouts. This is powered with the support of draft orders and redirecting users to the checkout provider, post-creation of this draft order. The custom checkout flow should support standard functionalities that are part of the default platform checkout flows e.g. Shopify checkout.
Pre-requisites for Integration
The custom checkout provider should support the following:
Custom Discounts
- Ability to pass custom discount to be applied on each item
Revenue Attribution
- Ability to specify attribution details in properties & tags of the default order
- Properties can be excluded from checkout UI (it's meant for internal bookkeeping)
- Tags should be displayed
Flow for custom checkouts
Flow Diagram

Flow Description
- The user clicks on the Mason playbook to checkout curated products with custom discounts
- Mason's UI library makes a backend call to create a discounted cart-like structure
- Mason's backend returns the discounted cart to the UI
- Mason's UI library triggers a post message ( window.postMessage ) on the browser to the Custom Checkout UI library as per the
contract mentioned below - Custom Checkout UI library will process the discounted cart
- Custom checkout will open a modal from where the user will go through the checkout
POST Message Contract
{
"api_key": <> # To uniquely identify the Shopify store in their system
"items": [
{
"id": "43497948545272", # variant id
"quantity": 2,
"properties": [ # For attribution. Same as required by Shopify
{
"name": "<key1>",
"value": "<val1>"
}],
"line_price": {
"sub_total": "699.00",
"discounts": [{
"code": "Discount title", # code for display
"amount": "75.00" # pass per quantity value here
},
{
"code": "discount2",
"amount": "25.00"
}]
}
}
]
"discounts": [
{
"type": "CUSTOM_DISCOUNT",
"code": "Discount title",
"amount": "150.00"
}
],
"tags": ["by mason", "Diwali Special"],
"sig": <>
}
Fields Details
- API Key - To uniquely identify the Shopify store in their system
- Items - containing details of the product & variant being bought & quantity
- Discount - which needs to be applied to items
- Properties - in each item containing the attribution information
- Tags - to be shown with the order in the Shopify dashboard
- Sig - This is the signature created using the payload below ( without the sig field ) and the common key shared between Mason & Checkout provider. To ensure data is not tempered, this key can be used by the checkout provider to validate the payload
Mason Playbook Sample
Updated about 1 month ago