This guide walks you through how to properly commission users that have made purchases via your platform. We’ll specifically cover:

  1. Prerequisites
  2. Transaction Commissioning
  3. Setting up Commissioning Logic


  • You have created or augmented your content management system to include Button Organization IDs (e.g. org-xxx) via our Merchants API and Brand commission rates via our Rates API.
  • You are ingesting transactions from Button, either via Webhooks or from our Transactions API.

Transaction Commissioning

Commissioning in a loyalty setting typically comes in the form of a Publisher offering an incentive to a user for shopping at a Brand. This incentive can be cash-back, or another type of currency (e.g. points, miles).

In order for the value proposition to resonate with both you and the user, the commission earned for making a purchase is split between both parties.

Setting up Commissioning Logic

Below is an example of how to set up commissioning logic where you pay your users a flat percentage of the commission you receive. Here are the steps to do this:

  1. Parse the commerce_organization from the transaction and look up the corresponding User Payout % from your CMS.
  2. Multiply the User Payout % by the amount. This will give you the commission that the user has earned, and you can now give the user that amount in the form of a pending reward.
  3. When you receive another webhook - or pull via our Transactions API - that contains the same transaction ID (button_order_id) but with status=validated, you can now convert the user’s commission from “pending” to “finalized”.


Here is a sample flow for Brand123 (the example Brand in the table below):

Example CMS Setup

  1. Pull the commission rate(s) for Brand123 from the Rates API. In this example, it would be:
    • 7% on Toys
    • 3% on Clothing
    • 4% on Electronics
  1. Calculate the user's commission rate for Brand123. For this example, the User Payout % is 90%. Multiply the amount (i.e. the commission amount) by the User Payout %. Then, use the floor function to round this to a whole number. For example, for Toys, you would take 7% and multiple by 90% to arrive at 6.3%. Then, apply the floor function to arrive at 6% (e.g. FLOOR(7% * 90%) = 6%). In this example, the user's commission rates would be:

    • 6% on Toys
    • 2% on Clothing
    • 3% on Electronics
  2. The user makes a purchase and you receive a webhook - or pull via the Transactions API - and the transaction is in a pending state (e.g. status=pending). For example, the user spends $300 total: $100 on Toys, $100 on Clothing, $100 on Electronics.

    • Based on the commission rates from step 1, you would receive the following from Button:
      • $7 + $3 + $4 = $14
    • Once you apply the commissioning logic from step 2, notify the user of their pending reward, which is:
      • $6 + $2 + $3 = $11
    • Thus, your profit for this transaction will be:
      • $14 - $11 = $3
  3. Once the transaction finalizes, you will receive a webhook – or pull via the Transactions API – notifying you of this update with status=validated. You can now:

    • Notify the user that their pending reward is finalized.
    • Give the user the reward.