Order Attribution

Button attribution closes the loop on incoming users from the Button marketplace. The simplest form of attribution takes just a couple minutes to put in place.

Looking for a reference of all API endpoints? Check out the attribution API reference.

This diagram illustrates how a user comes in via a deep link and the steps needed to capture an order and attribute it to the related deep link.

Step 1: Pass the deep link to the SDK

Setup the SDK to route all your deep links through it. That way it can grab the attribution data when it is passed along a deep link.

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {
  [[Button sharedButton] handleURL:url];
  return NO;
public class MyApplication extends Application {
  public void onCreate() {
      // During your first implementation, we recommend you to turn on
      // logging for more insight into the reporting.
      // The logs will be under the tag 'ButtonSDK'
      // adb logcat -s ButtonSDK
      if (BuildConfig.DEBUG) {

Step 2: Fetch the attribution data

Use the SDK to capture the attribution data. The specific field that is relevant is the btn_ref which appears as a query parameter on the deep link.

Call the specified method in the Button SDK to capture the btn_ref.

[Button sharedButton].referrerToken

You can find the full documentation for Mobile Web here

Step 3: Report the stored token with your Order

In the call to your own Checkout API, include the btn_ref value so that your API can later report that value to Button's Order API.

Note: It is important to report all orders regardless of the presence of a Button attribution token to unlock Customer Segments and to allow Button to investigate transactions for Loyalty & Rewards publishers without per-transaction effort from you!

Step 4: Report your order to Button

After you've captured the user's order in your own system, you'll need to capture the order in Button's system as well and pass along the attribution data. The details for this API can be found in the API docs. The bare minimum are the total value of the order (exclude shipping and handling, tax, promotions, credits), the currency for the item, your unique identifier for the order, the attribution data (the btn_ref), and use your API key for authentication. Go to your Button dashboard to access your API key.

Interactive Guide

We've put together an interactive tool (see GIF) that lets you make the full lifecycle of Order requests against our API and get real-time feedback and validation that everything is working correctly.

Reporting Libraries

We've made libraries for a few common languages to make it really easy to get set up. These libraries are totally open source so even if you use a different language, they are a great reference for implementation.

Full API Reference

Don't use one of these languages, want to build your own or simply want to understand how the API works? You can find the full details of the underlying API in the API reference.

Update or delete the order

To keep the order you've captured with Button the same as your system, you can update or delete the orders.

To update or delete an order make an API call with the unique order ID that you used to create the order. You only needed the btn_ref on order creation, these steps no longer require that field. If you used the Interactive Order Reporting Setup, that tool will guide you through this too.

curl https://api.usebutton.com/v1/order/my_order_id \
   -u your_api_key: \
   -d total=20000

Advanced features & integration docs

For more details, full integration guides, and code samples, check out the full docs.

API Docs