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!

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

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. This call must be made with authentication.

Response

{
    "meta": {
        "status": "ok"
    },
    "object": {
        "btn_ref": "srctok-12877f131651a0d6",
        "button_order_id": "btnorder-52ffa8ac59e48412",
        "currency": "USD",
        "order_id": "29",
        "total": 7000,
        "status": "open",
        "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",
        "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

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,
            "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"
        }
    ]
}

Changelog

2016-07-29

2016-06-22

2016-04-11