Endpoints

Everything the App API exposes today.

The App API is how your app reads the merchant's data. Version 1 is read-only — every endpoint is a GET, anything else returns 405 method_not_allowed. Write capabilities are granted case by case after review.

Base URL: https://api.spuke.com/v1/app · Auth: Authorization: Bearer spk_at_live_… (see Authentication).

Endpoints

Method Path Scope What it gives you
GET /v1/merchant merchant:read Profile of the merchant that installed your app: company, country, VAT number, status. Call once after install to label the connection.
GET /v1/payments payments:read Processed payments, newest first. Live traffic supports ?status=succeeded.
GET /v1/payments/{id} payments:read One payment. The {id} is the charge_id in live and the row id in sandbox.
GET /v1/refunds refunds:read Sandbox: refund rows. Live: refunded charges with the running amount_refunded.
GET /v1/disputes disputes:read Chargebacks including evidence_due_by and past_due.
GET /v1/payouts payouts:read Bank settlements. Restricted scope — reconciliation tools only.
GET /v1/balance payouts:read Available and pending balance of the merchant.
GET /v1/products products:read The merchant's catalog (no prices in v1).
GET /v1/products/{id} products:read One product.
GET /v1/invoices invoices:read Issued invoices. Live only — sandbox returns an empty list.
GET /v1/invoices/{id} invoices:read One invoice.
GET /v1/subscriptions subscriptions:read Recurring agreements with status and period end.
GET /v1/analytics/summary analytics:read Aggregated volume for a window: ?days=30 (1–365).

Field-by-field descriptions of every response are in Objects & fields.

Query parameters

Parameter Where Behaviour
limit all list endpoints 1–100, default 25.
offset all list endpoints Row offset, default 0.
status /v1/payments (live) Exact match, e.g. ?status=succeeded.
days /v1/analytics/summary 1–365, default 30.

Unknown query parameters are ignored, not rejected. There are no date-range filters in v1 — page by offset and stop at the first object older than your cursor.

Pagination

curl "https://api.spuke.com/v1/app/v1/payments?limit=50&offset=100" \
  -H "Authorization: Bearer spk_at_live_…"

{ "object": "list", "data": [ … ], "has_more": true }

Lists are sorted newest first and carry no total count. Iterate until has_more is false. New objects arrive while you page, so for exports read the first page frequently rather than deep-paging a moving list.

Test vs live

The token decides the data source: a sandbox token reads your environment's simulated data, a live token reads the merchant's real data. Field names differ between the two — see the table at the top of Objects & fields.

Amounts and timestamps

Amounts are integer minor units with a lowercase ISO currency: { "amount": 2500, "currency": "eur" } is €25.00. Never use floats. Timestamps are ISO-8601 UTC; arrival_date, issue_date and due_date are dates without a time part.

Errors

{ "error": { "type": "insufficient_scope", "message": "Missing required scope: payments:read" } }

See Error & status codes.