App API

The App API is the HTTP API your server uses to read and change a store's data, under /apps-api/v1. Every request carries an installation access token from the merchant's grant (see Authentication), and can reach only what the merchant granted to that installation. New to it? Start with Make your first API call.

The production origin of the App API is not published yet, so the examples read it from POLTURA_API.

PolturaClient from @poltura/app-sdk wraps every route: new PolturaClient({ origin, accessToken, timeoutMs?, maximumResponseBytes?, fetch? }). origin is an HTTPS origin with no path. Requests time out after 10 seconds unless you set timeoutMs (up to 60 seconds), and answers over 1 MiB are refused unless you raise maximumResponseBytes (up to 8 MiB). The client sends the token as Authorization: Bearer, never sends cookies and never follows redirects.

A write, from the complete example: saving to app storage with the version it replaces and an idempotency key.

export async function saveFeatured(
  client: PolturaClient,
  productIds: readonly string[],
  expectedVersion: number,
  idempotencyKey: string,
): Promise<StorageRecord> {
  const value = FeaturedProducts.parse({ productIds: [...productIds] });
  return client.storage.put(STORAGE_NAMESPACE, FEATURED_KEY, value, {
    expectedVersion,
    idempotencyKey,
  });
}

RoutesCopy Anchor Link

Lists take limit (1 to 100, default 25) and cursor, and answer with nextCursor: pass it back to get the next page, until it is null. Each route also has its own page in this section, with parameters and examples.

CatalogueProduct: { id, title 1–500, handle 1–255, description max 20000 or null, image, updatedAt }. PublicProductWriteStatus is draft | published. PublicMetadata max 64 snake_case keys, values max 2000. PublicTags max 32. PublicOrder includes orderNumber (1–64), items max 200 and shippingAddress. Money is { amount: "49.99", currency: "EUR" } in major units; do not multiply by 100.

A write counts as two requests against the installation's quota. Writing a field that the route does not allow fails with invalid_input. Every write takes an Idempotency-Key header, so a retried request is applied once.

Storage limitsCopy Anchor Link

A namespace is 1 to 64 characters, lowercase letters, digits and _, starting with a letter. A key is 1 to 128 characters, letters, digits, ., _ and -, starting with a letter or digit. Sending the same idempotency key with the same body returns the first answer again; with a different body it fails with conflict. A write whose expectedVersion is not the current version fails with stale_version: read the record again and retry.

Backend actionsCopy Anchor Link

Actions go the other way: a worker calls useAction(actionId), and Poltura sends a signed POST with { input, context } to your backendOrigin. They are not part of the App API; see Signed actions. Limits per installation: 60 calls a minute from the admin and 300 from the storefront, and 10 a minute per shopper. When a call cannot complete, the worker gets one of not_declared, timeout, upstream, too_large or unavailable.

ErrorsCopy Anchor Link

A failed call throws PolturaRequestError with code, status, requestId (quote it when you ask for help) and, for rate_limited, retryAfterMs. When the request never got an answer the code is one of response_too_large, invalid_response, request_failed, aborted or unavailable.

The API's error body is { "error": { "code", "message", "requestId", "details"?, "retryAfterMs"? } }, with these codes:

The OpenAPI 3.1 specification is at /openapi.json, generated from the same contracts as the SDK.

NextCopy Anchor Link

• Make your first API call: how your server gets a token, and a paginated product list.
• Authentication: tokens, refresh and permissions.