Changelog

Every additive change to the Platform API appears here under the dated revision the X-Dukkan-Api-Version header carries, and every theme-contract change under its date. Newest first. The versioning policy is in the API reference.

2026-09-10: Orders created by apps#

The third dated revision of v1 (X-Dukkan-Api-Version: 2026-09-10). All additive:

• Two new scopes. orders:create creates orders with prices the app sets; it is separate from orders:write and does not include reading orders. clients:write creates and updates customer records and is gated on the data processing agreement exactly like clients:read; its customer endpoints arrive in a later revision. orders:write now reads "Update order status, note and tags" on the consent screen. Scope reference.
• POST /orders creates an order with the agreed unit prices, for catalog variants and custom lines (OrderItem.kind is variant or custom), recomputes the totals, reduces stock under the stock policy or skips inventory, links the customer, notifies the merchant and emits order.created with source: "app". Specific codes: 422 currency_not_allowed and invalid_request with details.fields, 404 variant_not_found, 409 variant_unavailable, payment_method_disabled and insufficient_stock with details.lines. Orders created by apps.
• PATCH /orders/{id} updates the note, adds or removes tags as set operations, and merges the calling app's own attributes; the reference attribute renders as a chip on the merchant's order page. Order.tags, OrderDetail.note and OrderDetail.attributes are new fields, and GET /orders?tag= filters by tag.
• GET /store returns the store's public identity and checkout facts with no scope: pricing and storefront currencies, the FX table checkout applies as scaled / 10^scale, the enabled payment methods and the province vocabulary.
• GET /products gains q (ranked substring search over name, variant name, SKU, DSIN and barcode), status and ids; GET /products/variants?ids= re-validates up to 100 variants at once with their product name and status.
• The order.created payload carries source.
• @dukkan.one/app-sdk 0.3.0 adds orders.create, orders.update, products.search, products.variants and store.get, typed DukkanValidationError and DukkanConflictError with insufficientLines, and the FX helpers exchangeRateFor and buildCreateOrderLines. @dukkan.one/nuxt 0.3.0 exports enforceLimit and clientIp from @dukkan.one/nuxt/runtime. The SDK in any Node app, The Nuxt module.

2026-09-09 — App SDK, Nuxt module and CLI#

The official developer kit, published under the next dist-tag until 1.0.0:

• @dukkan.one/app-sdk: a typed Platform API client generated from the OpenAPI document, OAuth with PKCE and rotating tokens behind a TokenStore that serialises refreshes, a webhook receiver that verifies on raw bytes and deduplicates on the signed event id, commerce helpers for money in minor units and order transitions, and the dukkan.app.toml schema. Runs on Node, Workers, Bun and Deno. Quickstart, reference.
• @dukkan.one/nuxt: mounts the install, callback and webhook routes from dukkan.app.toml and asks for one contract, defineDukkanApp. The Nuxt module.
• @dukkan.one/cli: the dukkan binary now carries app init, app config push and pull, app dev with a public tunnel and a development session, app webhook trigger and app logs, next to the unchanged theme commands. @dukkan.one/theme-cli forwards to it with a deprecation notice. CLI reference.
• The contract for other languages, with the test vectors and the config schema, is published at /contracts/v1/. The contract for other languages.

2026-09-09 — App SDK contract#

The second dated revision of v1 (X-Dukkan-Api-Version: 2026-09-09). All additive:

• Token responses (both grants) carry install_id, store_id, store_slug and, on refresh, scope. Key your storage on the ids; see Authorization.
• GET /installation describes the token's install and store: effective scopes, distribution channel, the store's currency exponent, locale and timezone, and the current webhook subscription.
• Webhook envelopes carry a signed install_id; deliveries add the unsigned X-Dukkan-Install-Id header for secret lookup. Sandbox rehearsals carry test: true.
• POST /webhooks/test fires one signed delivery of any subscribed topic on a sandbox store, through the real outbox and delivery worker.
• A refresh token presented again within 30 seconds of its rotation, while the successor is valid, is a race: invalid_grant without revocation. See The refresh grant.
• 429 responses carry Retry-After; payment_status is a published enum; the OpenAPI document publishes every topic's payload schema under x-dukkan-topic-payloads.
• The dashboard shows drafts managed by dukkan.app.toml and warns when the portal and the file disagree. Webhook signing secrets minted from the dashboard now use the dk_whsec_ prefix like the API.

2026-09-02 — Documentation#

• The docs were rebuilt on the current tree, the layout contract in the theme guide was corrected ({% layout %} + {% block %}), fulfillment.requested was added to the topic table, and complete references for scopes, Liquid and the CLI were added.

2026-08 — Theme contract#

All additive unless noted:

• Sections on four pages: enabled_on on a section definition opens it to product, category and cart; absent keeps home only. page_sections reaches all four templates.
• Platform-owned section wrapper (a change for theme authoring, not for documents): snippets/sections.liquid is reserved and injected at push; the theme writes snippets/section-body.liquid; a theme emitting data-dukkan-section is rejected. Bodies render twice, a blank body emits no wrapper, and band: true is excluded from the sec--alt alternation.
• New schema keys: info, category, band and enabled_on on sections; localized on text settings; font on a select option.
• Two new types: datetime and richtext (output through the richtext filter).
• Settings document: the translations key is reserved for localized overrides (an accepted narrowing while external themes are sandbox-gated); url settings accept same-host absolute paths.
• New filters: file_alt, file_focal_style, tel_href, wa_href, money_major and date_localized. img_url became the image-CDN contract with a fixed width ladder.
• Context v1: product.savings and variant.savings, product.sold_count, product.image_color, and the four category image fields image_url, image_color, image_alt, image_focal_style (the first-letter fallback stays mandatory).
• Eastern Arabic numerals: the arabic_numerals setting switches the money filters to Arabic digits and the root is stamped data-dukkan-numerals="arabic".
• Runtime modules: scroll reveal, sticky buy button, back to top, dark mode [data-scheme="dark"], the "notify me" form, quick view, and the fly-to-cart effect for bundles.
• Performance: published themed pages are shared-cacheable; previews, sandboxes, the cart and search are excluded.
• Theme updates: first-party theme updates apply to their installs automatically; external themes update only through review and a merchant draft.

2026-08-29 — Theme marketplace#

• The publishing lifecycle is complete: media (cover + 3–8 screenshots with Arabic alt text), bilingual release notes, withdraw, retire and restore, the platform-owned demo store, draft-first updates for merchants, and insights. See Publish a theme.
• Product decisions: preview before buy, refunds handled by Dukkan finance under the Developer Terms, and a first response within 5 business days.

2026-08-19 — Sandbox stores and the DPA#

• Sandboxes are born seeded: 3 per organization, 90 days renewable, with reset, renew and purge commands. See Sandbox stores.
• The @dukkan.one/theme-cli@0.1.0 CLI and the DKN-XXXXXX device flow.
• Data processing agreement version 2026-08-19.

2026-08-10 — Developer terms#

• First version of the developer terms.

2026-08-09 — Platform API v1#

The first dated revision of v1 (X-Dukkan-Api-Version: 2026-08-09):

• Resources: orders, fulfillments, refunds, products, discounts, inventory movements and the webhook subscription.
• Conventions: Idempotency-Key on every write, opaque cursor pagination, 180 requests per minute per install, and a uniform error envelope.
• The 12 events including fulfillment.requested, signed with HMAC-SHA256 and retried up to 8 times.