Introduction

The Billingrails API is REST-based. Request and response bodies use a consistent structure: create and update requests send the fields you want to set, and responses wrap resources in a named key with optional metadata for lists.

Requests

To create a resource, send a POST request with a JSON body containing the resource fields. The resource type is determined by the endpoint; the server assigns the ID.

Creating a resource

Send a POST request with the attributes for the new resource:

// POST /v1/accounts
{
  "name": "John Doe",
  "email": "john.doe@example.com"
}

Updating a resource

To update a resource, send a PUT request with only the fields you want to change. Omitted fields remain unchanged.

// PUT /v1/accounts/{id}
{
  "invoice_settings": {
    "grace_period_days": 10,
    "net_term_days": 45,
    "number_prefix": "BILL"
  }
}

Responses

Single-resource responses wrap the resource in a key matching the resource type (e.g. account, subscription, invoice). List responses use a plural key (e.g. accounts, subscriptions) and include a meta object for pagination.

Single resource

Responses for a single resource wrap the resource in a key named after the resource type (e.g. account, subscription):

{
  "account": {
    "object": "account",
    "id": "acc_IhMUl3rrZ3",
    "type": "individual",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "created_at": "2025-02-14T17:33:40.843Z"
  },
  "meta": {
    "request_id": "req_IhMUl3rrZ3"
  }
}

List of resources

List endpoints return an array of resources under a plural key, with pagination metadata in meta:

{
  "accounts": [
    {
      "object": "account",
      "id": "acc_IhMUl3rrZ3",
      "type": "individual",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "created_at": "2025-02-14T17:33:40.843Z"
    }
  ],
  "meta": {
    "request_id": "req_IhMUl3rrZ3",
    "current_page": 1,
    "per_page": 20,
    "total_count": 100
  }
}

Use the page and per_page query parameters to paginate. See Pagination for details.

Glossary

• Resource — An entity in the Billingrails API, such as an account, invoice, subscription, or payment.
• Attribute — A field on a resource (e.g. status, amount, created_at).
• Meta — Response metadata such as request_id and, for lists, current_page, per_page, and total_count.

Next steps

• Authentication — Bearer authentication and API key security
• Rate limits — Request limits and handling 429 responses
• Pagination — Paginated list responses
• Error handling — Error response format

For complete request and response schemas for every endpoint, see the resource pages in this API reference (Accounts, Invoices, Payments, and others); they are generated from the OpenAPI specification.