API overview

Base URL and format

https://id.anikeen.com/api/v1/…           production
https://staging.id.anikeen.com/api/v1/…   staging

Requests and responses are JSON. Send Accept: application/json and, with a body, Content-Type: application/json.

Authentication

Every endpoint except a few public ones needs a bearer token:

curl https://id.anikeen.com/api/v1/user \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Token	Endpoints	How to get it
User token (OAuth access token or personal access token)	/api/v1/… for the signed-in user, e.g. /api/v1/orders	authorization code flow
App token (client credentials, trusted apps)	/api/v1/client/… and /api/v1/admin/…	client credentials grant

Public endpoints without a token:

Endpoint
GET /api/v1/countries	the countries addresses can use, with their ISO code (country_iso)
POST /api/v1/orders/preview	calculate an order's totals and VAT, see Orders

Response shapes

Single objects are wrapped in data:

{"data": {"id": "01J…", "status": "draft"}}

Most lists are paginated (?page=2) and carry links and meta:

{
  "data": [{"id": "01J…"}],
  "links": {"first": "…?page=1", "last": "…?page=3", "prev": null, "next": "…?page=2"},
  "meta": {"current_page": 1, "last_page": 3, "per_page": 15, "total": 42}
}

IDs are strings (ULIDs for most objects). Amounts are returned as numbers in most places; newer endpoints (charges, billing limit) return them as strings with fixed decimals, e.g. "9.52". Timestamps are ISO 8601.

Errors

Failed requests answer with an HTTP status and a JSON body with a human-readable message and – on most endpoints – a stable machine-readable error code:

{"message": "The subscription is already cancelled.", "error": "already_cancelled"}

Branch on error, not on message: messages are for people and may change. Some errors carry more fields, e.g. net_amount on elapsed_amount_exceeded or remaining on billing_limit_reached.

Status	Meaning
400	malformed request
401	no token, an invalid or expired token (unauthenticated where a code is sent)
402	a payment failed
403	the token may not do this, e.g. missing_scope, client_not_allowed, confirmation_required
404	not found, or not visible to your app
409	a conflict with the current state, e.g. already_active, billing_limit_reached
412	a conditional write failed (preferences)
422	validation failed: errors lists the messages per field
429	rate limited: wait for Retry-After seconds
5xx	a temporary problem on Anikeen ID's side: retry later

Validation errors:

{
  "message": "The name field is required.",
  "errors": {"name": ["The name field is required."]}
}

Some endpoints (the profile API) also send a code per field in codes.

The error codes of each endpoint are listed on its page.

Idempotency

Endpoints that create something billable accept an idempotency_key: a retry with the same key returns the object created first (200 instead of 201) instead of creating a second one. Use one key per thing you create (e.g. cart:42, shipment-123). Reusing a key for different data answers 409 idempotency_key_conflict.

Rate limits

Endpoints are rate limited per app and user. A 429 comes with a Retry-After header; wait that many seconds before retrying. Limits that matter for your design are listed on the endpoint's page.