API reference overview

All API calls are HTTPS. The base URL for every partner API endpoint is:

https://pos-api.{env}.apps.myfinterra.com

The full OpenAPI 3.1 spec is available machine-readable at:

GET /pos/v1/.well-known/openapi.json

Request conventions

Content-Type: application/json on all write requests
Authorization: Bearer <access_token> on all requests
Dates: ISO 8601 UTC strings (2024-01-15T10:30:00Z)
Monetary amounts: integer cents (e.g. 5000 = $50.00) — never floating point

Response conventions

Success responses return 200 OK (reads) or 201 Created (writes) with a JSON body.

Errors return a structured envelope:

{
  "error": "order_not_found",
  "message": "No order with that ID exists in your partner scope.",
  "request_id": "req_01j2…"
}

Always log request_id — it maps to our CloudWatch traces and makes support faster.

Pagination

List endpoints accept limit (default 50, max 200) and offset parameters:

GET /pos/v1/locations?limit=20&offset=0

Response:

{
  "items": [...],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Idempotency

POST /pos/v1/orders accepts an optional Idempotency-Key header (UUID). Sending the same key within 24 hours returns the original response without creating a duplicate order. Use this on retries after network errors.

Rate limits

All M2M clients are subject to per-client rate limits based on the tier assigned in the admin portal:

Tier	Burst	Sustained
`low`	10 req/s	5 req/s
`standard`	50 req/s	20 req/s
`high`	200 req/s	100 req/s
`enterprise`	Custom	Custom

When a limit is exceeded the API returns 429 Too Many Requests. The response includes Retry-After (seconds).