Report Orders to Button on
All Platforms

Report Orders to Button

After the Attribution Token for an order is POSTed to your Checkout API (completed at the end of the Integrate the Button SDK guide), 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.

If you are persisting the Attribution Token, make sure to set the size limits properly in your database. The Attribution Token can be up to 255 characters.

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.

Basic 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 guide.

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 >

Request Parameters

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, a URL safe string up to 255 characters. 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 section 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 section for more information and examples.

Advanced Request Parameters

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).

Why server to server call?

Button requires you to POST the order information from your mobile application to your Checkout API, then to Button's Order API. The reason we require the intermediary step of POSTing to your Checkout API rather than allow you to report orders directly from your mobile application to Button's Order API is to protect user information, increase reliability of reporting orders to Button, and minimize any risk of security issues.

Error messages

Button API response codes

Button uses conventional HTTP response codes to indicate success or failure:

  • 200-level response codes indicate success
  • 400-level response codes indicate an error in the request data
  • 500-level response codes indicate a server error

400 error

Most 400 errors occur when you do not include a required parameter in the payload when POSTing to Button's Order API. The missing parameter is typically the order amount. Check to make sure you are including this and any other required parameters if you are receiving a 400 error.

401 error

A 401 error will occur if there is neither a session_id nor api_key included in the payload. Be sure to include at least one of these when reporting orders to Button's Order API.

404 error

A 404 error means we could not find the order ID. This means that you already reported it or you already canceled it.

409 error

A 409 error will occur is you attempt to submit the same order_id to Button's Order API twice. This prevents any duplicate orders being reported to Button.

500 error

If you receive a 500 error message when reporting orders to Button's API for whatever reason, you should retry submitting the request. If this error persists, please contact support.

Finalization date

Each order that is reported to Button's API, by default, will be automatically assigned a finalization_date, which is the date and time when a particular order can no longer be modified or deleted. Most merchants should not pass the optional finalization_date parameter when reporting orders to Button's API, but in some cases an order should be finalized at a custom time. This 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.

For more information on finalization date, see this guide.

Why add line items when reporting orders to Button?

Line item (line_items) level details are not required when reporting orders to Button but we highly encourage including these. Including 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. We recommend including line items for two major reasons:

  1. Product/Event targeting
    • Including this data will allow Publishers to target specific products for events, promotions, etc. (e.g. "earn 2x cashback when purchasing chicken wings for the big game!")
    • Merchants that run item or brand level campaigns on Button see:
      • 3x greater daily revenue
      • 5x more user engagement
      • 5x more app opens
      • Repeat purchase rates higher than 40%
      • 50% increase in new user app installs
  2. Debugging and Customer Service
    • When a customer service request comes in, if Button has line item level data, we can provide direct support to the customers without having to escalate to you for further details (e.g. "you only received $2.00 cash-back because your order included a single pizza pie, and this is your reward earnings from that"). Without this detail, we may rely on escalations to your team to provide the details of an order.

Example line items by vertical

Retail

Items in retail Merchant orders will typically have UPC and SKU codes. These should be passed in the optional attributes parameter within the optional line_items parameter when POSTing to Button's Order API. Here is a sample line_items array with attributes containing UPC and SKU codes.

{
  ...
    "line_items": [
        {
            "identifier": "sku-1234",
            "amount": 2000,
            "quantity":2,
            "description": "Shovels",
            "attributes": {
                "category": "Home&Garden",
                "subcategory": "Tools",
                "brand": "Ames",
                "upc": "049206633742"
            }
        },{
            "identifier": "sku-4567",
            "amount": 3000,
            "quantity":1,
            "description": "Rakes",
            "attributes": {
                "category": "Home&Garden",
                "subcategory": "Tools",
                "brand": "Ames",
                "upc": "049206633745"
            }
        }
    ]
  ...
}

Hospitality and Travel

Items in hospitality and travel orders will typically have the site the reservation was booked, how much the booking costs per night, the checkin and checkout dates, and the number of guests on the reservation. These should be passed in the optional attributes parameter within the optional line_items parameter when POSTing to Button's Order API. In addition, you should include the finalization_date (for more information on this, see this guide). Here is a sample line_items array with attributes containing these:

{
  ...
    "line_items": [
        {
            "identifier": "sku-7890",
            "amount": 14941,
            "quantity":1,
            "description": "A Cool Motel",
            "finalization_date": "2017-08-02T19:26:08Z",
            "attributes": {
                "booking_type": "Website to book stuff",
                "nightly_cost": 16808,
                "checkin": "2017-03-23",
                "checkout": "2017-03-25",
                "guests": 2
            }
        }
    ]
  ...
}

Delivery

Items in retail Merchant orders will typically have a UPC code. These should be passed in the optional attributes parameter within the optional line_items parameter when POSTing to Button's Order API. Here is a sample line_items array with attributes containing the UPC code.

{
  ...
    "line_items": [
        {
            "identifier": "sku-2345",
            "amount": 100,
            "quantity":1,
            "description": "Orange Juice",
            "attributes":{
                "upc": "400000000003"
            }
        },{
            "identifier": "sku-6789",
            "amount": 200,
            "quantity":2,
            "description": "Milk",
            "attributes":{
                "upc": "400000000004"
            }
        }
    ]
  ...
}

Next Step

Read more on the Button order life cycle.