NAV
shell python javascript ruby

Overview

This is the reference documentation for all of Button APIs. Some of these APIs may be subject to change. Please contact your Button representative with any questions.

Client Libraries

We’ve developed client libraries for node.js, Python, and Ruby to simplify integrating. Consider using one if you are on a supported stack. If not, let us know! We may be able to support your runtime.

Installation

pip install pybutton
npm install @button/button-client-node
gem install button

Our client libraries can be installed with your language’s standard package manager. Use the toggles in the upper-right to select your preferred language.

Initialization

from pybutton import Client

client = Client('sk-XXX')
var client = require('@button/button-client-node')('sk-XXX');
require 'button'

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

A client is instantiated with your Organization’s API Key, sk-xxx in these examples.

Options

from pybutton import Client

client = Client("sk-XXX", {
  'hostname': 'api.testsite.com',
  'port': 80,
  'secure': False,
  'timeout': 5, # seconds
})
var client = require('@button/button-client-node')('sk-XXX', {
  hostname: 'api.testsite.com',
  port: 80,
  secure: false,
  timeout: 3000 // 3 seconds
});
require 'button'

client = Button::Client.new('sk-XXX', {
  hostname: 'api.testsite.com',
  port: 3000,
  secure: false,
  timeout: 5 # seconds
})

The client instance can be configured with the following options:

Protocol

Request Format

Request

from pybutton import Client

client = Client('sk-XXX')

response = client.orders.create({
    'total': 50,
    'currency': 'USD',
    'order_id': '2007',
    'finalization_date': '2017-08-02T19:26:08Z',
    'btn_ref': 'srctok-XXX',
    'customer': {
        'id': 'mycustomer-1234',
        'email_sha256': hashlib.sha256("user@example.com".lower().strip()).hexdigest(),
    },
})

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',
  customer: {
    id: 'mycustomer-1234',
    email_sha256: crypto.createHash('sha256').update('user@example.com'.toLowerCase().trim()).digest('hex')
  }
}, function(err, res) {
    // ...
});
require 'button'

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

response = client.orders.create({
  total: 50,
  currency: 'USD',
  order_id: '1994',
  finalization_date: '2017-08-02T19:26:08Z',
  btn_ref: 'srctok-XXX',
  customer: {
    id: 'mycustomer-1234',
    email_sha256: Digest::SHA256.hexdigest('user@example.com'.downcase.strip)
  }
})

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": "1994",
    "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`'"
    }
  }'

The Button API is designed around REST. Request parameters must be given as JSON-encoded request body.

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

Authentication

Button uses your API key for API endpoint access. Additionally, certain endpoints are available through the SDK with a user session.

For requests that require an API key, Button expects the API key via Basic Auth.

The Authorization header field is constructed as follows:

  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

Success (single)

{
    "meta": {
        "status": "ok"
    },
    "object": {
        "id": "f00b4r",
        "active": true
    }
}

Error

{
    "meta": {
        "status": "error"
    },
    "error": {
        "message": "Missing merchant approval",
        "type": "MissingApproval",
        "details": {
          "merchant_id": "org-XXX"
        }
    }
}

Responses are delivered in JSON, and may have the following fields:

Error Handling

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

API Versioning

Button versions its public API to support backwards-incompatible changes. As our product grows and changes our semantics do as well, and we want our public protocols to reflect that. This helps us enforce the sort of guarantees we want to offer to both our Publisher and Merchant partners.

The first time your Organization makes a request to Button’s public API, your version is pinned to the latest published version. Your version is guaranteed to never change, and you should never experience backwards-incompatible responses, errors, or side-effects of any API calls (sometimes we might introduce backwards-compatible changes like accepting an additional parameter).

API Versions are labeled by the date they were introduced in YYYY-MM-DD format. Importantly, API Versions are cumulative: all protocol changes introduced at or before your current API version will be in effect for all of your requests.

Published API Versions

Orders

Orders are objects used to represent a user purchase in a Merchant app or mobile website. 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 Status

All Orders have a read-only field called status that is automatically set and managed by Button. The status field will have one of the following possible values:

Orders automatically transition from open to finalized when the order’s finalization_date elapses.

POST /v1/order

Request

import hashlib
from pybutton import Client

client = Client('sk-XXX')

hashed_email = hashlib.sha256('user@example.com'.lower().strip()).hexdigest()

response = client.orders.create({
    'total': 50,
    'currency': 'USD',
    'order_id': '2007',
    'purchase_date': '2017-07-25T08:23:52Z',
    'finalization_date': '2017-08-02T19:26:08Z',
    'btn_ref': 'srctok-XXX',
    'customer': {
        'id': 'mycustomer-1234',
        'email_sha256': hashed_email,
    },
    'customer_order_id': 'abcdef-123456'
})

var crypto = require('crypto');
var client = require('@button/button-client-node')('sk-XXX');

var hashedEmail = crypto.createHash('sha256')
  .update('user@example.com'.toLowerCase().trim())
  .digest('hex');

client.orders.create({
  total: 50,
  currency: 'USD',
  order_id: '1989',
  purchase_date: '2017-07-25T08:23:52Z',
  finalization_date: '2017-08-02T19:26:08Z',
  btn_ref: 'srctok-XXX',
  customer: {
    id: 'mycustomer-1234',
    email_sha256: hashedEmail
  },
  customer_order_id: 'abcdef-123456'
}, function(err, res) {
    // ...
});
require 'digest'
require 'button'

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

hashed_email = Digest::SHA256.hexdigest('user@example.com'.downcase.strip)

response = client.orders.create({
  total: 50,
  currency: 'USD',
  order_id: '1994',
  purchase_date: '2017-07-25T08:23:52Z',
  finalization_date: '2017-08-02T19:26:08Z',
  btn_ref: 'srctok-XXX',
  customer: {
    id: 'mycustomer-1234',
    email_sha256: hashed_email
  },
  customer_order_id: 'abcdef-123456'
})

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": "1994",
    "purchase_date": "2017-07-25T08:23:52Z",
    "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`'"
    },
    "customer_order_id": "abcdef-123456"

  }'

Create an order.

Request Parameters

Note related to financial fields: Many fields in the order represent financial sums. All financial amounts must be presented as an integer in the smallest currency unit (e.g., 100 for $1.00, -100 for -$1.00).

Advanced Request Parameters

Response

Response Object

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

You will be returned an object that corresponds to your POST-ed order along with a Button Order ID. You do not need to store this ID as you can always manage orders in Button using the Order ID that you reported with the Order (your Order ID).

Error Codes

GET /v1/order/:id

Request

from pybutton import Client

client = Client('sk-XXX')

try:
    response = client.orders.get("btnorder-XXX")
except ButtonClientError as e:
    print(e)

var client = require('@button/button-client-node')('sk-XXX');

client.orders.get('btnorder-XXX', function(err, res) {
  // ...
});
require 'button'

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

response = client.orders.get('btnorder-XXX');

curl https://api.usebutton.com/v1/order/ord-xxxxx \
  -u my-api-key:

Response Object

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

Retrieve an order.

Request Parameters

POST /v1/order/:id

Request

from pybutton import Client

client = Client('sk-XXX')

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

var client = require('@button/button-client-node')('sk-XXX');

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

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

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

curl https://api.usebutton.com/v1/order/ord-xxxxx \
  -X POST \
  -u my-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "total": 1000
  }'

Response Object

{
    "meta": {
        "status": "ok"
    },
    "object": {
        "btn_ref": "srctok-12877f131651a0d6_ca",
        "button_order_id": "btnorder-52ffa8ac59e48412",
        "currency": "USD",
        "order_id": "29",
        "total": 7000,
        "status": "open",
        "customer": {
          "id": "cust-123456"
        },
        "line_items": [
            {
                "identifier": "sku-1234",
                "total": 4000,
                "amount": 2000,
                "quantity":2,
                "sku": "sku-1234",
                "upc": "400000000002",
                "category": ["Clothes"],
                "description": "Pants",
                "attributes":{
                    "size": "L"
                }
            },{
                "identifier": "sku-4567",
                "total": 3000,
                "amount": 3000,
                "quantity":1,
                "sku": "sku-4567",
                "upc": "400000000002",
                "category": ["Clothes"],
                "description": "Pants",
                "attributes":{
                    "size": "L"
                }
            }
        ],
        "purchase_date": "2016-07-25T08:23:52Z",
        "finalization_date": "2016-07-29T01:45:43Z"
    }
}

Update an order.

Request Parameters

Advanced Request Parameters

Note: you’ll need to authenticate.

Error Codes

DELETE /v1/order/:id

Request

from pybutton import Client

client = Client('sk-XXX')

response = client.orders.delete("btnorder-XXX")
var client = require('@button/button-client-node')('sk-XXX');

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

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

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

curl https://api.usebutton.com/v1/order/ord-xxxxx \
  -X DELETE \
  -u my-api-key:

Response Object

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

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

Error Codes

Accounts

Gets a list of available transaction accounts. Each currency will have its own account.

GET /v1/affiliation/accounts

Request

from pybutton import Client

client = Client('sk-XXX')

response = client.accounts.all()

print(response)
# <class pybutton.Response [2 elements]>
var client = require('@button/button-client-node')('sk-XXX');

client.accounts.all(function(err, res) {
    // ...
});
require 'button'

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

response = client.accounts.all

puts response
# => Button::Response(2 elements)
curl https://api.usebutton.com/v1/affiliation/accounts \
  -X GET \
  -u YOUR_API_KEY:

Response Object

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

HTTP Request

GET https://api.usebutton.com/v1/affiliation/accounts

Note: you’ll need to authenticate.

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 a Publisher to a Merchant and takes an action like installing the app or making a purchase (API details for a Merchant to report an order). A finalized transaction initiates a credit to the Publisher for driving the user’s transaction or app installation, and a debit to the Merchant as they received an order or an app installation. We capture the various transaction event types in the category field. Additionally, transactions have a status associated with them so that you can identify the current state of the life-cycle the transaction is in.

For a full breakdown of the fields included in the Transaction payload to the right, check out the Transaction event object.

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

Request

from pybutton import Client

client = Client('sk-XXX')

response = client.accounts.transactions('acc-XXX',
    cursor='cXw',
    start='2015-11-18T00:00:00.000Z',
    end='2015-11-19T00:00:00.000Z',
    time_field='modified_date',
)

print(response)
# <class pybutton.Response [100 elements]>
var client = require('@button/button-client-node')('sk-XXX');

client.accounts.transactions('acc-XXX', {
  cursor: 'cXw',
  start: '2015-11-18T00:00:00Z',
  end: '2015-11-19T00:00:00Z'
  time_field: 'modified_date',
}, function(err, res) {
    // ...
});
require 'button'

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

response = client.accounts.transactions('acc-XXX', {
  cursor: 'cXw',
  start: '2015-11-18T00:00:00Z',
  end: '2015-11-19T00:00:00Z'
  time_field: 'modified_date',
})
cursor = response.next_cursor

puts response
# => Button::Response(75 elements)
# without optional arguments
curl https://api.usebutton.com/v1/affiliation/accounts/acc-XXX/transactions \
  -X GET \
  -u YOUR_API_KEY:

# with optional arguments
curl https://api.usebutton.com/v1/affiliation/accounts/acc-XXX/transactions?cursor=cXw&start=2015-11-18T00%3A00%3A00Z&end=2015-11-19T00%3A00%3A00Z&time_field=modified_date \
  -X GET \
  -u YOUR_API_KEY:

Response Object

{
    "meta": {
        "status": "ok",
        "next": "https://api.usebutton.com/v1/affiliation/acc-xxx/transactions?cursor=cD0yMDE2LTAyLTExKzE3JTNBMDUlM0ExNyUyQjAwJTNBMDA3",
        "previous": null
    },
    "objects": [
        //Sample Transaction -- order
        {
            "publisher_customer_id": "1111-3333-4444-999999999999",
            "publisher_organization": "org-YYY",
            "publisher_organization_name": "Publisher Company Name",
            "commerce_organization": "org-XXX",
            "commerce_organization_name": "Merchant Company Name",
            "button_id": "static",
            "account_id": "acc-XXX",
            "btn_ref": "srctok-XXX",
            "pub_ref": "Publisher Reference String",
            "button_order_id": "btnorder-XXX",
            "order_id": null,
            "order_total": 6000, //Transaction amount
            "order_currency": "USD",
            "order_line_items": [
                {
                    "identifier": "sku-1234",
                    "total": 6000,
                    "amount": 2000,
                    "quantity": 3,
                    "publisher_commission": 600,
                    "sku": "sku-1234",
                    "gtin": "00400000000001",
                    "category": ["Clothes"],
                    "description": "T-shirts",
                    "attributes": {
                        "size": "M"
                    }
                }
            ],
            "order_click_channel": "app",
            "order_purchase_date": null,
            "category": "new-user-order",
            "id": "tx-XXX",
            "created_date": "2015-11-18T19:49:17Z",
            "modified_date": "2015-11-18T19:49:17Z",
            "validated_date": null,
            "attribution_date": "2015-11-18T19:49:17Z",
            "amount": 600, //Commission amount
            "currency": "USD",
            "status": "pending",
            "advertising_id": null,
            "customer_order_id": null,
        },
        //Sample Transaction -- app install
        {
            "publisher_customer_id": "1111-3333-4444-999999999999",
            "publisher_organization": "org-YYY",
            "publisher_organization_name": "Publisher Company Name",
            "commerce_organization": "org-XXX",
            "commerce_organization_name": "Merchant Company Name",
            "button_id": "static",
            "account_id": "acc-XXX",
            "btn_ref": "srctok-XXX",
            "pub_ref": "Publisher Reference String",
            "button_order_id": null,
            "order_id": null,
            "order_total": null,
            "order_currency": null,
            "order_line_items": null,
            "order_click_channel": null,
            "order_purchase_date": null,
            "category": "app-install",
            "id": "tx-XXX",
            "created_date": "2015-11-18T19:49:17Z",
            "modified_date": "2015-11-18T19:49:17Z",
            "validated_date": "2015-11-18T19:49:17Z",
            "attribution_date": "2015-11-18T19:49:17Z",
            "amount": 100, //Commission amount
            "currency": "USD",
            "status": "validated",
            "advertising_id": null
        }
    ]
}

HTTP Request

GET https://api.usebutton.com/v1/affiliation/accounts/:id/transactions

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.

Customers

The Customers API lets you tell us about your Customers to unlock Customer Segments, as well as other upcoming features.

POST /v1/customers

Request

curl https://api.usebutton.com/v1/customers \
  -X POST \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "id": "customer-1234",
    "email_sha256": "'`echo -n "user@example.com" | openssl dgst -sha256`'",
    "device_id": "abcdefg"
  }'
import hashlib
from pybutton import Client

client = Client('sk-XXX')

hashed_email = hashlib.sha256('user@example.com'.lower().strip()).hexdigest()

response = client.customers.create({
    'id': 'customer-1234',
    'email_sha256': hashed_email,
    'device_id': 'abcdefg',
})
var crypto = require('crypto');
var client = require('@button/button-client-node')('sk-XXX');

var hashedEmail = crypto.createHash('sha256')
  .update('user@example.com'.toLowerCase().trim())
  .digest('hex');

client.customers.create({
  id: 'customer-1234',
  email_sha256: hashedEmail,
  device_id: "abcdefg"
}, function(err, res) {
    // ...
});
require 'digest'
require 'button'

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

hashed_email = Digest::SHA256.hexdigest('user@example.com'.downcase.strip)

response = client.customers.create({
  id: 'customer-1234',
  email_sha256: hashed_email,
  device_id: 'abcdefg'
})

Response Object

{
  "id": "customer-1234"
}

Create a new Customer in Button. If the Customer already exists, it will be updated with the identifying factors provided.

HTTP Request

POST https://api.usebutton.com/v1/customers

Request Parameters

GET /v1/customers/:id

Request

curl https://api.usebutton.com/v1/customers/customer-1234 \
  -X GET \
  -u YOUR_API_KEY:
from pybutton import Client

client = Client('sk-XXX')

response = client.customers.get('customer-1234')

print(response)
# <class pybutton.Response id: customer-1234, ...>
var client = require('@button/button-client-node')('sk-XXX');

client.customers.get('customer-1234', function(err, res) {
  // ...
});
require 'button'

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

response = client.customers.get('customer-1234')

puts response
# => Button::Response(id: customer-1234, ...)

Response Object

{
  "meta": {
    "status": "ok"
  },
  "object": {
    "id": "customer-1234",
    "created_at": "2017-07-17T21:52:21.748Z",
    "emails_sha256": [
      "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
    ],
    "device_ids": [
      "abcdefg"
    ],
    "segment": "new"
  }
}

Retrieve a Customer from the Button API. You can lookup by either your Customer ID, or the Button Customer ID.

HTTP Request

GET https://api.usebutton.com/v1/customers/:id

Response Object

Note: you’ll need to authenticate.

Merchants

The Merchants endpoint is used by Publishers to retrieve all relevant information for the Merchants they are partnered with.

GET /v1/merchants

Fetch all partnered Merchants and associated information available.

Request

curl https://api.usebutton.com/v1/merchants?status=approved \
  -X GET \
  -u YOUR_API_KEY:
from pybutton import Client

client = Client('sk-XXX')

response = client.merchants.all(status='approved')
var client = require('@button/button-client-node')('sk-XXX');

client.merchants.all({
  status: 'approved'
}, function(err, res) {
    // ...
});
require 'button'

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

response = client.merchants.all(status: 'approved')

Response Object

{
  "objects": [
    {
      "id": "org-xxxxxxxxxxxxxxxx",
      "name": "Merchant123",
      "categories": [
        "Travel"
      ],
      "urls": {
        "homepage": "https://example.com",
        "terms_and_conditions": "https://www.usebutton.com/support/terms-conditions/merchant123"
      },
      "metadata": {
        "description": "Book your perfect hotel.",
        "icon_url": "https://www.usebutton.com/no-image.png",
        "banner_url": "https://www.usebutton.com/no-image.png"
      },
      "available_platforms": ["ios", "android"],
      "supported_products": ["Instant Rewards"],
      "status": "approved"
    }
  ]
}

HTTP Request

GET https://api.usebutton.com/v1/merchants

Request Parameters

Note: you’ll need to authenticate.

Links

The Links endpoint is used to generate an attributed link for a particular merchant or request metadata about how a given link will perform in our system.

POST /v1/links

Generate and return a link to a Merchant identified by their url. This link can then be used by a single user to link to the Merchant and make attributed purchases. A Publisher user ID and Publisher reference value (e.g. click ID, campaign ID) can also be passed.

Request

curl https://api.usebutton.com/v1/links \
  -X POST \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://jet.com",
    "experience": {
      "btn_pub_user": "your-user-id",
      "btn_pub_ref":"your-publisher-reference"
    }
  }'
from pybutton import Client

client = Client('sk-XXX')

response = client.links.create({
    'url': 'https://www.jet.com',
    "experience": {
        'btn_pub_user': 'your-user-id',
        'btn_pub_ref': 'your-publisher-reference',
    },
})

print(response)
# <class pybutton.Response merchant_id: org-XXXXXXXXXXXXXXX, ...>
var client = require('@button/button-client-node')('sk-XXX');

client.links.create({
  url: "https://www.jet.com",
  experience: {
    btn_pub_user: "your-user-id",
    btn_pub_ref: "your-publisher-reference"
  }
}, function(err, res) {
  // ...
});
require 'button'

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

response = client.links.create({
    url: "https://www.jet.com",
    experience: {
        btn_pub_user: "your-user-id",
        btn_pub_ref: "your-publisher-reference"
    }
})

puts response
# => Button::Response()

Response Object

{
  "meta": {
    "status": "ok"
  },
  "object":{
    "merchant_id": "org-XXX",
    "affiliate": null,
    "links": {
      "universal": "https://r.bttn.io?btn_pub_user=your-user-id&btn_pub_ref=your-publisher-reference&btn_url=https%3A%2F%2Fjet.com&btn_ref=org-XXX"
    }
  }
}

HTTP Request

POST https://api.usebutton.com/v1/links

Request Parameters

POST /v1/links/info

Fetch attributes of a URL. This includes the id of the merchant in Button’s namespace (organization_id), approval status, and supported Purchase Path.

Request

curl https://api.usebutton.com/v1/links/info \
  -X POST \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://jet.com"
  }'
from pybutton import Client

client = Client('sk-XXX')

response = client.links.get_info({
    "url": "https://www.jet.com",
})

print(response)
# <class pybutton.Response merchant_id: org-XXXXXXXXXXXXXXX, ...>
var client = require('@button/button-client-node')('sk-XXX');

client.links.getInfo({
  url: "https://www.jet.com"
}, function(err, res) {
  // ...
});
require 'button'

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

response = client.links.get_info({
    url: "https://www.jet.com"
})

puts response
# => Button::Response()

Response Object

{
  "meta": {
    "status": "ok"
  },
  "object": {
    "organization_id": "org-XXX",
    "approved": true,
    "ios_support": {
      "app_to_web": true,
      "app_to_app": true,
      "web_to_web": true,
      "web_to_app": true,
      "web_to_app_with_install": false
    },
    "android_support": {
      "app_to_web": true,
      "app_to_app": true,
      "web_to_web": true,
      "web_to_app": true,
      "web_to_app_with_install": false
    }
  }
}

HTTP Request

POST https://api.usebutton.com/v1/links/info

Request Parameters

Note: you’ll need to authenticate.

Personalized Rates

Obtain personalized rates/offers available to Publisher’s user.

POST /v1/offers

Retrieve rates/offers that are available to Publisher’s user.

Request

curl https://api.usebutton.com/v1/offers \
  -X POST \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "some-user-id",
    "device_ids": ["123"],
    "email_sha256s": ["1234567a1234567a1234567a1234567a1234567a1234567a1234567a1234567a"]
  }'

Response Object

{
  "meta": {
    "status": "ok"
  },
  "object": {
    "merchant_offers": [
      {
        "merchant_id": "org-123",
        "best_offer_id": "offer-XXX",
        "offers": [
          {
            "id": "offer-XXX",
            "rate_percent": "4.5",
            "display_params": {
              "category": "Video Games"
            }
          },
          {
            "id": "offer-YYY",
            "rate_percent": "2",
            "display_params": {}
          }
        ]
      }
    ]
  }
}

HTTP request

POST https://api.usebutton.com/v1/offers

Request Parameters

Response Object

Top-level object

Field Type Description
merchant_offers list List of rates/offers available to the user.

merchant_offers List

Field Type Description
merchant_id string Merchant organization ID.
best_offer_id string ID of the best rate/offer that’s available to the user.
offers list List of all merchant rates/offers available to the user.

offers List

Field Type Description
id string Offer ID.
rate_percent string (optional) Decimal string of offer rate in percent.
rate_fixed string (optional) Decimal string of offer rate in fixed amount.
display_params map<string>string (optional) A map of template parameters that can be used by the Publisher to render the rate/offer.

Note: you’ll need to authenticate.