Last updated

These docs are intended for a developer audience.

Set up Rebilly Instruments

This topic describes how to set up the Rebilly Instruments JS library.


Before you start this tutorial, if you have not already done so, set up a payment gateway. An active gateway is required.

1. Obtain IDs and a publishable API key

  1. Obtain your organization ID and website ID:
    1. In the left navigation bar, click Settings .
    2. In the Management section, click My organization & websites.
    3. In the Organization details section, note the ID value.
    4. In the Website section, note the ID value. When you first log in to Rebilly, you create an organization as part of the setup process. A default website is created when a new organization is created. For more information, see Organizations and websites.
  2. Obtain your publishable API key:
    1. In the left navigation bar, click Automations .
    2. In the Development section, click API keys.
    3. Optionally, if you have not created a publishable key:
      1. In top right of the screen, click Add API.
      2. In the API key type section, select Publishable, then complete the form and click Save API key.
      3. Go back to the API Keys page.
    4. Select a publishable key and copy the Key value.

2. Set up Rebilly Instruments

In this step you will implement a basic Rebilly Instruments set up. Select one of the following options to install the library.

  1. Use a package manager
  2. Use Content Delivery Network (CDN)

Initial setup

Select an installation option, then install the library and provide the HTML.

Install the library

Install the library using one of the following commands:

npm install @rebilly/instruments
yarn add @rebilly/instruments

Include the HTML mounting points

The default mounting points are rebilly-instruments and rebilly-instruments-summary.

To provide your own mounting points, pass a valid CSS class or a HTML element to the RebillyInstrument.mount() options.


Configure the library

This step describes the basic set up for mounting.


Use this method to initialize the library and to configure the experience. This method returns a Promise and accepts a single configuration object.

For more information, see RebillyInstrument.mount().


Rebilly data

Provide your publishable API key, organization id, and website id, to connect with the Rebilly api.


Purchase data

Provide details of the purchase amount, using one of following properties:

  • items
  • money
  • invoiceId
  • transactionId

For more information, see Provide purchase data to Rebilly Instruments


Optional, include listeners

Use the instrument-ready and purchase-completed to connect to the lifecycle of the library.


Indicates when an instrument token is created, and provides access to the instrument response.

For more information, see RebillyInstruments.on('instrument-ready').



Indicates when a purchase is completed, and provides access to the transaction response.

For more information, see RebillyInstruments.on('purchase-completed').


Basic set up complete

You now have a basic Rebilly Instruments integration. To learn more about Rebilly Instruments, see:

Copy to clipboard
  • HTML
  • JavaScript
1import RebillyInstruments from '@rebilly/instruments';
2// Mount Rebilly Instruments
4 publishableKey: 'pk_sandbox_123',
5 organizationId: 'org-123',
6 websiteId: 'my-website-id',
7 apiMode: 'sandbox',
8 items: [
9 {
10 planId: 'my-plan-id',
11 quantity: 1
12 },
13 ]
15// Optional
16RebillyInstruments.on('instrument-ready', (instrument) => {
17'instrument-ready', instrument);
19RebillyInstruments.on('purchase-completed', (purchase) => {
20'purchase-completed', purchase);

Interactive example