Merchants API on
All Platforms

Merchants API

This guide walks you through how to utilize the Merchants API. We'll cover:

  1. What is the Merchants API
  2. Partnering with Merchants
  3. Fetching Merchants from the API

What is the Merchants API?

The Merchants API enables Publishers to retrieve all of the relevant information for the Merchants they are partnered with through Button. It encompasses a set of APIs that gives you access to all of your Merchant partners on Button, complete with brand information, URLs, icons, and more. You can use this API to help populate your Content Management System with accurate Merchant details.

Looking for the full API Reference? Check out the Merchants API Reference.

Partner Logos

Note: Want to work with companies not supported today? Just let us know and we'll work with them to make it happen!


Partnering with Merchants

In order to use the Merchants API, you first need Merchant partners. Please reach out to your Partner Success Manager to inquire about working with more Merchants.


Fetching Merchants from the API

Fetching Merchant partners from the API is a simple as an HTTP GET with some parameters and an Auth header.

Authorization

You can fetch your Button API Key in the Organization Settings page of the Dashboard.

The Button Merchants API uses Basic HTTP Authentication. The Authorization field should be 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 + ":"))

Note: There is a pre-computed version of this value in the Organization Settings screen too.

Fetching Partners

The /v1/merchants endpoint gives you access to details for your Merchant partners. For full API documentation, see the API Reference.

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

This will give you a response object that describes the partner and their branding information.

{
  "objects": [
    {
      "id": "org-XXX",
      "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"
    }
  ]
}