API changelog

Product update notifications - October 2026

Email the buyers of a product that it has been updated — the campaign a merchant starts with Notify customers on a product's page — from your own system. Additive to the v1 contract. Available on every paid plan.

• New POST /products/{shopify_product_id}/notifications: queues a campaign (202) for every buyer of the product's downloadable mappings, or, with variant_ids, of the mappings serving those variants. Optional plain-text message of up to 2,000 characters with {customer.first_name}, {shop.name}, {product.title} and {product.metafields.<namespace>.<key>}; no links. dry_run runs every check and returns the counts, subject and rendered note without sending (200; use a fresh Idempotency-Key per dry run). Costs 10 rate-limit tokens.
• New GET /notifications/{notificationId}: the campaign's status, counts, waiting_for_archive and a closed error vocabulary; completed with partial: true when some sends failed. Campaigns started in the app appear too.
• New POST /notifications/{notificationId}/cancel: cancels a queued campaign (200). It keeps the product's 7-day limit, exactly like cancelling in the app.
• New optional notify_customers object on POST /mappings and PUT /mappings/{id}: queues a notification for the written mapping's buyers after the write commits. A note that breaks a rule about its own text (blank, too long, a bad variable, more than five metafields, a link in the text) is 422 invalid_message with nothing written; a metafield problem and every other refusal is reported in the new data.notification field (created: false, error), never as a 4xx. data.notification is present only when the flag was sent; existing responses are unchanged.
• One campaign per product per 7 days, across all of its variants and every source, and none while one is still queued or sending: 429 notification_cooldown with Retry-After (up to seven days) and error.details.next_available_at. Not the token bucket — do not retry it automatically; schedule the next call at next_available_at.
• At most 5 campaigns per shop queued or sending at once, across every product and every source: a sixth is 429 too_many_active_notifications with error.details.limit and error.details.active_notification_ids, and no Retry-After. Retry once one of them has finished. A dry run is refused the same way; on a mapping write it is reported in data.notification.
• One product update email per buyer per shop per 24 hours, across every campaign: a buyer who already got one is skipped when the campaign sends. Skipped buyers are not in sent_count, failed_count or suppressed_count. A campaign that skipped every buyer ends failed with error: recipients_recently_notified and does not use the product's 7 days.
• Before each batch of up to 500 emails the campaign checks the shop again and stops if the subscription or paid plan lapsed, customer emails were turned off, sending was suspended, or Alva switched notifications off. Stopped before anyone was emailed it is failed (plan_required, email_disabled, notifications_suspended or notifications_switched_off) and releases the 7 days; stopped later it is completed with partial: true. A campaign whose every send failed is failed with nothing_sent and releases the 7 days too, and one with nobody left to email by the time it sent is failed with no_eligible_recipients and releases them as well.
• A campaign whose targeted mapping has a ZIP rebuild in flight waits for it (waiting_for_archive: true; only a mapping that delivers a ZIP archive makes a campaign wait); a failed rebuild, or one that makes no progress for 60 minutes while building (6 hours while still waiting to start or to retry), counted from the rebuild, not from the campaign's creation, fails the campaign with zero sends and releases the limit.
• Eight new error codes: 403 notifications_suspended, 404 notification_not_found, 409 notification_not_cancellable, 422 invalid_message, 422 no_downloadable_content, 422 no_eligible_recipients, 429 notification_cooldown, 429 too_many_active_notifications. mapping_not_found and multiple_mappings_match gain error.details.unresolved_variant_ids / ambiguous_variant_ids on this endpoint.

Access update - September 2026

API access is no longer approval-only.

• Every paid plan (Basic, Pro and Enterprise) can use the API. Create keys in the app under Settings → API keys; there is nothing to request.
• On the Free plan the API keys tab is hidden, and existing keys return 402 plan_required until the shop upgrades.

v1 update - July 2026

Additive error-code and response-field additions to the existing v1 contract.

• New 422 withdrawal_consent_required error on the order download-urls endpoint: returned when the shop has EU withdrawal-right consent enabled and the order has no consent record yet; download URLs are issued once the customer consents.
• New 422 key_limit_reached error when creating API keys: a shop can hold at most 25 active API keys; revoke one first.
• New 409 delivery_not_yet_released error on the order download-urls and resend endpoints: returned when the product has a download delivery delay configured and the buyer's files have not unlocked yet. No download URLs are minted and no email is sent until the delay elapses.
• New error.details object on the error envelope: present only on codes that carry caller-safe context. Today delivery_not_yet_released is the only producer, and it carries release_at, the ISO 8601 instant the downloads unlock. Treat the object as open - new keys may appear without a major version.
• New delivery_pending and release_at fields on the order-status purchase object: delivery_pending is true while a purchase is still held by a download delivery delay, and release_at is the ISO 8601 unlock instant, or null when nothing is pending.
• The grant-downloads endpoint now releases held purchases on the order immediately, so a merchant can override a download delivery delay through the API.

v1.0.0 - June 2026

Initial pilot API surface behind approval-only access.

• API keys for approved shops.
• Required idempotency keys on write requests.
• Remote URL asset import, direct uploads, asset listing, asset updates, and asset deletion.
• Flat categories, product mappings, packs, and license-key tags.
• Order assignments that make mapped downloads visible in Shopify customer accounts.
• Order access controls: revoke, restore, grant downloads, and resend email.
• Job and order status endpoints.
• OpenAPI spec and Postman collection downloads.

Versioning policy

The v1 contract is additive-only: new endpoints, optional fields, and new error codes may be added. Breaking changes will use a future /api/v2 path.