Commissioning

Commissioning

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

Prerequisites

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

Example

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:
    • 10% on toys
    • 5% on baby
    • 2% on everything else
  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 baby, you would take 5% and multiple by 90% to arrive at 4.5%. Then, apply the floor function to arrive at 4% (e.g. FLOOR(5% * 90%) = 4%). In this example, the user's commission rates would be:

    • 9% on toys
    • 4% on baby
    • 1% on everything else
  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 baby, $100 on everything else.

    • Based on the commission rates from step 1, you would receive the following from Button:
      • $10 + $5 + $2 = $17
    • Once you apply the commissioning logic from step 2, notify the user of their pending reward, which is:
      • $9 + $4 + $1 = $14
    • Thus, your profit for this transaction will be:
      • $17 - $14 = $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.