Last updated

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

TypeStatus codeDescription
RebillyRequestError-Generic error when no response is available.
RebillyTimeoutError-The request timed out.
RebillyCanceledError-The request was canceled before being completed.
RebillyForbiddenError401Indicates an invalid API key or expired session token.
RebillyNotFoundError404Requested resource was not found.
RebillyMethodNotAllowedError405Request method not allowed on this resource.
RebillyConflictError409Requested operation triggered a conflict.
RebillyValidationError422The 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.

OptionTypeDescription
apiKeystringYour secret API key. To be used only for server-side integration. See Developer > API Keys.
sandboxbooleanFlag used to enable sandbox mode for the instance. This allows you to run requests without processing real transactions on your account. Defaults to false.
timeoutintegerDefine the timeout in milliseconds for API requests. Defaults to 6000.
organizationIdstringYour organization identifier in scope of which need to perform request (if not specified, the default organization will be used).
urlsobjectDefine 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.

NameTypeDescription
itemsArray<Member>An array of member entities. See the Member type for details.
totalnumberAn integer defining the total amount of members that exist regardless of the requested limit.
limitnumberAn integer defining the count of values returned by the API request. Reflects the limit value passed to the function which returned the Collection.
offsetnumberA zero-based index defining the starting position for the requested members.
responseObjectThe original response stripped down to the status code, status text and headers. Exposes three more properties: {status, statusText, headers}.
getJSONFunctionReturns a plain mutable JSON object exposing the items of the current collection instance. Discards all other property.
configObjectAn 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.

NameTypeDescription
fieldsObjectAn object literal with key-value pairs for each field returned by the API in the response.
responseObjectThe original response stripped down to the status code, status text and headers. Exposes three more properties: {status, statusText, headers}.
getJSONFunctionReturns a plain mutable JSON object exposing the fields of the current member instance. Discards the response property.
configObjectAn 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 using the file system in Node.js.

Each file instance exposes the same properties.

NameTypeDescription
dataObjectAn arraybuffer containing the file data returned by the request. See ArrayBuffer.
responseObjectThe original response stripped down to the status code, status text and headers. Exposes three more properties: {status, statusText, headers}.
configObjectAn object literal with the original request query string parameters.