Extract of Rebilly REST API (2.1)

Download OpenAPI specification:Download

Introduction

The Rebilly API is built on HTTP. Our API is RESTful. It has predictable resource URLs. If you have a HATEOAS client, it may be useful that it has hyperlinks to related resources. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can use your favorite HTTP/REST library for your programming language to use Rebilly's API, or you can use one of our SDKs (currently available in PHP and Javascript.

We have other APIs that are also available. Every action from our app is supported by an API which is documented and available for use so that you may automate any workflows necessary. This document contains the most commonly integrated resources.

Authentication

When you sign up for an account, you are given your first API key. You can generate additional API keys, and delete API keys (as you may need to rotate your keys in the future). You authenticate to the Rebilly API by providing your secret key in the request header.

Rebilly offers three forms of authentication: private key, JSON Web Tokens, and public key.

  • private key: authenticates each request by searching for the presence of an HTTP header: REB-APIKEY.
  • JWT: authenticates each request by the HTTP header: Authorization.
  • public key: authenticates by the HTTP header: REB-AUTH (read more on this below).

Rebilly also offers JSON Web Tokens (JWT) authentication, where you can control the specific granular permissions and expiration for that JWT. We call our resource for generating JWT Sessions.

Rebilly also has a client-side authentication scheme that uses an apiUser and HMAC-SHA1 signature (only for the Tokens resource), so that you may safely create tokens from the client-side without compromising your secret keys.

Never share your secret keys. Keep them guarded and secure. The client-side authentication scheme uses one HTTP header named REB-AUTH.

ApiKey

When you sign up for an account, you are given your first API key. To do so please follow this link. Also you can generate additional API keys, and delete API keys (as you may need to rotate your keys in the future).

Security scheme type: API Key
header parameter name: REB-APIKEY

JWT

You can create a JSON Web Token (JWT) via our Sessions resource.

Security scheme type: HTTP
HTTP Authorization Scheme basic

PHP SDK

For all PHP SDK examples provided in this spec you will need to configure $client. You may do it like this:

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

Data Exports

A data export is a request that results in a file creation which has a header row and contents of the data requested to be exported.

Request a data export of selected resource

Request a data export of selected resource

Authorizations:
Request Body schema: application/json
name
required
string

Export name

resource
required
string
Value:"transactions"

The type of resource being exported (eg., transactions).

format
required
string
Enum:"csv" "json" "xml"

Export result format

arguments
object

Export request arguments that can be passed to filter and/or sort the result set

dateRange
object

The date range (can be in relative formats). If omitted, all time will be included.

emailNotification
Array of string <email>

List of emails to be notified when export is completed

fields
Array of string

List of fields to include in the export. See supporting documentation for more info. If omitted, default fields will be included.

recurring
object

Exports can reoccur according to your own schedule

Responses

201

Data export request received

401

Access forbidden, invalid API-KEY was used

post /experimental/data-exports
Live Server
null//api.rebilly.com/experimental/data-exports
Sandbox Server
null//api-sandbox.rebilly.com/experimental/data-exports

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "resource": "transactions",
  • "format": "csv",
  • "arguments":
    {
    },
  • "dateRange":
    {
    },
  • "emailNotification":
    [
    ],
  • "fields":
    [
    ],
  • "recurring":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "resource": "transactions",
  • "format": "csv",
  • "arguments":
    {
    },
  • "dateRange":
    {
    },
  • "emailNotification":
    [
    ],
  • "fields":
    [
    ],
  • "recurring":
    {
    },
  • "userId": "string",
  • "recordCount": 0,
  • "scheduledTime": "2019-04-30T18:01:39Z",
  • "createdTime": "2019-04-30T18:01:39Z",
  • "updatedTime": "2019-04-30T18:01:39Z",
  • "status": "pending",
  • "_links":
    [
    ]
}

Retrieve a list of data export requests

Retrieve a list of data export requests

Authorizations:

Responses

200

A list of data export requests was retrieved successfully

401

Access forbidden, invalid API-KEY was used

get /experimental/data-exports
Live Server
null//api.rebilly.com/experimental/data-exports
Sandbox Server
null//api-sandbox.rebilly.com/experimental/data-exports

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Retrieve a data export request

Retrieve a data export request

Authorizations:
path Parameters
id
required
string

The resource identifier string

Responses

200

Data Export request

401

Access forbidden, invalid API-KEY was used

get /experimental/data-exports/{id}
Live Server
null//api.rebilly.com/experimental/data-exports/{id}
Sandbox Server
null//api-sandbox.rebilly.com/experimental/data-exports/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "resource": "transactions",
  • "format": "csv",
  • "arguments":
    {
    },
  • "dateRange":
    {
    },
  • "emailNotification":
    [
    ],
  • "fields":
    [
    ],
  • "recurring":
    {
    },
  • "userId": "string",
  • "recordCount": 0,
  • "scheduledTime": "2019-04-30T18:01:39Z",
  • "createdTime": "2019-04-30T18:01:39Z",
  • "updatedTime": "2019-04-30T18:01:39Z",
  • "status": "pending",
  • "_links":
    [
    ]
}

Files

A File is an entity that can store a phyiscal file and some metadata. It also provides an easy access to its size, mime-type, user-defined tags and description thus allowing easy sorting and searching among stored files. There are several methods of file uploading available: multipart/form-data encoded form, RAW POST (by sending file contents as POST body), fetching from URL (by providing the file URL via 'url' param) Attachment is an entity that is used to link a File to one or multiple objects like Customer, Dispute, Payment, Transaction, Subscription, Plan, Product, Invoice, Note. That allows to quickly find and use files related to those specific entities.

Retrieve a list of files

Retrieve a list of files

Authorizations:
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit

offset
integer >= 0

The collection items offset

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

expand
string

Expand response to get full related object intead of ID. See the expand guide for more info.

fields
string

Limit the returned fields to the list specified, separated by comma. Note that id is always returned.

sort
Array of string
Items Enum:"id" "-id" "name" "-name" "extension" "-extension" "size" "-size" "width" "-width" "height" "-height" "createdTime" "-createdTime" "updatedTime" "-updatedTime"

The collection items sort field and order (prefix with "-" for descending sort).

Responses

200

A list of Files was retrieved successfully

401

Access forbidden, invalid API-KEY was used

get /v2.1/files
Live Server
null//api.rebilly.com/v2.1/files
Sandbox Server
null//api-sandbox.rebilly.com/v2.1/files

Request samples

Copy
$files = $client->files()->search([
    'filter' => 'name:TestFile',
]);

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create a file

Create a file

Authorizations:
Request Body schema: application/json
url
string

The file URL

Responses

201

File was created

401

Access forbidden, invalid API-KEY was used

422

Invalid data was sent

post /v2.1/files
Live Server
null//api.rebilly.com/v2.1/files
Sandbox Server
null//api-sandbox.rebilly.com/v2.1/files

Request samples

application/json
Copy
Expand all Collapse all
{
  • "url": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "url": "string",
  • "tags":
    [
    ],
  • "mime": "image/png",
  • "size": 0,
  • "width": 0,
  • "height": 0,
  • "sha1": "string",
  • "createdTime": "2019-04-30T18:01:39Z",
  • "updatedTime": "2019-04-30T18:01:39Z",
  • "isPublic": true,
  • "_links":
    [
    ]
}

Retrieve a File Record

Retrieve a File with specified identifier string

Authorizations:
path Parameters
id
required
string

The resource identifier string

Responses

200

File was retrieved successfully

401

Access forbidden, invalid API-KEY was used

404

Resource was not found

get /v2.1/files/{id}
Live Server
null//api.rebilly.com/v2.1/files/{id}
Sandbox Server
null//api-sandbox.rebilly.com/v2.1/files/{id}

Request samples

Copy
$file = $client->files()->load('fileId');

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "url": "string",
  • "tags":
    [
    ],
  • "mime": "image/png",
  • "size": 0,
  • "width": 0,
  • "height": 0,
  • "sha1": "string",
  • "createdTime": "2019-04-30T18:01:39Z",
  • "updatedTime": "2019-04-30T18:01:39Z",
  • "isPublic": true,
  • "_links":
    [
    ]
}

Update the File with predefined ID. Note that file can be uploaded with POST only.

Update the File with predefined ID

Authorizations:
path Parameters
id
required
string

The resource identifier string

Request Body schema: application/json
name
string

Original File name

extension
string

The File extension

description
string

The File description

url
string

Write-only. If defined on POST, this would be used as a file source.

tags
Array of string

The tags list

isPublic
boolean

Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL.

Responses

200

File was updated

401

Access forbidden, invalid API-KEY was used

404

Resource was not found

422

Invalid data was sent

put /v2.1/files/{id}
Live Server
null//api.rebilly.com/v2.1/files/{id}
Sandbox Server
null//api-sandbox.rebilly.com/v2.1/files/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "url": "string",
  • "tags":
    [
    ],
  • "isPublic": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "url": "string",
  • "tags":
    [
    ],
  • "mime": "image/png",
  • "size": 0,
  • "width": 0,
  • "height": 0,
  • "sha1": "string",
  • "createdTime": "2019-04-30T18:01:39Z",
  • "updatedTime": "2019-04-30T18:01:39Z",
  • "isPublic": true,
  • "_links":
    [
    ]
}

Delete a File

Delete the File with predefined identifier string

Authorizations:
path Parameters
id
required
string

The resource identifier string

Responses

204

File was deleted

401

Access forbidden, invalid API-KEY was used

404

Resource was not found

delete /v2.1/files/{id}
Live Server
null//api.rebilly.com/v2.1/files/{id}
Sandbox Server
null//api-sandbox.rebilly.com/v2.1/files/{id}

Request samples

Copy
$client->files()->delete('fileId');

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": 100,
  • "error": "string"
}

Download a file

Download a file

Authorizations:
path Parameters
id
required
string

The resource identifier string

Responses

200

The file was retrieved successfully

302

Resource was moved

401

Access forbidden, invalid API-KEY was used

404

Resource was not found

get /v2.1/files/{id}/download
Live Server
null//api.rebilly.com/v2.1/files/{id}/download
Sandbox Server
null//api-sandbox.rebilly.com/v2.1/files/{id}/download

Response samples

application/json
Copy
Expand all Collapse all
"string"

Download image in specific format

Download image in specific format. Images are converted server-side

Authorizations:
path Parameters
id
required
string

The resource identifier string

extension
required
string
Enum:".png" ".jpg" ".gif"

File extension which also indicates the desired file format

Responses

200

The file was retrieved successfully

401

Access forbidden, invalid API-KEY was used

404

Resource was not found

422

Invalid data was sent

get /v2.1/files/{id}/download{extension}
Live Server
null//api.rebilly.com/v2.1/files/{id}/download{extension}
Sandbox Server
null//api-sandbox.rebilly.com/v2.1/files/{id}/download{extension}

Response samples

application/json
Copy
Expand all Collapse all
"string"