API overview

The BillingServ API lets your application manage customers, packages, invoices, orders, support tickets, usage, reports, and other supported account resources.

Base URL

Use your BillingServ installation’s v2 API URL:

https://your-billingserv-domain.com/api/v2

API v1 is deprecated. New integrations should use v2.

Authentication

Generate a live API key from the API Information page in the admin panel, then send it as a bearer token:

Authorization: Bearer <live_api_key>
Accept: application/json

The full key is shown once. Store it securely and never expose it in browser code, logs, or a public repository. Regenerating the key invalidates the previous key.

curl "https://your-billingserv-domain.com/api/v2/customer/lists" \
  -H "Authorization: Bearer <live_api_key>" \
  -H "Accept: application/json"

Request and response format

Send JSON for request bodies unless an endpoint documents another format:

Content-Type: application/json

Successful responses contain "success": true. API v2 responses also include X-Request-ID and X-API-Version: 2 headers. Keep the request ID when troubleshooting or contacting support. Errors use the relevant HTTP status and follow this shape. The errors value may be a message, a list, or a field-keyed validation object:

{
  "success": false,
  "errors": {
    "username": [
      "The email address has already been taken."
    ]
  },
  "code": "validation_error",
  "request_id": "694413c5-e398-4477-9592-dce0f81605de"
}

Use code for machine-readable handling and request_id to trace a failed request. The same request ID is returned in the X-Request-ID response header.

Idempotent requests

The following create and update operations accept an optional Idempotency-Key header:

POST /customer/create
POST /invoice/create-quote
POST /invoice/create-invoice
POST /invoice/update-invoice
POST /order/add-order

Use a unique key for each logical operation. Keys may contain letters, numbers, dots, underscores, and hyphens, and must be 1–100 characters long:

Idempotency-Key: order-7f3d9b2c

For a supported operation, repeating the same key with the same request replays the successful response for 24 hours. Reusing a key with a different request returns 409 Conflict. A request already being processed with the same key also returns 409.

Rate limits

Rate limits are configurable for each BillingServ deployment. Read the response headers instead of assuming a fixed limit: | Header | Meaning | |: |: | | X-RateLimit-Limit | Requests allowed in the current window | | X-RateLimit-Remaining | Requests remaining in the current window | When the limit is exceeded, the API returns 429 Too Many Requests. Back off and retry according to your application’s retry policy. | Status | Meaning | |: |: | | 200 | Request completed successfully | | 201 | Resource created successfully | | 401 | API key is missing or invalid | | 403 | The authenticated account cannot use the endpoint | | 404 | The requested resource was not found | | 422 | Request validation failed | | 409 | The request conflicts with an existing idempotency operation | | 429 | Rate limit exceeded | | 500 | Unexpected server error |

Keep your system synchronized

Polling the API is not required for every change. Configure webhooks to receive customer, payment, invoice, order, subscription, credit note, and support events as they happen.

Developer Hub

Getting Started

Webhooks

Endpoints

Base URL

Authentication

Request and response format

Idempotent requests

Rate limits

Keep your system synchronized

​Base URL

​Authentication

​Request and response format

​Idempotent requests

​Rate limits

​Keep your system synchronized

Base URL

Authentication

Request and response format

Idempotent requests

Rate limits

Keep your system synchronized