API Reference

The Button API is a simple RESTful way to interact with the Button Marketplace.

Looking to get data pushed to you? Check out our Webhook documentation.

Libraries

We've written and open sourced a few platform-specific client libraries for interacting with our API. All are dependency-free and support a wide range of platform versions. If appropriate, consider using one instead of integrating directly with our HTTP interface.


If you'd like to see another platform or version supported, let us know!

Interactive Guide

We've put together an interactive tool to that lets you make requests against our API and get real-time feedback and validation that we're handling your requests properly.

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


Protocol

Request Format

The Button API is designed around REST. Request parameters may be given as URL parameters or a JSON-encoded request body, with JSON taking precedence.

The only unusual request parameter is api_key (access it on your Button dashboard) which is sent as a basic authentication username. For example:

curl https://api.usebutton.com/v1/order \
  -X POST \
  -u my-api-key: \
  -d total=50 \
  -d currency=USD \
  -d order_id=29 \
  -d btn_ref=srctok-12877f131651a0d6

Basic Authentication

To send server authentication credentials via the Authorization header field you need to properly construct the field value. The Authorization field is constructed as follows for our API:

  1. Add a colon to the end of the api key (e.g. apiKey + ":")
  2. Base64 encode the resulting string
  3. The authorization method and a space i.e. "Basic " is then put before the encoded string. (e.g. "Basic " + base64Encode(apiKey + ":"))

Response Format

Responses are delivered in JSON, with the following top-level fields:

Examples:

// Success (single).
{
    "meta": {
        "status": "ok"
    },
    "object": {
        "id": "f00b4r",
        "active": true
    }
}

// Error.
{
    "meta": {
        "status": "error"
    },
    "error": {
        "message": "Client not wearing jumper."
    }
}

Error Handling

The service uses standard HTTP response code conventions to indicate success or failure:

Endpoints

Order

Orders are objects used to represent a user purchase in a commerce application. It is preferable to report all orders to the Button API, regardless of whether you have a known Button btn_ref to enable seamless investigation and support in cases of Loyalty & Rewards publishers.

Order Statuses

Create order

POST /v1/order

Creates an order.

Request Parameters

Advanced Request Parameters

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!

Response

{
    "meta": {
        "status": "ok"
    },
    "object": {
        "btn_ref": "srctok-12877f131651a0d6",
        "button_order_id": "btnorder-52ffa8ac59e48412",
        "currency": "USD",
        "order_id": "29",
        "total": 7000,
        "status": "open",
        "customer": {
            "id": "customer-1234"
        },
        "line_items": [
            {
                "identifier": "sku-1234",
                "amount": 2000,
                "quantity":2,
                "description": "T-shirts",
                "attributes":{
                    "size": "M",
                    "upc": "400000000001"
                }
            },{
                "identifier": "sku-4567",
                "amount": 3000,
                "quantity":1,
                "description": "Pants",
                "attributes":{
                    "size": "L",
                    "upc": "400000000002"
                }
            }
        ],
        "finalization_date": "2016-07-29T01:45:43Z"
    }
}

Get order

GET /v1/order/:id

Retrieve an order.

Request parameters

Response

{
    "meta": {
        "status": "ok"
    },
    "object": {
        "btn_ref": "srctok-12877f131651a0d6",
        "button_order_id": "btnorder-52ffa8ac59e48412",
        "currency": "USD",
        "customer": {
            "id": "customer-1234"
        },
        "line_items": [
            {
                "identifier": "sku-1234",
                "amount": 2000,
                "quantity":2,
                "description": "T-shirts",
                "attributes":{
                    "size": "M",
                    "upc": "400000000001"
                }
            },{
                "identifier": "sku-4567",
                "amount": 3000,
                "quantity":1,
                "description": "Pants",
                "attributes":{
                    "size": "L",
                    "upc": "400000000002"
                }
            }
        ],
        "order_id": "29",
        "status": "open",
        "total": 7000,
        "finalization_date": "2016-07-29T01:45:43Z"
    }
}

Update order

POST /v1/order/:id

Update an order.

Orders can be updated only while the order is in the open state.

Request parameters

Advanced Request Parameters

Note: you'll need to authenticate.

Response

{
    "meta": {
        "status": "ok"
    },
    "object": {
        "btn_ref": "srctok-12877f131651a0d6",
        "button_order_id": "btnorder-52ffa8ac59e48412",
        "currency": "USD",
        "order_id": "29",
        "total": 6000,
        "status": "open",
        "line_items": [
            {
                "identifier": "sku-1234",
                "amount": 2000,
                "quantity":3,
                "description": "T-shirts",
                "attributes":{
                    "size": "M",
                    "upc": "400000000001"
                }
            }
        ],
        "finalization_date": "2016-07-29T01:45:43Z"
    }
}

Delete order

DELETE /v1/order/:id

Deletes an order.

Orders can be deleted only during the order adjustment period, which defaults to 7 days from when the order was created.

Request parameters

Note: you'll need to authenticate.

Response

{
    "meta": {
        "status": "ok"
    },
    "object": null
}

Get accounts

GET /v1/affiliation/accounts

Gets a list of available accounts. An account is similar to a bank account, it has a specific currency and has a list of transactions.

Request parameters

Note: you'll need to authenticate.

Response

{
   "meta": {
        "status": "ok"
    },
    "objects": [
        {
            "id": "acc-130060b42a047270",
            "name": "Button Account",
            "currency": "USD",
            "organization": "org-63cd58a1a2a8b543"
        }
    ]
}

Get transactions

GET /v1/affiliation/accounts/:id/transactions

Get a list of transactions. A transaction is a record of a commission owed or earned. A transaction is created when a user moves from one app to another and takes an action like installing the app, or purchasing an item (API details for a Commerce app to report an order). This is so that we can credit the Publisher app for driving the user, and debit the Commerce app as they recieved something they wanted (a new user or an order).

Request parameters

If you want to paginate across your transactions, utilize the meta.next URL as your next request URL until it is null.

Note: you'll need to authenticate.

Response

{
    "meta": {
        "status": "ok",
        "next": "https://api.usebutton.com/v1/affiliation/acc-130060b42a047270/transactions?cursor=cD0yMDE2LTAyLTExKzE3JTNBMDUlM0ExNyUyQjAwJTNBMDA3",
        "previous": null
    },
    "objects": [
        {
            "id": "tx-070dd05f5db6e4ec",
            "amount": 600,
            "currency": "USD",
            "category": "new-user-order",
            "created_date": "2015-11-18T19:49:17Z",
            "modified_date": "2015-11-18T19:49:17Z",
            "validated_date": null,
            "account_id": "acc-123",
            "btn_ref": "srctok-123",
            "button_order_id": "btnorder-52ffa8ac59e48412",
            "order_id": "order-1",
            "order_currency": "USD",
            "order_total": 6000,
            "customer": {
                "id": "customer-1234"
            },
            "order_line_items": [
                {
                    "identifier": "sku-1234",
                    "amount": 2000,
                    "quantity":3,
                    "description": "T-shirts",
                    "attributes": {
                        "size": "M",
                        "upc": "400000000001"
                    }
                }
            ],
            "publisher_organization": "org-63cd58a1a2a8b543",
            "publisher_customer_id": "6815467b-93ca-47ce-97ae-bcf8b4292a87",
            "button_id": "btn-59722058ab439774",
            "commerce_organization": "org-44ae5a8149efe050",
            "status": "pending",
            "advertising_id": "02840796-66B3-4C96-AF72-84393B4925BF"
        }, {
            "id": "tx-40d9fe33d8e3d5ea",
            "amount": 1000,
            "currency": "USD",
            "category": "app-install",
            "created_date": "2015-11-18T19:49:17Z",
            "modified_date": "2015-11-18T19:49:17Z",
            "validated_date": "2015-11-18T19:49:17Z",
            "account_id": "acc-123",
            "btn_ref": "srctok-123",
            "button_order_id": null,
            "order_id": null,
            "order_currency": null,
            "order_total": null,
            "order_line_items": null,
            "publisher_organization": "org-63cd58a1a2a8b543",
            "publisher_customer_id": "6815467b-93ca-47ce-97ae-bcf8b4292a87",
            "button_id": "btn-59722058ab439774",
            "commerce_organization": "org-44ae5a8149efe050",
            "status": "validated",
            "advertising_id": "02840796-66B3-4C96-AF72-84393B4925BF"
        }
    ]
}

Advanced Application Notes

Order Life Cycle

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 (Note: Most merchants should not pass the optional finalization_date parameter when reporting orders to Button's API. For more information and to see if you should be passing this parameter, see here). This date and time is automatically calculated by taking the date and time when the order is reported to Button's API and adding your account's default finalization window (i.e. the time allowable for an order to be modified or deleted). The value for your default finalization window was set when you were initially onboarded with Button and is immutable through the API and the dashboard.

Default Finalization Date Example

An order is reported to Button's API on January 1st 2017 at 12pm EST (2017-01-01T17:00:00Z) and the account's default finalization window is one week. When the order is reported to Button's API, the state of the order will be

{
  ...
  "status": "open",
  "finalized_date": "2017-01-08T17:00:00Z",
  ...
}

Note that the finalization_date is January 8th, 2017 at 12pm EST, which is one week (i.e. the account's default finalization window) from when the order was reported. It is until this date and time that the order can be modified or deleted. Once this date and time has passed, Button will automatically update the state and it will be

{
  ...
  "status": "finalized",
  "finalized_date": "2017-01-08T17:00:00Z",
  ...
}

After this, this order can no longer be modified or deleted.

When to Use Custom Finalization Date

In some cases an order should be finalized at a custom time. This is specified by passing the optional parameter finalization_date when reporting an order to Button's API. 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. If the finalization_date parameter is passed when reporting an order to Button's API, it will override the automatic assignment of it, as described in the above section.

Changelog

2016-07-29

2016-06-22

2016-04-11