What is the Alva Digital Downloads API?
The Alva Digital Downloads API is a versioned REST API — v1 — that lets an external system manage digital downloads on a Shopify store without opening the Shopify admin. Through it a developer can create files, map them to products, look up orders, issue download URLs, resend delivery emails, and check license-key stock, all over standard HTTPS.
The API sits alongside the app's admin interface rather than replacing it. Every resource it touches — files, product mappings, categories, orders, license-key tags — is the same data your team edits by hand in Alva, just reachable from code. That makes it the bridge between Alva Digital Downloads and whatever else runs your business.
What you can do with the Alva API
The Alva API covers the core delivery workflow end to end. It manages files, product mappings and categories, looks up orders and issues download URLs, resends branded delivery emails, and reports license-key stock. Files can be uploaded directly, or ingested from a remote URL that Alva streams straight into storage on your behalf.
In practical terms, an integration can:
- Manage files — upload a file directly, or hand Alva a URL and it streams the asset into storage for you (remote-URL ingest), so a large library never has to pass through your own servers first.
- Map products and categories — attach files, packs, links, or license-key tags to Shopify products using the same many-to-many model the admin uses.
- Look up orders and issue download URLs — resolve a Shopify order and mint a fresh, time-limited download URL for the buyer.
- Resend delivery emails — re-trigger the download email for an order from code, without editing anything by hand.
- Check license-key stock — read how many keys remain for a tag before a big launch, so you never sell out silently.
Endpoint paths, request bodies, and response shapes live in the API reference. This post stays at the level of what the API is for; the reference is where you wire up each individual call.
How authentication and API keys work
Authentication uses per-shop API keys. Each request carries a Bearer token that begins with adk_live_. Alva Digital Downloads stores only a sha256 hash of the secret — never the plaintext — compares it in constant time, and fails closed, so a missing, malformed, unknown, or revoked key all return the same unauthorized response.
You create a key inside the Alva admin, copy the token once, and store it in a secret manager. Alva keeps only the public key id and the hash, so the plaintext secret is never recoverable from your account. Because every failure mode returns an identical response, an attacker cannot probe your store to tell a wrong key from a revoked one.
Issue a separate key per system, and revoke any one of them the moment an integration is retired. A revoked key stops working immediately across every endpoint, which makes rotating credentials a one-click action rather than a coordinated migration.
Built for automation at scale
The Alva API is built to be driven by machines that retry. Idempotency keys are required on every write, with a 24-hour replay window that turns a duplicated request into the original response instead of a second record. A token-bucket rate limiter protects the store, and every response returns a request_id for tracing.
Idempotency is not optional on writes. Every non-GET request must send an Idempotency-Key header; reuse the same key and body and Alva safely replays the first result rather than creating a duplicate file, mapping, or assignment. A retry after a dropped connection is therefore harmless:
curl https://.../api/v1/mappings \
-H "Authorization: Bearer adk_live_..." \
-H "Idempotency-Key: 2f9c-4b1e-...-e1" \
-H "Content-Type: application/json" \
-d '{ "product_id": "gid://shopify/Product/123", ... }'Beyond idempotency, a token-bucket rate limiter caps bursts so one runaway script cannot overwhelm your delivery pipeline, sensitive values are redacted from logs, and remote-URL ingest runs behind an SSRF guard that blocks requests aimed at internal addresses. The request_id on every response gives you and Alva support a single string to trace one call from request to result.
API or Shopify Flow: which path is yours?
Alva Digital Downloads gives you two ways to automate. Shopify Flow is the no-code path — visual triggers and actions you assemble in Shopify's editor. The API is the code path, for teams that need programmatic control from their own systems. Most stores never need the API; Flow covers the common automations.
If your goal is to tag a fraud-flagged customer, revoke access on a refund, or reward VIP buyers, build it visually — the guide to Shopify Flow automations for digital downloads walks through Alva's triggers and actions. Reach for the API when the logic lives outside Shopify: an ERP that owns your catalog, an LMS that provisions course access, or a CRM that has to stay in sync. Under the hood, both drive the same engine behind Alva's multi-channel download delivery.
Who the Alva API is for
The Alva API is aimed at three audiences: developers who want to script bulk file and mapping work, agencies building custom or headless Shopify storefronts that deliver digital goods, and operations teams syncing downloads with an external ERP, LMS, or CRM. Merchants running a standard Shopify storefront rarely need it.
A headless build can keep Shopify as the source of truth for orders while the API issues download URLs to a bespoke front end. An operations team can let its ERP create files and mappings the moment a product ships, so the storefront and the back office never drift apart. The common thread is control that has to originate outside the Shopify admin.
None of this is a requirement for selling digital products on Shopify — the Alva admin already handles that end to end. The API is for the minority of stores whose scale or architecture has outgrown clicking through a user interface.
How to get access to the API
API access is opt-in and gated. A global availability flag plus a per-shop toggle mean the API is switched on for one store at a time on request, not enabled for everyone by default. Contact Alva support to turn it on for your store. The API is available on paid plans and is rolling out gradually.
Ask Alva support to enable API access, then create a key from the Alva admin. The help guide to using the external API walks through keys, idempotency, remote ingest, and order assignments, and the build ships with a full API reference, a downloadable OpenAPI spec, and a Postman collection. Check the plans for where the API sits.
Frequently asked questions
The Alva Digital Downloads API is a versioned REST API, v1, that lets an external system manage digital downloads on a Shopify store without using the Shopify admin. Through it a developer can create files, map them to products, look up orders, issue download URLs, resend delivery emails, and check license-key stock over standard HTTPS.
Only for writes. Every non-GET request must include an Idempotency-Key header, which has a 24-hour replay window, so a retried call returns the original response instead of creating a duplicate file, mapping, or assignment. Read requests do not need one. This keeps automations that retry after a network error safe from making duplicate changes.
The API uses per-shop API keys. Each request sends a Bearer token that begins with adk_live_. The app stores only a sha256 hash of the secret, never the plaintext, compares it in constant time, and fails closed, so a missing, malformed, unknown, or revoked key all return the same unauthorized response and cannot be told apart.
Shopify Flow is the no-code automation path, built from visual triggers and actions inside Shopify. The API is the code path, for teams that need programmatic control from their own systems. Use Flow for automations that live inside Shopify, and the API when the logic lives in an external ERP, LMS, or CRM.
API access is opt-in and gated per store. A global availability flag plus a per-shop toggle mean it is switched on individually on request, not enabled for everyone by default. Contact Alva support to turn it on for your store. The API is available on paid plans and is rolling out gradually.