Last updated 4 days ago

Reference

Error handling

The SDK returns several different types of errors based on the HTTP response, ranging from 401 to 422. They are exposed and can be imported:

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

Error types

Type Status Code Description
RebillyRequestError - Generic error when no response is available.
RebillyTimeoutError - The request timed out.
RebillyCanceledError - The request was canceled before being completed.
RebillyForbiddenError 401 Indicates an invalid API key or expired session token.
RebillyNotFoundError 404 Requested resource was not found.
RebillyMethodNotAllowedError 405 Request method not allowed on this resource.
RebillyConflictError 409 Requested operation triggered a conflict.
RebillyValidationError 422 The request payload triggered a validation error (see error details).

Configuration options

All client API configuration parameters are optional. However, a secret API key can only be provided at instantiation.

API environments

By default a client instance is always generated in the Live environment. The Sandbox mode is only recommended while developing your integration.

Option Type Description
apiKey string Your secret API key. To be used only for server-side integration. See Developer > API Keys.
sandbox boolean Flag used to enable sandbox mode for the instance. This allows you to run requests without processing real transactions on your account. Defaults to false.
timeout integer Define the timeout in milliseconds for API requests. Defaults to 6000.
organizationId string Your organization identifier in scope of which need to perform request (if not specified, the default organization will be used).
urls object Define the root urls for live and sandbox mode. Object must have a key for each mode that have strings for values. Defaults to {live: 'https://api.rebilly.com', sandbox: 'https://api-sandbox.rebilly.com'}

Collections, Members, and Files

All resource calls return either a File, Member, or Collection:

  • getAll always returns a Collection, which contains a list of Members
  • CSV or PDF downloads will return a File
  • All other methods return a Member

Frozen Objects

Both Collections and Members are immutable (frozen). Attempting to modify either one directly will result in a TypeError. You can retrieve a plain JSON object for mutation using the getJSON method.

Collection

The Collection type represents a list of Members (e.g. a list of customers, a list of transactions).

Each collection instance exposes the same properties.

Name Type Description
items Array<Member> An array of member entities. See the [Member type][goto-member] for details.
total number An integer defining the total amount of members that exist regardless of the requested limit.
limit number An integer defining the count of values returned by the API request. Reflects the limit value passed to the function which returned the Collection.
offset number A zero-based index defining the starting position for the requested members.
response Object The original response stripped down to the status code, status text and headers. Exposes three more properties: {status, statusText, headers}.
getJSON Function Returns a plain mutable JSON object exposing the items of the current collection instance. Discards all other property.
config Object An object literal with the original request query string parameters.

Member

The Member type represents an instance of a single resource entity in Rebilly (e.g. one customer, one transaction).

Each member instance exposes the same properties.

Name Type Description
fields Object An object literal with key/value pairs for each field returned by the API in the response.
response Object The original response stripped down to the status code, status text and headers. Exposes three more properties: {status, statusText, headers}.
getJSON Function Returns a plain mutable JSON object exposing the fields of the current member instance. Discards the response property.
config Object An object literal with the original request query string parameters.

File

The File type allows you to access the arraybuffer data from API requests that return files. The files can be either exported CSV data or generated invoice PDFs.

You can generate a binary file to download from the file content directly in the browser, or save it locally via the file system in Node.

Each file instance exposes the same properties.

Name Type Description
data Object An arraybuffer containing the file data returned by the request. See ArrayBuffer.
response Object The original response stripped down to the status code, status text and headers. Exposes three more properties: {status, statusText, headers}.
config Object An object literal with the original request query string parameters.