App API

Authentication

Bearer tokens, modes and installation context.

Base URL:

https://api.spuke.com/v1/app

Every request carries an installation access token:

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

The token identifies the app and the merchant. There is no merchant id parameter — you cannot address a merchant that has not installed you.

Getting a token

Tokens come from the OAuth flow at install time (authorization_code, PKCE supported) and are renewed with the refresh_token grant. See Installs & OAuth.

Because refresh tokens rotate, refreshing twice with the same token invalidates the installation's tokens — serialise your refresh calls.

Failure modes

Error bodies are uniform:

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

Server-side only

The client secret and refresh tokens must never reach a browser or a mobile binary. Public clients use PKCE and keep only the short-lived access token.

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

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

Query parameters

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.

Objects & fields

The shape of every resource you can read.

This page describes the actual JSON the App API returns, field by field.

One thing to internalise first: the API serves two different data sources depending on the token.

Both are documented below. Write your parser against both, or gate features by livemode.

Global rules

Merchant — GET /v1/merchant

Who installed your app.

{ "object": "merchant", "id": "…", "business_name": "Ada GmbH", "email": "ops@ada.de",
  "country": "DE", "city": "Berlin", "vat_number": "DE123456789", "reference": "M-10423",
  "status": "approved", "plan_id": "…", "livemode": true, "created_at": "2026-05-02T08:00:00Z" }

Payment — GET /v1/payments, /v1/payments/{id}

One processed payment. In sandbox the row is a simulated checkout session; in live it is the real charge.

Live

{ "object": "payment", "livemode": true, "charge_id": "ch_3Nk91x", "payment_intent_id": "pi_3Nk91x",
  "amount": 2500, "amount_refunded": 0, "currency": "eur", "status": "succeeded", "refunded": false,
  "customer_email": "ada@example.com", "customer_name": "Ada Lovelace", "description": "Order #1042",
  "payment_method_type": "card", "card_brand": "visa", "card_last4": "4242", "card_country": "DE",
  "receipt_url": "https://…", "failure_code": null, "failure_message": null,
  "charge_created_at": "2026-08-17T09:41:12Z" }

Sandbox

{ "object": "payment", "livemode": false, "id": "…uuid", "amount_cents": 2500,
  "amount_refunded_cents": 0, "fee_cents": 74, "net_cents": 2426, "currency": "eur",
  "status": "completed", "customer_email": "test@spuke.test", "customer_name": "Test Buyer",
  "description": "Order #1", "payment_method_type": "card", "card_brand": "visa", "card_last4": "4242",
  "failure_code": null, "failure_message": null, "disputed": false,
  "payment_intent_id": "pi_test_…", "charge_id": "ch_test_…", "created_at": "2026-08-17T09:41:12Z" }

Filter live payments with ?status=succeeded.

Refund — GET /v1/refunds

Sandbox returns real refund rows:

{ "id": "…uuid", "amount_cents": 500, "currency": "eur", "status": "succeeded",
  "reason": "requested_by_customer", "charge_id": "ch_test_…", "payment_intent_id": "pi_test_…",
  "created_at": "2026-08-18T07:02:10Z" }

Live returns the refunded charges (one row per charge, not per refund):

{ "charge_id": "ch_3Nk91x", "amount_refunded": 500, "currency": "eur",
  "refunded": false, "updated_at": "2026-08-18T07:02:10Z" }

refunded: false with a non-zero amount_refunded means a partial refund. amount_refunded is the authoritative running total for that payment.

Dispute — GET /v1/disputes

A chargeback: the disputed amount is held and there is a hard deadline.

Live

{ "dispute_id": "dp_7c", "charge_id": "ch_3Nk91x", "amount": 2500, "currency": "eur",
  "status": "needs_response", "reason": "fraudulent", "evidence_due_by": "2026-08-31T23:59:59Z",
  "has_evidence": false, "past_due": false, "dispute_created_at": "2026-08-19T11:15:00Z" }

Sandbox adds id, session_id, amount_cents, fee_cents, evidence_submitted_at, closed_at, created_at.

Payout — GET /v1/payouts

A transfer of the merchant's balance to their bank. It bundles many payments — never 1:1 with a payment. Requires the restricted payouts:read scope.

{ "payout_id": "po_44", "amount": 128400, "currency": "eur", "status": "paid",
  "method": "standard", "arrival_date": "2026-08-21",
  "destination_bank_name": "Commerzbank", "destination_last4": "4021",
  "payout_created_at": "2026-08-19T02:00:00Z" }

Sandbox rows use id, amount_cents, created_at plus failure_code / failure_message.

Balance — GET /v1/balance

Money currently held for the merchant. Same scope as payouts.

{ "object": "balance", "livemode": false,
  "available": [{ "amount": 240000, "currency": "eur" }],
  "pending":   [{ "amount":  35000, "currency": "eur" }] }

Live balances are served as empty arrays unless the installation has settlement access.

Product — GET /v1/products, /v1/products/{id}

{ "object": "product", "id": "…uuid", "name": "Pro plan", "description": "…", "active": true,
  "images": ["https://…"], "tags": ["saas"], "unit_label": "seat", "url": "https://…",
  "created_at": "…", "updated_at": "…" }

Prices are not embedded — they belong to the merchant's price list and are not exposed in v1.

Invoice — GET /v1/invoices, /v1/invoices/{id}

Live only; sandbox returns an empty list.

{ "object": "invoice", "id": "…uuid", "invoice_number": "2026-0301", "status": "paid",
  "currency": "eur", "subtotal_amount": 1900, "tax_amount": 361, "total_amount": 2261,
  "customer_name": "Ada GmbH", "customer_email": "ops@ada.de", "customer_type": "business",
  "issue_date": "2026-08-01", "due_date": "2026-09-01", "paid_at": "2026-08-04T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z" }

Subscription — GET /v1/subscriptions

{ "id": "…uuid", "status": "active", "currency": "eur", "amount_minor": 1900, "quantity": 1,
  "customer_email": "ada@example.com", "customer_name": "Ada Lovelace",
  "current_period_start": "2026-08-17T09:41:12Z", "current_period_end": "2026-09-17T09:41:12Z",
  "cancel_at_period_end": false, "created_at": "2026-05-02T08:00:00Z" }

Analytics summary — GET /v1/analytics/summary?days=30

Pre-aggregated volume; far cheaper than paging every payment. days is clamped to 1–365 (default 30).

{ "object": "analytics_summary", "livemode": true, "period_days": 30, "payment_count": 512,
  "gross_amount": 1284000, "refunded_amount": 21500, "net_amount": 1262500, "currency": "eur" }

Aggregation reads at most the 1 000 most recent payments of the window.

List envelope

Every list endpoint wraps results the same way:

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

Error envelope

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

Rate limits & errors

Four enforcement levels, and how to stay under them.

Limits are enforced hierarchically — burst, then installation, then app, then platform. Test and live traffic are counted separately, so sandbox load can never eat live quota.

Per-installation quotas

App-wide ceilings

Across all installations of one app: 3 000 req/min in test, 30 000 req/min in live. A generous platform ceiling sits above that as an emergency brake.

Headers

Every response carries:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 583
X-RateLimit-Reset: 27
Retry-After: 27      # only on 429

Handling 429

async function call(url, token, attempt = 0) {
  const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
  if (res.status === 429 && attempt < 5) {
    const wait = Number(res.headers.get("Retry-After") ?? 1) * 1000;
    await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
    return call(url, token, attempt + 1);
  }
  return res;
}

Add jitter, cap retries, and never retry a 403.

Staying efficient

• React to webhooks instead of polling.
• Cache /v1/merchant; it changes rarely.
• Use time-window filters for backfills, and run them off-peak.
• When usage crosses 80 % of an app quota we notify you before throttling bites.