Last updated 5 months ago

Usage

Rebilly offers several APIs, each with a specific purpose. In order to perform operations on an API you must instantiate the corresponding API client, as detailed below. Performing API operations is identical across all API clients.

Promise-based

Every resource method returns a chainable Promise.

RebillyAPI

This is the main API client. Often you will only need this client. It includes resources for the main Rebilly API and the Rebilly User API.

Usage with Node

Import the RebillyAPI method and initialize it with your secret API key (and optionally organizationId) The full list of configuration options can be found here

ES7 example:

import RebillyAPI from 'rebilly-js-sdk';

const api = RebillyAPI({apiKey: 'secret-api-key', organizationId: '11111111-1111-1111-1111-111111111111'});

try {
    const transactions = await api.transactions.getAll();
    transactions.items.forEach(transaction => {
        //transaction.fields
    });
} catch (err) {
    console.error(err.name);
}

ES5 example:

var RebillyAPI = require('rebilly-js-sdk').default;
var api = RebillyAPI({apiKey: 'secret-api-key', organizationId: '11111111-1111-1111-1111-111111111111'});

api.transactions.getAll()
    .then(function(transactions) {
        transactions.items.forEach(function(transaction) {
            //transaction.fields
        });
    })
    .catch(function(err) {
        console.error(err.name);
    });

Usage in browser

You should never use a secret API key in the browser because it will be exposed by each API call in plain text. Instead a JWT session token should be provided to the API instance.

To do this, initialize the API client without an API key.

You can then get a JWT by providing your account email and password to the signin endpoint.

Example:

// instantiate an unauthorized API client
const api = RebillyAPI();

// build the sign in payload
const payload = {data: {email, password, expiredTime}};

// the 'signIn' method does not require API authorization to complete
const response = await api.account.signIn(payload);

// set the session token for future API requests that require
// an authorization using the response fields
api.setSessionToken(response.fields.token);

// this request will be authorized using the token
const customers = await api.customers.getAll();

RebillyExperimentalAPI

This client includes resources for the experimental Rebilly Reports API. It is used mainly for reporting and requests with heavy computational loads like dashboard statistics.

Versionless API

The experimental API can introduce backward incompatible changes to the API specification. Unlike the main API, it does not support versioning.

Usage with Node

Import the RebillyExperimentalAPI method and initialize it with your API key (and optionally organizationId) The full list of configuration options can be found here

import {RebillyExperimentalAPI} from 'rebilly-js-sdk';

const experimentalAPI = RebillyExperimentalAPI({apiKey: 'secret-api-key', sandbox: true, timeout: 10000});

Usage in browser

You should never use a secret API key in the browser because it will be exposed by each API call in plain text. Instead a JWT session token should be provided to the API instance.

To do this, initialize the API client without an API key.

In order to get a JWT you will need to use the sign in method from the main API client. The same JWT can be used for both RebillyAPI and RebillyExperimentalAPI.

Example:

// instantiate main API client
const api = RebillyAPI();

// instantiate experimental API client
const experimentalAPI = RebillyExperimentalAPI();

// build the sign in payload
const payload = {data: {email, password, expiredTime}};

// use the main client's signIn method to get a JWT
const response = await api.account.signIn(payload);

// set the session token for the experimental client
experimentalApi.setSessionToken(response.fields.token);