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: Post your order to your API

Here you should follow your normal flow to capture orders to your own API. The only change here is to keep the btn_ref near your order so you can later call Button with the order and the attribution data.

Note: You should report all orders regardless of the presence of a Button attribution token to allow seamless customer support and investigation with Loyalty & Rewards publishers.

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.

curl https://api.usebutton.com/v1/order \
   -X POST
   -u your_api_key: \
   -d total=12340 \
   -d currency=USD \
   -d order_id=my_order_id \
   -d btn_ref=ooQuaF0faehohree0ohyee6N

Note: This is a simple example that does not include line item breakout, UPCs etc... See the API Reference for full details. Also, the total must be an integer (e.g. $123.40 is 12340) and not include shipping and handling, tax, promotions, or credits (i.e. total should be the actual value of the product or service before any adjustments).

Interactive Guide

We've put together an interactive tool that lets you make the full lifecycle of Order requests against our API and get real-time feedback and validation that we're handling everything properly.

Sign Up for an account in our dashboard and checkout the Interactive Guide to get up and running.

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.

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