API Overview

Base URL#

All API endpoints are prefixed with /api/v1/. Requests must be made over HTTPS. The full base URL for a Commerce installation at billing.example.com would be:

https://billing.example.com/api/v1/

Authentication#

The API uses Bearer token authentication. Every request must include an Authorization header:

Authorization: Bearer {your-token}

Tokens are generated in the client portal under Profile → API Tokens. See API Authentication & Tokens for full details.

Request Format#

The API accepts standard HTTP requests. Most endpoints are read-only and use GET. No request body is required for GET endpoints.

For any endpoints that accept a body (future write operations), send JSON with the Content-Type: application/json header.

Response Format#

All responses return JSON. Successful list responses follow this structure:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 15,
    "total": 52
  }
}

Single-resource responses return a data object directly:

{
  "data": {
    "id": 1,
    "name": "Jane Smith",
    ...
  }
}

Pagination#

List endpoints support page and per_page query parameters.

Example: GET /api/v1/services?page=2&per_page=25

The meta block in the response contains total (total record count) and last_page (total pages).

Error Responses#

Error responses use standard HTTP status codes and always include a message key. Validation errors also include an errors object:

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["The selected status is invalid."]
  }
}

Rate Limiting#

The API enforces rate limits per token. When exceeded, the server returns 429 Too Many Requests. The response includes a Retry-After header indicating how many seconds to wait.

[!TIP] If you're building an integration that syncs data, cache responses locally and only fetch when needed. Most Commerce data does not change frequently.

HTTP Methods#

The current API version is read-only for most resources. Only GET is used unless noted otherwise.

[!IMPORTANT] Placing orders, submitting payments, or managing domains via the API is not supported in the current version. These actions must be performed through the client portal.

Versioning#

The current API version is v1. Future breaking changes will be released under a new version prefix (e.g., /api/v2/). The v1 endpoints will remain available during any transition period, with advance notice of deprecation.