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

  1. The user clicks on the Mason playbook to checkout curated products with custom discounts
  2. Mason's UI library makes a backend call to create a discounted cart-like structure
  3. Mason's backend returns the discounted cart to the UI
  4. 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
  5. Custom Checkout UI library will process the discounted cart
  6. 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", # per quantity
                "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" # all item level discount for all quantities combined            

    "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
  • Items -> line_price -> discounts - which needs to be applied to items
  • Discounts - The combined discount value applied at each item level [ Can be used to show on the Checkout Page. Else show discount at each item level above ]
  • 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