Report Orders to Button on

Report Orders to Button

All orders must be affiliated through Button so we can properly reward commissions to Publishers who have you integrated in their application.

To report orders, you have to do the following:

  1. Obtain the attribution token
  2. POST the attribution token to your Checkout API
  3. Report orders to Button's Order API

Obtain the attribution token

When a user comes into your app through deep link, a unique Attribution Token (or btn_ref) will be generated and stored by the Button SDK for their session. When the user checks out and your app reports the order to your Checkout API, you must obtain their Attribution Token via the SDK and POST this in addition to any other information you regularly would. Note: you should never store this value and should always access it from Button when it is needed.

// Obtain Attribution Token
if let btn_ref = Button.shared().referrerToken() {
    // referred token is present
}
// Obtain Attribution Token
NSString *btn_ref = [[Button sharedButton] referrerToken] ?: @"No Referrer Token";

POST the attribution token to your Checkout API

When the order is complete within your mobile app and you're ready to POST the user's order to your Checkout API for further processing, grab the Attribution Token from the SDK and POST to your Checkout API how you normally would, including the Attribution Token in the payload. Note: you should never store this value and should always access it from Button when it is needed.

// Set parameters for POST, including Attribution Token
let parameters: Parameters = [
    "btn_ref": btn_ref, // Attribution Token from previous section
    "price": 34.90,
    "location": "New York"
]

// Perform POST request
Alamofire.request("https://api.yourapi.com", method: .post, parameters: parameters, encoding: JSONEncoding(options: []))
// Set parameters for POST, including Attribution Token
NSDictionary *parameters = @[
    @"btn_ref": btn_ref, // Attribution Token from previous section
    @"price": @(34.90),
    @"location": @"New York"
]

// Perform POST request
[sessionManager POST:@"https://api.yourapi.com" parameters:parameters progress:nil success:^(NSURLSessionDataTask *task, id responseObject) {
  NSLog(@"Success");
} failure:^(NSURLSessionDataTask *task, NSError *error) {
  NSLog(@"Failure");
}];

Report orders to Button's Order API

After the Attribution Token for an order is POSTed to your Checkout API, you must send that same Attribution Token (btn_ref) to Button's Order API to complete the order with Button. This will allow Button to properly reward commissions to Publishers who have your Button in their application. To do this, you must attribute the order through an HTTP POST request with the relevant parameters. These parameters and their values will vary depending on your marketplace.

Button has made available client libraries in Node.js, Ruby, and Python for making these requests easier for you.

See our API documentation for more details on order reporting.

Create a new order

After your Checkout API has successfully completed all of its necessary processes, it should execute an HTTP POST request to the Button Order API’s "create order" endpoint to report the order. The payload should include the Attribution Token (btn_ref), passed to your Checkout API by your client (iOS, android, mobile web) at the end of previous section.

curl https://api.usebutton.com/v1/order \
  -X POST \
  -u your_api_key: \
  -H "Content-Type: application/json" \
  -d '{
    "total": 50,
    "currency": "USD",
    "order_id": "1989",
    "finalization_date": "2017-08-02T19:26:08Z",
    "btn_ref": "srctok-XXX",
    "customer": {
      "id": "mycustomer-1234",
      "email_sha256": "'`echo -n "user@example.com" | openssl dgst -sha256`'"
    }
  }'
var client = require('@button/button-client-node')('sk-XXX');

client.orders.create({
  total: 50,
  currency: 'USD',
  order_id: '1989',
  finalization_date: '2017-08-02T19:26:08Z',
  btn_ref: 'srctok-XXX', // This is the Attribution Token POSTed from your app
  customer: {
    id: 'mycustomer-1234',
    email_sha256: crypto.createHash('sha256').update('user@example.com'.toLowerCase().trim()).digest('hex')
  }
}, function(err, res) {
  console.log(res);
});
require 'button'

client = Button::Client.new('sk-XXX')

response = client.orders.create({
  total: 50,
  currency: 'USD',
  order_id: '1989',
  finalization_date: '2017-08-02T19:26:08Z',
  btn_ref: 'srctok-XXX', # This is the Attribution Token POSTed from your app
  customer: {
    id: 'mycustomer-1234',
    email_sha256: Digest::SHA256.hexdigest('user@example.com'.downcase.strip)
  }
})

puts response
# => Button::Response(button_order_id: btnorder-XXX, total: 50, ... )
from pybutton import Client

client = Client('sk-XXX')

response = client.orders.create({
    'total': 50,
    'currency': 'USD',
    'order_id': '1989',
    'finalization_date': '2017-08-02T19:26:08Z',
    'btn_ref': 'srctok-XXX', # This is the Attribution Token POSTed from your app
    'customer': {
        'id': 'mycustomer-1234',
        'email_sha256': hashlib.sha256("user@example.com".lower().strip()).hexdigest()
    }
})

print(response)
# <class pybutton.Response total: 50, currency: 'USD', ...>

Update an order

When your API sees an adjusted order, you are required to report the adjustment to Button's Order API’s "update order" endpoint.

curl https://api.usebutton.com/v1/order/<btnorder-XXX> \
  -X POST \
  -u your_api_key: \
  -H "Content-Type: application/json" \
  -d '{
    "total": 60
  }'
var client = require('@button/button-client-node')('sk-XXX');

client.orders.update('btnorder-XXX', { total: 60 }, function(err, res) {
    console.log(res);
});
require 'button'

client = Button::Client.new('sk-XXX')

response = client.orders.update('btnorder-XXX', total: 60)

puts response
# => Button::Response(button_order_id: btnorder-XXX, total: 60, ... )
from pybutton import Client

client = Client('sk-XXX')

response = client.orders.update('btnorder-XXX', {
    'total': 60,
})

print(response)
# <class pybutton.Response total: 60, currency: 'USD', ...>

Delete an order

​When your API sees a cancelled order, you are required to report the cancellation to Button's Order API’s "delete order" endpoint. After an order is deleted, its order_id is free to use again in another order.

curl https://api.usebutton.com/v1/order/<btnorder-XXX> \
   -X DELETE \
   -u your_api_key:
var client = require('@button/button-client-node')('sk-XXX');

client.orders.del('btnorder-XXX', function(err, res) {
    console.log(res);
});
require 'button'

client = Button::Client.new('sk-XXX')

response = client.orders.delete('btnorder-XXX')

puts response
# => Button::Response()
from pybutton import Client

client = Client('sk-XXX')

response = client.orders.delete('btnorder-XXX')

print(response)
# <class pybutton.Response >

The Order API accepts the following parameters when creating, updating, or deleting an order:

  • total: Total attributable order value, in smallest decimal currency units. Must be an integer >= 0. Example: 1234 for $12.34. Net order total excluding VAT, all other taxes, surcharges and any additional costs such as delivery (i.e. total should be the actual value of the product or service before any adjustments).
  • currency: Three-letter ISO currency code as specified in ISO 4217.
  • order_id: Partner-specified unique order id, treated as an ASCII string. 255 character maximum.
  • btn_ref (optional): The Button referral code. This field is optional to create an order, but is required for attributing your order to the publisher that drove the user to your app. Note: even though this is marked as optional, you should be providing a Button referral code when reporting orders.
  • advertising_id (optional): If known, the last known Apple IDFA or Google Advertising ID for the customer making the purchase.
  • customer (optional):
    • id: The ID for the current customer in your system.
    • email_sha256 (optional): The SHA-256 hash of the customer's lowercase email, as a 64-character hex string. Note: The value of the e-mail address must be converted to lowercase before computing the hash. The hash itself may use uppercase or lowercase hex characters. Internally, Button always normalizes the hash to lowercase.
    • advertising_id (optional): The customer's IDFA / AAID.
  • line_items (optional): An array of line item details of your order. Note: even though this is marked as optional, it is highly recommended to report line items to enable item level rewards and targeting, as well as improving customer support capabilities. See this guide for more information.
    • identifier: The unique identifier of your line item.
    • amount: Total attributable order value for the line item, in smallest decimal currency units. Must be an integer >= 0. Example: 1234 for $12.34. Net item value excluding VAT, all other taxes, surcharges and any additional costs such as delivery (i.e. amount should be the actual value of the product or service before any adjustments).
    • quantity (optional): The number of units of this line item. Must be an integer > 1. Defaults to 1.
    • description (optional): Text describing the line item.
    • attributes (optional): A key/value store for strings to specify additional information about a line item. Examples of attributes are: top level / meta category identifier with a category; secondary category identifier with a subcategory; primary manufacturer of the product with a brand; the UPC (universal product code) of an item with a upc. Note: even though this is marked as optional, these are required for retail Merchants. See this guide for more information and examples.

The Order API has advanced request parameters. These should only be provided in the payload if specifically told to do so by Button. Providing them otherwise may cause errors when reporting.

  • finalization_date (optional): When (in an ISO-8601 date) the order should move to the finalized state. If no value is supplied the default finalization date for your organization will be used. A date more than a year from now will be capped at a year from the current time. Note: Only use this field if you have variable order finalization dates (e.g. Hotel stays, which typically are finalized at the end of a reservation and may vary from order to order. For more information on order life cycles, read further here).

Next Steps

You are now reporting orders to Button! Which would you like to look at next?


Line Items

Including line item (line_items) minimizes errors that can occur when reporting orders to Button while also helping increase ROI you see from Publishers who integrate your inventory into their application. It allows them to customize push notifications, in-app placement, and email promotions for your products based on these qualifying values.

View Guide

Order Life Cycle

The finalization date (finalization_date) should only be used by merchants who offer products and services with finalization dates that vary from order to order. Hotel stays are a good example of this, as they are typically finalized at the end of a reservation, and vary from order to order. Read more to see if you should include these.

View Guide