Automatic Billing API
Hey dev, have fun! ✨
Documentation index — fetch the full index at https://docs.billing.kobana.com.br/llms.txt. Use this file to discover every available page before exploring further.
Mind the API versions — you are reading the v1.0 documentation of the Automatic Billing API, which covers the Subscriptions endpoints (create, plan change, pause, cancel, manual invoicing, item sync) and related resources. Resources like Payments, Transfers, Statements and Pix Receivables live in other Kobana APIs — use the product picker in the top menu to switch.
Format
The API only accepts JSON. Every request must use Content-Type: application/json. All responses use snake_case.
| Field type | Format |
|---|---|
| DateTime | ISO8601 format. Examples — Date: 2026-01-24. Date and time: 2026-01-24T10:07Z |
| Money | Decimal number in BRL, with up to 4 decimal places. E.g.: 100.5 = R$ 100.50 |
| UUID | Resource identifiers as UUID v4 |
Conventions
Conventions used in this documentation:
| Convention | Description |
|---|---|
:variable | A variable name that must be replaced in the URL. |
#{variable} | A variable name that must be replaced with values from your account. |
... | Response content truncated for readability. |
$KOBANA_TOKEN | Access token. For command-line testing, export it: export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx then paste the docs commands into your terminal. |
Return Codes
The API returns standard HTTP status codes:
| Code | Description | |
|---|---|---|
| ✅ | 200 OK | Successful request with a response body. |
| ✅ | 201 Created | Resource created successfully. |
| ✅ | 204 No Content | Successful request without a response body. |
| ❌ | 400 Bad Request | Invalid request, usually malformed content. |
| ❌ | 401 Unauthorized | Missing or invalid access token. |
| ❌ | 403 Forbidden | API access blocked or user not authorized. |
| ❌ | 404 Not Found | Resource not found. |
| ❌ | 422 Unprocessable Entity | Valid request, but the data is not. |
| ❌ | 429 Too Many Requests | Rate limit reached. |
| ❌ | 500 Internal Server Error | Internal processing error. Check server status. |
Request ID
Every request has an associated identifier in the Request-Id response header. This value helps with debugging and auditing — requests and their IDs are available in the system dashboard. Request logs are retained for 30 days. When opening a support ticket about a specific request, provide the Request-Id to speed up the investigation.
Security
The Kobana API uses 2048-bit SSL certificates. Every request must use HTTPS — calls on port 80 are redirected to 443.
Clients must support TLSv1.2 or TLSv1.3 with one of the ciphers: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305, ECDHE-RSA-AES256-SHA384. TLSv1 and TLSv1.1 are not supported.
HTTP Caching
Use HTTP cache headers to reduce load and improve speed. Most responses include ETag and/or Last-Modified — store these values and send them back on follow-up requests via If-None-Match and If-Modified-Since. If the resource hasn't changed you'll get 304 Not Modified — no body, no reprocessing. More info: HTTP Cache Docs.
Error Handling
5xx errors mean a server failure: 500 Internal Server Error (application unavailable), 502 Bad Gateway, 503 Service Unavailable and 504 Gateway Timeout (point-in-time infrastructure failures). Your application must catch these and retry the request after a few minutes with backoff. Server status: https://status.kobana.com.br.
Monetary values
Every monetary value — in requests and responses — is a decimal number in BRL, with up to 4 decimal places. There are no cent-based fields: send 100.5 for R$ 100.50 and 0.0125 for R$ 0.0125. Pricing fields keep all 4 decimals; the others are rounded to 2.