Use Button for Loyalty and Rewards on
All Platforms

Use Button for Loyalty and Rewards

Button can help you power real-time loyalty & rewards platforms across the app ecosystem, enabling you to notify and reward your members for purchases made on their mobile devices.



Note: Want to work with companies not supported today? Just let us know and we'll work with them to make it happen!

In this guide, we will go over:

What might I want to use Button to do?

Button can support a wide range of loyalty & rewards use-cases, but here are a few we've seen:

  • Rewarding users for purchases made in apps or mobile web.
  • ⁣⁣Giving users points, digital items or currency for purchases.
  • ⁣Providing offers or deals from partners with closed-loop tracking.
  • Increase your mobile revenue by converting taps to transactions - we’ve found this can be an increase of >400%.

How does a Loyalty or Rewards Integration with Button work?

There are two components to a Loyalty or Rewards integration with Button:

  1. Choose the method to show your users products or services through Button (either partners, or items from partners). There are a few options:

    • Button Tracking
    • App-to-App Support
    • Embedded Web checkout
    • A simple link to a Merchant
  1. Receive webhooks when users install or checkout in partner apps, and crediting your users as necessary.

What would that look like in a diagram?

It would look like this...


Set up loyalty with Button in 5 steps

1. Configure the SDK and set up user-level IDs

The first thing you'll need to do is add the Button SDK to your app, initialize it, and identify your users with your unique User ID. The reason you'll want to pass your user identifier is that when we notify you of transactions you drove (via webhooks or our Transactions API), we'll include the user identifier so that you can reward them accordingly.

2. Create a Button Purchase Path

You can fetch an action from Button by passing a Merchant URL to Button's SDK, which Button will then enhance with a mix of tracking, native technology, and a highly optimized user experience. This simple approach allows you to add Button to virtually any purchasable item that is accessible through a URL. The SDK is smart enough to determine if Button supports commissioning a particular URL, so all you have to do is pass it to the SDK and Button will take care of the rest. For more information on Button Purchase Path, check out this guide.

3. Send users to the partner app to purchase

If Button can exchange the the given URL for a fully attributed action, the fetch will complete with a Purchase Path. Starting a purchasePath will pass control to the Button SDK which will open the Merchant app, install flow, or web checkout.

Note: If the user doesn't already have the Merchant app installed, they can choose to seamlessly install it using our proprietary Attended Install functionality. You'll receive a webhook on app download completion to inform you of any commission earned.



4. Configure Webhooks on Commissionable Events

In order to receive notifications when your users install or checkout in Button Marketplace apps, you need to configure a webhook endpoint. Webhooks send you a notification by POSTing to an API endpoint you declare with the details of the user and transaction.

You can configure webhooks in the Dashboard Webhooks tab.

Pending, Validated, and Declined States

Your webhook will be sent Transaction: Pending, Transaction: Validated, and Transaction: Declined events from Button. These represent pending, validated, and declined transactions respectively.

Until a transaction is marked as validated, it can be changed and should not be redeemable / cash-out-able to a user. Pending transactions can be shown to users in a pending state (e.g. Balance vs. Available Balance.)

5. Give users their rewards from webhooks!

Note: You should only reward users on purchase events, so make sure you check the category field and filter out app install webhooks.

When you receive a webhook POST, you know that one of your users did something that you may want to reward them for!

The webhook payload will contain a few fields that are particularly useful:

  • publisher_customer_id: The User ID (your ID) for the user that transacted
  • category: The Category of transaction (Order vs Install)
  • order_total: For orders, this is the total amount of the order
  • status: The status of the transaction
  • commerce_organization: The ID of the Merchant app that the purchase took place in
  • order_line_items[].publisher_commission: Each line item contains the exact commission granted to the Publisher for the line item

Full webhook documentation

In this case, if you wanted to give a user 100 points for purchasing in App A, we would perform logic like the following:

// Get the user that made the transaction
User affectedUser = User.userByID(webhook.publisher_customer_id);

if (webhook.commerce_organization == TARGET_COMMERCE_APP_ID) {
    if (webhook.status == "validated") {
        affectedUser.addPoints(100, "Purchasing in App X");
    }
    else if (webhook.status == "pending") {
        // Optionally tell them something here
    }
}

Alternatively, you can use the publisher commission field to calculate rebates based on the specific commission generated by each item in the order. If publisher commission == 0, this item was likely subject to a Merchant exclusion.

// assume `webhook` is a parsed Button webhook
const USER_COMMISSION_PERCENTAGE = .8;
const PUBLISHER_COMMISSION_EPOCH = new Date('2018-07-18T23:00:00Z'); // see webhook field documentation

const user = User.userByID(webhook.publisher_customer_id);
const createdDate = new Date(webhook.created_date);

if (createdDate < PUBLISHER_COMMISSION_EPOCH) {
  // Use your original commissioning logic
} else {
  for (const lineItem of webhook.order_line_items) {
    const publisherCommission = lineItem.publisher_commission;
    if (publisherCommission === 0) {
      continue;
    }

    // apply a commission to the user with your chosen method
    lineItemTotal = lineItem.amount * lineItem.quantity;
    user.addPoints(lineItemTotal * USER_COMMISSION_PERCENTAGE);
  }
}
# assume `webhook` is a parsed Button webhook
require 'date'

PUBLISHER_COMMISSION_EPOCH = "2018-07-18T23:00:00Z" # see webhook field documentation
USER_COMMISSION_PERCENTAGE = 0.8

user = User.user_by_id(webhook["publisher_customer_id"])
created_date = DateTime.iso8601(webhook["created_date"])

if (created_date < DateTime.iso8601(PUBLISHER_COMMISSION_EPOCH))
  # Use your original commissioning logic
else
  webhook["order_line_items"].each { |line_item|
    publisher_commission = line_item["publisher_commission"]
    if (publisher_commission == 0)
      next
    end

    # apply a commission to the user with your chosen method
    line_item_total = line_item["amount"] * line_item["quantity"]
    user.add_points(line_item_total * USER_COMMISSION_PERCENTAGE)
  }
end
# assume `webhook` is a parsed Button webhook
import datetime

PUBLISHER_COMMISSION_EPOCH = '2018-07-18T23:00:00Z' # see webhook field documentation
USER_COMMISSION_PERCENTAGE = .8
ISO_8601_FORMAT_STRING = "%Y-%m-%dT%H:%M:%SZ"

user = User.user_by_id(webhook['publisher_customer_id'])

created_date = datetime.datetime.strptime(webhook['created_date'], ISO_8601_FORMAT_STRING)
epoch_date = datetime.datetime.strptime(PUBLISHER_COMMISSION_EPOCH, ISO_8601_FORMAT_STRING)

if created_date < epoch_date:
  # Use your original commission logic
  pass
else:
  for line_item in webhook['order_line_items']:
    publisher_commission = line_item['publisher_commission']
    if publisher_commission == 0:
      # line item was not commissionable
      continue

    # apply a commission to the user with your chosen method
    line_item_total = line_item['amount'] * line_item['quantity']
    user.add_points(line_item_total * USER_COMMISSION_PERCENTAGE)

Testing your integration

Now it's time to test that everything is working correctly.

  • Display a Button in your app
  • Tap it and go through to the Merchant app
  • Make a purchase
  • Your webhook will fire
  • Confirm that the webhook fires with the correct amount & userID.

Note: You can also use the Button Partner Test App to test out your integration, but it does not currently support userID so all webhooks will fire without a user ID.

Questions?

Have other use-cases in mind, or see something that doesn't make sense? Contact us and we'll get in touch!

What's Next

Now that you know Button for Loyalty and Rewards, see more on how to integrate:


Configure Webhooks

Button allows you to configure webhooks so you can get real-time updates to your system when users push Buttons in your app. To do so, you will need to configure the destination of the webhook and what events you want to receive. Then, Button will send you an HTTP request when any of those events are created.

View Guide