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:
getAllalways returns aCollection, 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 thegetJSONmethod.
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 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 using the file system in Node.js.
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. |