Set up API access
1. Confirm the shop is on a paid plan
The API works on every paid plan. On the Free plan the API keys tab is hidden and existing keys return plan_required; upgrade to a paid plan to use the API.
2. Create an API key
Open Alva Settings, choose API keys, and create a key for the integration. Copy the token once and store it in a secret manager. Alva stores only a public key id and a hash of the secret. Once the key exists, that same tab shows your API base URL — the address every request goes to.
3. Send the token as a Bearer header
Send every request with Authorization: Bearer adk_live_.... A missing, malformed, unknown, or revoked key returns the same unauthorized response so attackers cannot enumerate valid keys.
4. Include idempotency keys on writes
Every non-GET request must include an Idempotency-Key header. Reusing the same key and body safely replays a successful response instead of creating a duplicate asset, mapping, assignment, or access change.
Create assets and map products
Use POST /api/v1/assets to ingest a remote file from an allowlisted host, or use the direct-upload endpoints when your integration uploads to Alva storage itself. Poll GET /api/v1/jobs/{job_id} until remote ingest completes.
After the asset exists, create or update a mapping with POST /api/v1/mappings. Product ids should use Shopify GID format. The API scopes every mapping to the shop attached to the API key.
Assign downloads to orders
Use POST /api/v1/orders/{shopify_order_id}/assignments when an external system needs to give a customer access to mapped digital products. The assignment can create the customer record, create the purchase, and optionally send the delivery email.
Use the order access endpoints to revoke access, restore access, grant extra downloads, or resend the delivery email. These actions are shop-scoped and do not accept shop ids in the request body.
Read the API docs
Use the quickstart, endpoint reference, error guide, and downloadable OpenAPI spec when building an integration.
FAQ
Can every merchant use the external API?
Every merchant on a paid plan (Basic, Pro or Enterprise) can. The Free plan does not include API access.
Do write requests need idempotency keys?
Yes. Every non-GET request must include an Idempotency-Key header so retries do not create duplicate assets, mappings, assignments, or access changes.
See also
Was this helpful?
Last updated 2026-10-05