API Reference

Reference documentation for the Arky SDK modules and their REST routes.

Modules

Module	What it covers
Account	Operator sign-in codes, sessions and the account
Store	The store, its email sending, its Arky plan, roles and members, webhooks
Markets and Channels	Markets, sales channels, publishable and secret keys, zones, tax categories
E-shop	Products, bookings, catalogs and prices, carts, orders, payments, returns, inventory, companies
Customer Groups	Groups, offerings, members, revisions, renewals and member changes
Shipping and Fulfillment	Shipping profiles and methods, routing, fulfillment jobs, deliveries and pickups
Promotions	Code-based discounts and promotion codes
Content	Collections, entries and the block types
Media	Images, videos and PDFs with their smaller versions
Categories	Classifications with filter fields
Customers	Customers, sessions, sign-in codes and email changes, suppressions, notes
Forms	Forms, submissions with files, stages and notes
Store Email	The store’s Resend account, email addresses, templates and email settings
Broadcasts	One email to the members of customer groups
Outgoing Email And Webhooks	Every email Arky sends and every webhook post
Support	Fixed-step support flows and conversations by chat and email
Store Locations	The store’s places and country reference data
Platform	Currencies, events, Arky plans, platform administrators

Base URL

https://api.arky.io

Authentication

Storefront routes (/v1/storefront/...) take the store’s public key on every request, and a customer session once the visitor has one:

X-Arky-Publishable-Key: arky_pk_...
Authorization: Bearer CUSTOMER_SESSION_TOKEN

Admin routes (/v1/stores/{store_id}/...), account routes (/v1/accounts/...) and platform routes (/v1/platform/...) take an account session; store routes also take one of the store’s secret keys, which acts with its own permissions:

Authorization: Bearer ACCOUNT_ACCESS_TOKEN
Authorization: Bearer arky_sk_...

Storefront Context

Storefront requests carry their context in headers, set by the SDK from initialize options or setContext. The sales channel comes from the publishable key: each publishable key belongs to one channel, so there is no channel header.

Header	Meaning
X-Arky-Locale	the language: one of the store’s languages, with no fallback
X-Arky-Market	the market key; implied when the key’s channel lists exactly one active market
X-Arky-Cart-Token	the cart’s recovery token, sent by the SDK
X-Arky-Order-Token	an order’s secret, for a guest reading or changing their order

A support chat has no token of its own: it belongs to the customer of the session that started it.

Requests

• Bodies are JSON with snake_case fields; form submissions and uploads are multipart.
• The app picks every id. A create carries the new record’s id, a canonical UUID v4 the app makes once per user action (crypto.randomUUID()) and sends again on every retry. The same request under the same id returns the existing record; a different request under it is refused with 409.
• Changes carry what they read. An update or an action carries expected_updated_at, the record’s updated_at as read; a delete carries it in the query. A stale value is refused with 409 GENERAL.CONFLICT, so a repeated action can’t apply twice.
• Language is explicit. A request that stores or renders text in a language names it in language (or X-Arky-Locale on storefront reads). It must be one of the store’s languages.
• Enums are objects tagged by type: { "type": "scheduled", "send_at": 1767254400000 }.
• Moments are integer epoch milliseconds; days are "YYYY-MM-DD"; money is integer minor units of its currency.

Responses

A response is the record itself, without secrets such as tokens and keys. Lists are paged:

{
	"items": [],
	"cursor": "next_page_cursor"
}

Follow cursor until it is null, even after an empty page.

Errors

{
	"error": "STORE.DELETING",
	"message": "This store is being closed and can't change",
	"status_code": 409,
	"validation_errors": []
}

• 400 a request that breaks a rule, with validation_errors naming the fields;
• 401 and 403 missing or insufficient access;
• 404 a record that isn’t there, or a reference to one;
• 409 with GENERAL.CONFLICT: a stale expected_updated_at or another request under a used id; with a named code: a record that is being deleted (REFERENCE.DELETING), a delete refused because something points at the record (REFERENCE.STILL_REFERENCED, the message names who), or a business rule such as PRICE.OVERLAP;
• 402 a store whose Arky plan has no access, on the storefront.

See Error Handling for handling them in code.