Rebilly API (latest)

Download OpenAPI specification:Download

Introduction

The Rebilly API is built on HTTP and is RESTful. It has predictable resource URLs and returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. Use your favorite HTTP/REST library in your programming language when using this API, or use one of the Rebilly SDKs, which are available in PHP and JavaScript.

Every action in the Rebilly UI is supported by an API which is documented and available for use, so that you may automate any necessary workflows or processes. This API reference documentation contains the most commonly integrated resources.

Authentication

This topic describes the different forms of authentication that are available in the Rebilly API, and how to use them.

Rebilly offers four forms of authentication: secret key, publishable key, JSON Web Tokens, and public signature key.

  • Secret API key: Use to make requests from the server side. Never share these keys. Keep them guarded and secure.
  • Publishable API key: Use in your client-side code to tokenize payment information.
  • JWT: Use to make short-life tokens that expire after a set period of time.

JWT

JWT is a short lifetime token that can be assigned a specific expiration time.

Usage format: Bearer <JWT>.

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "JWT"

ApplicationJWT

Applications in the Rebilly App Store can create a JSON Web Token (JWT) by fetching an user's instance. For more information, see Retrieve an application instance.

Usage format: Bearer <JWT>.

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "JWT"

PublishableApiKey

This authentication method is applicable to specific operations.

To create a publishable API key, see Create an API key.

Security Scheme Type: API Key
Header parameter name: Authorization

SecretApiKey

Never share your secret keys. Keep them guarded and secure.

Use your secret API key only to make requests from the server side. To authenticate, provide your secret key in the request header.

Security Scheme Type: API Key
Header parameter name: REB-APIKEY

CustomerJWT

To create a JSON Web Token (JWT) using Storefront authentication, see Create a session with username and password.

Usage format: Bearer <JWT>.

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "JWT"

Manage API keys

To create or manage API keys, select one of the following:

For more information on API keys, see API keys.

Errors

Rebilly follows the error response format proposed in RFC 7807, which is also known as Problem Details for HTTP APIs. As with any API responses, your client must be prepared to gracefully handle additional members of the response. The following section describes common error types.

Forbidden

Access forbidden.

Response Schema: application/json
non-empty
status
integer [ 403 .. 403 ]

HTTP status code.

type
string <uri>

Problem type in the form of a URI reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".

title
string

Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

detail
string

Human-readable explanation that is specific to this occurrence of the problem.

instance
string

URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

property name*
additional property
any
application/json
{
  • "status": 403,
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Conflict

Conflict.

Response Schema: application/json
non-empty
status
integer [ 409 .. 409 ]

HTTP status code.

type
string <uri>

Problem type in the form of a URI reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".

title
string

Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

detail
string

Human-readable explanation that is specific to this occurrence of the problem.

instance
string

URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

property name*
additional property
any
application/json
{
  • "status": 409,
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

NotFound

Resource not found.

Response Schema: application/json
non-empty
status
integer [ 404 .. 404 ]

HTTP status code.

type
string <uri>

Problem type in the form of a URI reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".

title
string

Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

detail
string

Human-readable explanation that is specific to this occurrence of the problem.

instance
string

URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

property name*
additional property
any
application/json
{
  • "status": 404,
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Unauthorized

Unauthorized access. Invalid credentials used.

Response Schema: application/json
non-empty
status
integer [ 401 .. 401 ]

HTTP status code.

type
string <uri>

Problem type in the form of a URI reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".

title
string

Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

detail
string

Human-readable explanation that is specific to this occurrence of the problem.

instance
string

URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

property name*
additional property
any
application/json
{
  • "status": 401,
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

ValidationError

Invalid data sent.

Response Schema: application/json
non-empty
status
integer [ 422 .. 422 ]

HTTP status code.

type
string <uri>

Problem type in the form of a URI reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".

title
string

Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

detail
string

Human-readable explanation that is specific to this occurrence of the problem.

instance
string

URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Array of objects

Invalid field details.

Array
field
string

Name of the field. Dot notation is used for nested object field names.

message
string

Message field.

property name*
additional property
any
application/json
{
  • "status": 422,
  • "title": "string",
  • "detail": "string",
  • "instance": "string",
  • "invalidFields": [
    ]
}

SDKs

Rebilly provides a JavaScript SDK and a PHP SDK to help interact with the Rebilly API. However, no SDK is required to use the API.

Rebilly also provides FramePay, a client-side iFrame-based solution, to help create payment tokens while minimizing PCI DSS compliance burdens and maximizing your customization ability. FramePay interacts with the payment tokens creation operation.

JavaScript SDK

For installation and usage instructions, see SDKs. All JavaScript SDK code examples are included in the API reference documentation.

PHP SDK

For installation and usage instructions, see SDKs. All SDK code examples are included in the API reference documentation. To use them, you must configure the $client as follows:

$client = new Rebilly\Client([
    'apiKey' => 'YourApiKeyHere',
    'baseUrl' => 'https://api.rebilly.com',
]);

Using filter with collections

Rebilly provides collections filtering. Use the ?filter parameter on collections to define which records should be shown in the response.

Format description:

  • Fields and values in the filter are separated with :: ?filter=firstName:John.

  • Sub-fields are separated with .: ?filter=billingAddress.country:US.

  • Multiple filters are separated with ;: ?filter=firstName:John;lastName:Doe.
    They are joined with AND logic. Example: firstName:John AND lastName:Doe.

  • To use multiple values, use , as values separators: ?filter=firstName:John,Bob.
    Multiple values specified for a field are joined with OR logic. Example: firstName:John OR firstName:Bob.

  • To negate the filter, use !: ?filter=firstName:!John.

  • To negate multiple values, use: ?filter=firstName:!John,!Bob. This filter rule excludes all Johns and Bobs from the response.

  • To use range filters, use: ?filter=amount:1..10.

  • To use a gte (greater than or equals) filter, use: ?filter=amount:1... This also works for datetime-based fields.

  • To use a lte (less than or equals) filter, use: ?filter=amount:..10. This also works for datetime-based fields.

  • To create specified values lists and use them in filters, use: ?filter=firstName:@yourListName.
    You can also exclude list values: ?filter=firstName:!@yourListName.
    Use value lists to compare against a list of data when setting conditions for rules or binds, or applying filters to data table segments. Commonly used lists contain values related to conditions that target specific properties such as: customers, transactions, or BINs.

  • Datetime-based fields accept values formatted using RFC 3339. Example: ?filter=createdTime:2021-02-14T13:30:00Z.

Expand to include embedded objects

Rebilly provides the ability to pre-load additional objects with a request.

You can use the ?expand parameter on most requests to expand and include embedded objects within the _embedded property of the response. The _embedded property contains an array of objects keyed by the expand parameter values. To expand multiple objects, pass them as a comma-separated list of objects.

Example request containing multiple objects:

?expand=recentInvoice,customer

Example response:

"_embedded": [
    "recentInvoice": {...},
    "customer": {...}
]

Expand may be used on GET, PATCH, POST, PUT requests.

Limit on collections offset

For performance reasons, take note that we have a 1000 limit on ?offset=.... For example, attempting to retrieve a collection using ?offset=1001 or ?offset=2000 returns the same results as if you used ?offset=1000.

Visit our Data Exports API for an asynchronous solution.

Get started

The full Rebilly API has over 500 operations. This is likely more than you may need to implement your use cases. If you would like to implement a particular use case, contact Rebilly for guidance and feedback on the best API operations to use for the task.

To integrate Rebilly, and learn about related resources and concepts, see Get started.