Requests and responses

Every endpoint follows the same conventions. Learn them once and each endpoint behaves as you expect.

Versioning

The version is in the path: /api/v1. Adding a field or an endpoint is not a breaking change and does not create a new version. A breaking change ships as /v2.

Write your client to ignore response fields it doesn’t recognise. New fields will appear in v1 responses over time.

Data formats

Type	Format	Example
Keys	`snake_case`	`invoice_reference`
Object type	Every object has an `object` field naming its type.	`"object": "subscription"`
Ids	Opaque strings. Store them as strings and don’t parse them.	`"9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33"`
Money	A decimal string with four decimal places. Never a number.	`"19.9900"`
Percentages	A decimal string with two decimal places.	`"10.00"`
Timestamps	ISO 8601, in UTC.	`"2026-09-30T04:12:00.000Z"`
Calendar dates	`YYYY-MM-DD`, in the subscription’s own timezone.	`"2026-10-30"`
Enumerations	Lower case.	`"awaiting_approval"`
Empty values	`null`. Fields are present even when empty.	`"end_date": null`

Parse money as a decimal type, not a floating-point number. "19.9900" is exact. 19.99 may not be.

Sending money and percentages

Fields that take an amount accept a decimal string or a number, with at most two decimal places. Prefer a string.

{ "flat_fee_price": "2400.00", "discount_percent": "10" }

Sending dates

Dates are YYYY-MM-DD, read in the organisation’s timezone. If you omit start_date when creating a subscription, it defaults to today in that timezone. Retrieve the timezone from the organisation.

Request bodies

Send JSON with Content-Type: application/json. Bodies can be up to 100,000 characters. The API rejects fields it doesn’t know. A misspelt discount_precent would otherwise be ignored, and the subscription would be created with no discount. The error names the field.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "`discount_precent` is not a field this endpoint accepts.",
    "param": "discount_precent",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

Response headers

Every response includes these headers.

Header	Description
`Request-Id`	A unique id for the request, such as `req_4f1a9c2e7b8d3a605e1c9f02`. The same id appears in error bodies and in the request log. Quote it when you contact support.
`RateLimit-Limit`	Requests allowed per minute for this key. See Rate limits.
`RateLimit-Remaining`	Requests left in the current window.
`RateLimit-Reset`	Seconds until the oldest counted request stops counting.
`Idempotent-Replayed`	`true` when the response is a stored answer to a repeated request. See Idempotency.
`Retry-After`	Seconds to wait before trying again. Sent with `429` and with `409 request_in_progress`.

Responses are never cached: they carry Cache-Control: no-store.

Request log

Saasybill keeps a log of every authenticated request for 30 days. Find it under Developer Settings, then Logs. Each entry records the key, method, path, status, duration, request id and idempotency key. The log never holds request or response bodies, because they carry customer data. It also records the path only, without the query string, which can carry a customer’s email address.

Where to next

Pagination

Page through lists.

Errors

Handle failures.

Idempotency

Retry writes safely.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Versioning

Data formats

Sending money and percentages

Sending dates

Request bodies

Response headers

Request log

Where to next

Pagination

Errors

Idempotency

​Versioning

​Data formats

​Sending money and percentages

​Sending dates

​Request bodies

​Response headers

​Request log

​Where to next

Pagination

Errors

Idempotency

Versioning

Data formats

Sending money and percentages

Sending dates

Request bodies

Response headers

Request log

Where to next