Skip to main content
Every endpoint follows the same rules. Learn them once and the whole API is predictable.

​
Authentication

Send Authorization: Bearer sk_test_... (test) or sk_live_... (live) on every /v1 request; anything else is 401 auth.unauthorized. A revoked key is 401 auth.key_revoked. Manage keys via API keys.

​
Test vs live

The key’s prefix decides the mode, and the mode scopes all data: a sk_test_ key never sees live resources and vice-versa. Every resource carries livemode. Test mode uses the simulated stamping service and tolerates the sample CSD; see Testing.

​
Money and time

Money is always a decimal string ("116.00") — never a float — so cents never drift. Amounts are computed and rounded half-up at the currency’s decimal places. Times are ISO-8601 UTC (2026-07-10T18:25:43Z). Ids are prefixed, time-ordered, base32 ULID-style: org_, key_, fp_, inv_, dl_, we_, evt_, whd_, req_.

​
Pagination

List endpoints take ?limit= (1–100, default 20) plus one cursor:
  • ?starting_after=<id> — the next (older) page
  • ?ending_before=<id> — the previous (newer) page
Sending both is 422 request.invalid_pagination. Responses are newest-first:

​
Idempotency

Send Idempotency-Key: <unique> on any POST. The first response is stored for 24h and replayed byte-for-byte for identical retries (replays add idempotent-replayed: true). A different body under the same key is 409 idempotency.key_reuse; an in-flight duplicate is 409 idempotency.key_processing. This makes retrying a 502 safe — no duplicate stamp.

​
Metadata

Fiscal profiles, invoices, webhook endpoints, and connected accounts accept a metadata object of string→string (≤50 keys, key ≤40 chars, value ≤500). It round-trips untouched and always appears (default {}). On PATCH, metadata is merged: send a key to set it, or a key with an empty-string value to delete it.

​
Expand

Where documented, ?expand=<field> inlines a related resource. Invoices support ?expand=fiscal_profile. An unsupported value is 422 request.invalid_expand.

​
Versioning

Pin a dated release with the Invoice-Version: 2026-07-15 header (Stripe-style). Omit it to use the current version. An unknown value is 400 request.invalid_version. A key may also carry a pinned version. Precedence: request header → key pin → current. The resolved version is echoed on every response’s Invoice-Version header. Versioning is real, not cosmetic — each dated version pins a response shape, so an old integration keeps exactly the contract it was built against. Discover every version at GET /v1/versions (public, no auth) and read the diff in the Changelog. A version scheduled for removal is served with RFC 8594 Deprecation: true and a Sunset HTTP-date on every response.

​
Rate limits

A token-bucket limiter admits a steady rate with a burst. Authed responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A throttled request is 429 rate_limit.exceeded with a Retry-After header — back off and retry.

​
Request-Id

Every response carries a Request-Id header; it is also the request_id in every error body.
Log the Request-Id. Support and idempotency both key off it.

​
Usage

Every metered action is recorded on a read-only stream. GET /v1/usage returns cursor-paginated usage_record objects for the acting org + mode — the Stripe usage-record analog. Today a fresh CFDI stamp emits one record (kind: "stamp", quantity: 1, resource_id the inv_…); idempotent replays and duplicate re-stamps never double-count. Filter with ?kind=, ?date_from=, and ?date_to= (inclusive bounds on created_at).

​
Errors

Errors are application/problem+json (RFC 9457) with a stable code, a human- and agent-readable remediation, an optional pac object, request_id, and a doc_url deep-link. Switch on code, show remediation. The full catalog lives in the Error reference.