Migrating to API Order Reporting

How and why to update your Button integration to use our order reporting API.

Looking for the full Order API documentation? Use the API Reference.

Overview

We’re making some changes to the ways that your orders are reported in our system, and we wanted to discuss moving your integration from SDK reporting to API reporting in the near term.

We have deprecated order reporting via the SDK in favor of reporting orders directly using our API from your API calls. We aim to migrate all partners to this new way of reporting over the next month or so. This update will provide you with a range of benefits including:

Performing the Migration

Migrating to the Order Reporting API is simple and will be a one-time effort that gives you ongoing reliable reporting for order attribution & affiliation.

Step 1

Send Button Attribution Tokens to your API

Whenever your app is opened from Button, the URL will also contain a Button Attribution Token. The Button SDK will automatically extract and store this token.

When you post an order to your API, you will need to check for the existence of this token, and if present include it in the order payload, so that the API can then report it to Button.

iOS

NSString *buttonToken = [Button sharedButton].referrerToken;

Android

Button.getButton(context).getReferrerToken();

Mobile Web

bttnio('getReferrerToken')

Note: for more information about affiliation in Mobile Web, see our documentation here

Note: When choosing a name for this field in your Order API, you'll need to coordinate both client and server to expect the same name. We recommend btn_ref for clarity.

Step 2

Start reporting orders to the Button API

Each time you create an order in your API, this will be reported to Button. If there is a btn_ref present in the order from your client, then you should also include this as the btn_ref field in the order posted to Button.

Order interactions to report:

  • - Post orders immediately after payment processed
  • - Update orders when modified
  • - Delete orders when cancelled or returned
Note: Orders created with a btn_ref will be valid for affiliation, so updating and deleting orders is important for ensuring correct billing.

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.

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

Don't use one of these languages? Or want to build your own? You can find the full details of the underlying API in the API reference.


Step 3

Remove SDK Order Reporting from your app

In your next app update, remove SDK Order Reporting -- you can roll that update out on a timeline that works for you without any impact or double-counting. You will however have to use this build to perform the verification in Step 4 to ensure that you're not seeing SDK orders.


Step 4

Verify with the Button Partner Test App

The Button Partner Test App will walk you through making a purchase in your newly configured App & API, show you the data that we see and allow you to confirm that it's all working correctly.

If something's not working, the App will let you know and help to either figure it out or get in touch.

Once you roll API Order Reporting out to production, let us know and we'll start listening to your API and will ignore orders from the SDK.

DOWNLOAD THE APP

Note: You will need to install the debug version of your app for this step to ensure you are not seeing an order reported from the SDK.

API Reporting not working correctly?

A few common issues

Purchase Path

Missing Button Token

It's important that orders contain the Button Attribution token btn_ref when available - this controls attribution & affiliation.

New Install

403 Forbidden?

If you're seeing a 403 Forbidden response it's most likely that your API key encoding isn't right, take a look at the API authentication section.

Accurate Attribution

Web links not working?

Button supports linking from the web with attribution. Make sure that you've completed the Interactive App Setup guide.


Get Started

Set up your Button Links and start making every click an in-app purchase opportunity, today. Then, start seeing users and transactions immediately in your Dashboard.