@commercelayer/agent-cli 0.2.0 → 0.2.2

package/README.md

@@ -15,13 +15,13 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | Command | Does |
 | --- | --- |
 | `init [--name <business name>]` | Create a sandbox store, with no login. The name (the folder name when absent) names the organization; the org slug and store hostname derive from it, numbered when taken. Writes `store.yml` (a commented template) and `credentials`. Reuses the store if they exist. |
-| `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, images, and the store's name, policies and theme. `missing_images` lists `img/<file>` references with no file in `.commercelayer/img/` (`apply` refuses them); `unused_images` lists files there that nothing references. |
-| `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused; While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
+| `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, promotions, images, and the store's name, policies and theme; `warnings` flags more than 10 active promotions without a coupon. `missing_images` lists `img/<file>` references with no file in `.commercelayer/img/` (`apply` refuses them); `unused_images` lists files there that nothing references. |
+| `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products and promotions Commerce Layer refused. While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
 | `catalog pull` | Read the products from the catalog source in `store.yml` (a Supabase table, a Google Sheet or a Google Merchant Center feed) into `.commercelayer/products/catalog.csv`. Then `plan` and `apply` as usual. |
 | `storefront init [--force]` | Custom storefronts only. Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. Product images are the store's, at `/img/<file>` (from `.commercelayer/img/`, uploaded by `apply`); products with no image get a neutral tile. The site's own files go in `storefront/assets/`. Refuses to overwrite without the flag; with it, rewrites the three files. |
 | `storefront publish` | Custom storefronts only. Upload the folder at `storefront.path` (default `storefront`) to the store host, where it replaces the hosted theme, leaving out dotfiles. `/img/` on the store host is always the store's images, so files under the folder's `img/` are not served: publish lists them as `not_served`. |
 | `storefront check` | Custom storefronts only. Read the published storefront at the preview URL and check it: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product and none for unknown skus, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides (no dead `::part` rules), title, `lang`, viewport, description, and whether the folder changed since publish. Prints `{ status, summary, checks: [{ id, kind, status: pass\|warn\|fail, message, fix, items }], render }` and exits 1 when a check fails; warnings do not fail. `kind` is `static` today; a later rendering phase adds `render` checks and fills `render`. |
-| `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order and every step. |
+| `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order, the `discounts` applied (promotions and codes, in minor units like the totals) and every step. |
 | `orders list` | The orders placed in the store, newest first, as UCP order entities. |
 | `orders show <id or number>` | One order. |
 | `ucp profile [--agent]` | The store's UCP business profile (`/.well-known/ucp`); with `--agent`, this CLI's own platform profile. |
@@ -58,6 +58,16 @@ theme:
   logo: img/logo.svg   # or an https:// URL; default: the name as a wordmark
   hero: img/hero.jpg   # the home page's wide image; default: a band in the accent
   tagline: Small-batch coffee, roasted in Milan   # at most 120 characters; default: "Ships to <countries>"
+promotions:
+  # Discounts: rules (when, all must match) and actions (what). The id is stable.
+  - id: welcome10
+    name: Welcome, 10% off
+    rules: [{ coupon: WELCOME10 }]
+    actions: [{ percentage: 10 }]
+  - id: free-shipping-50
+    market: eu
+    rules: [{ order_amount: { min: 50 } }]
+    actions: [free_shipping]
 policies:
   # Pages shopping agents show buyers before they pay. Without them the store
   # serves default sandbox pages at <preview_url>/policies/<name>.
@@ -65,6 +75,15 @@ policies:
   terms_of_service: https://example.com/terms
   returns: https://example.com/returns
 ```
+### Promotions
+Each entry under `promotions:` has an `id` (lowercase letters, digits and dashes; the store identifies the promotion by it) and optionally `name`, `market` (a market code; without it, every market), `starts` and `ends` (a day, or a UTC time; a bare `ends` day runs to 23:59:59Z; without them the promotion is always on), `limit` (total uses), `priority` (lowest first), `exclusive` and `enabled`.
+
+- Rules, one of each kind at most, all matching: `coupon: CODE` or a list (8 to 40 letters, digits, `-`, `_`), `order_amount: { min }` (the items total), `skus: [...]` or `category: A > B` (resolved to its products' skus by the CLI).
+- Actions: `percentage: 10` (with `skus` or `category` to limit it), `fixed_amount: 5`, `free_shipping`, `fixed_price: { price, skus|category }`, `free_gift: { skus|category, quantity }`, `buy_x_pay_y: { x, y, cheapest_free?, skus|category }`. Actions without their own skus take the rule's. Amounts are in major units, like prices; in a store with several currencies, a promotion with an amount names its `market`. Commerce Layer gets one promotion per action.
+- `flex: { rules: [...] }` holds a Commerce Layer Rules Engine promotion as written (amounts in cents), in place of `rules` and `actions`. It needs the Rules Engine: sandboxes do not have it, and `apply` stops with `flex_unavailable`, applying nothing.
+
+`plan` lists them as `promotion` changes, and warns when more than 10 promotion actions without a coupon are active (Commerce Layer applies 10). Removing one needs `--allow-delete`. `orders test --code <CODE>` proves one: its `discounts` lists what was taken off, and a code that applied nothing is a `discount_code_invalid` warning in `messages`.
+
 ### The products folder
 Beyond a handful of products, put the catalog in `.commercelayer/products/` and leave `products` out of `store.yml`. Every file in the folder is merged into the catalog by sku, in file-name order:
 - `<name>.yml`: a list of products in the shape above (one file per collection, or one per product, as you like).
@@ -96,7 +115,7 @@ One rule for images: `img/<file>` anywhere in `store.yml` (product `image_url`,
 
 A custom storefront replaces the theme: `storefront.path` in `store.yml` names its folder, `storefront init` writes a drop-in.js scaffold, `storefront publish` uploads it, `storefront check` checks it. Its pages link product images at `/img/`; its own files (fonts, icons, styles) go in `assets/`, not `img/`.
 
-Error codes: `invalid_theme`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
+Error codes: `invalid_theme`, `invalid_promotion`, `flex_unavailable`, `promotions_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:
 | What | Where |

package/dist/api/stub/management.js

@@ -7,10 +7,11 @@ import { publicOrders, readDb, SANDBOX_DOMAIN, writeDb } from './db.js';
 import { bearer, error, json, readJson } from './http.js';
 function publicState(r) {
     const { token: _token, ucp: _ucp, pending: _pending, asset_files: _files, ...state } = r;
-    return { ...state, name: r.name ?? null, policies: r.policies ?? null, theme: r.theme ?? null, assets: r.assets ?? {}, apply: r.apply ?? null, orders: publicOrders(r) };
+    return { ...state, name: r.name ?? null, policies: r.policies ?? null, theme: r.theme ?? null, assets: r.assets ?? {}, promotions: r.promotions ?? {}, apply: r.apply ?? null, orders: publicOrders(r) };
 }
-/** Like Commerce Layer refusing a sku in an import. Only the stub does this, so tests can exercise apply_failed. */
+/** Like Commerce Layer refusing a sku or a promotion in an import. Only the stub does this, so tests can exercise apply_failed. */
 const REFUSED = /^REFUSED-/;
+const REFUSED_PROMOTION = /^refused-/;
 /** C11R_STUB_BUSY_READS=n: the first n reads of a running import answer 503 commercelayer_busy, as when Commerce Layer rate-limits. Per process. */
 let busyReads = Number(process.env.C11R_STUB_BUSY_READS) || 0;
 /** Items an import gets through per read: small, so the CLI polls a few times. */
@@ -28,13 +29,19 @@ function advance(r) {
         return;
     job.step = 'done';
     job.finished_at = new Date().toISOString();
-    if (r.pending.refused.length) {
+    const refusedPromotions = r.pending.refused_promotions ?? [];
+    if (r.pending.refused.length || refusedPromotions.length) {
         job.status = 'failed';
-        job.errors = r.pending.refused.slice(0, 50).map((sku) => ({ sku, message: 'code is invalid' }));
+        job.errors = [
+            ...r.pending.refused.map((sku) => ({ sku, message: 'code is invalid' })),
+            ...refusedPromotions.map((id) => ({ sku: null, promotion: id, message: 'is invalid' })),
+        ].slice(0, 50);
     }
     else {
         job.status = 'completed';
         r.applied = r.pending.applied;
+        if (r.pending.promotions)
+            r.promotions = r.pending.promotions;
         r.applied_hash = job.hash;
     }
     delete r.pending;
@@ -98,11 +105,21 @@ export function handleManagement(req) {
         writeDb(db);
         if (record.apply?.status === 'in_progress')
             return error(409, 'apply_in_progress', 'Another apply is still running.', 'Run `c11r status` to follow it, then apply again.');
-        const { applied, hash, name, policies, theme, assets, allow_delete, full } = readJson(req);
+        const { applied, hash, name, policies, theme, promotions, assets, allow_delete, full } = readJson(req);
         const before = record.applied?.products ?? {};
         const removed = Object.keys(before).filter((sku) => !(sku in applied.products));
-        if (removed.length && !allow_delete)
-            return error(409, 'deletes_need_approval', `Apply would delete product ${removed.join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
+        // No promotions field (older CLIs): the promotions stay as they are.
+        const promosBefore = record.promotions ?? {};
+        const promos = promotions ? Object.fromEntries(promotions.map((p) => [p.id, p])) : promosBefore;
+        const promosRemoved = Object.keys(promosBefore).filter((id) => !(id in promos));
+        const promosChanged = Object.keys(promos).filter((id) => !(id in promosBefore) || canonical(promosBefore[id]) !== canonical(promos[id]));
+        const doomed = [...removed.map((sku) => `product ${sku}`), ...promosRemoved.map((id) => `promotion ${id}`)];
+        if (doomed.length && !allow_delete)
+            return error(409, 'deletes_need_approval', `Apply would delete ${doomed.join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
+        // Sandboxes have no Rules Engine: a new or changed flex promotion is refused before anything applies.
+        const flexAt = (promotions ?? []).findIndex((p) => p.flex && promosChanged.includes(p.id));
+        if (flexAt >= 0)
+            return error(422, 'flex_unavailable', `promotions[${flexAt}] (${promotions[flexAt].id}): flex promotions need the Rules Engine, which this organization does not have.`, 'Tell the human flex promotions need a Commerce Layer plan with the Rules Engine; build the promotion from the standard rules and actions if you can, or remove it, then apply again.');
         // The name, policies and markets apply in the request; products go through an
         // import job (SKUs, prices, then cleanups for removals) when any changed.
         record.name = name;
@@ -119,8 +136,10 @@ export function handleManagement(req) {
             }
         }
         const changed = Object.keys(applied.products).filter((sku) => full || !(sku in before) || canonical(before[sku]) !== canonical(applied.products[sku]));
-        if (changed.length === 0 && removed.length === 0) {
+        const refusedPromotions = promosChanged.filter((id) => REFUSED_PROMOTION.test(id));
+        if (changed.length === 0 && removed.length === 0 && refusedPromotions.length === 0) {
             record.applied = applied;
+            record.promotions = promos;
             record.applied_hash = hash;
             writeDb(db);
             return json(200, publicState(record));
@@ -131,12 +150,12 @@ export function handleManagement(req) {
             step: 'skus',
             hash,
             processed: 0,
-            total: changed.length + removed.length,
+            total: changed.length + removed.length + promosChanged.length + promosRemoved.length,
             started_at: new Date().toISOString(),
             finished_at: null,
             errors: [],
         };
-        record.pending = { applied, refused: changed.filter((sku) => REFUSED.test(sku)) };
+        record.pending = { applied, refused: changed.filter((sku) => REFUSED.test(sku)), promotions: promos, refused_promotions: refusedPromotions };
         writeDb(db);
         return json(202, publicState(record));
     }

package/dist/api/stub/shopping.js

@@ -208,23 +208,85 @@ function buildLines(ctx, market, requested, existing = []) {
     });
     return { lines, messages };
 }
-/** Apply discount codes: the sandbox code is 10% off the items; anything else is rejected with a warning. */
-function discounts(ctx, body, lines, messages) {
-    if (!ctx.shared.has('dev.ucp.shopping.discount') || body.discounts === undefined)
-        return undefined;
-    const codes = (body.discounts.codes ?? []).map((c) => String(c));
+/** The promotions that match these lines and codes, as Commerce Layer applies them: by priority, an exclusive one alone. */
+function promotionDiscounts(ctx, market, lines, codes, shipping) {
+    const now = Date.now();
     const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
-    const appliedList = [];
-    codes.forEach((code, i) => {
-        if (code.toUpperCase() === SANDBOX_CODE) {
-            if (appliedList.length)
-                messages.push(warn('discount_code_already_applied', `${code} is already applied.`, `$.discounts.codes[${i}]`));
+    const upper = codes.map((c) => c.toUpperCase());
+    const used = new Set();
+    const matching = [];
+    for (const p of Object.values(ctx.record.promotions ?? {})) {
+        if (!p.enabled || p.flex || !p.actions || Date.parse(p.starts) > now || Date.parse(p.ends) <= now)
+            continue;
+        if (p.market && p.market !== market.code)
+            continue;
+        const r = p.rules ?? {};
+        const code = r.coupons?.find((c) => upper.includes(c.toUpperCase()));
+        if (r.coupons && !code)
+            continue;
+        if (code)
+            used.add(code.toUpperCase());
+        if (r.order_amount && subtotal < toMinor(r.order_amount.min, market.currency))
+            continue;
+        if (r.skus && !lines.some((l) => r.skus.includes(l.item.id)))
+            continue;
+        matching.push({ p, code });
+    }
+    matching.sort((a, b) => (a.p.priority ?? Infinity) - (b.p.priority ?? Infinity));
+    const exclusive = matching.find((m) => m.p.exclusive);
+    const applied = [];
+    for (const { p, code } of exclusive ? [exclusive] : matching) {
+        let amount = 0;
+        for (const a of p.actions) {
+            const on = (skus) => lines.filter((l) => !skus || skus.includes(l.item.id));
+            const units = (skus) => on(skus).flatMap((l) => Array(l.quantity).fill(l.item.price)).sort((x, y) => x - y);
+            if (a.type === 'percentage')
+                amount += Math.floor((on(a.skus).reduce((s, l) => s + l.totals[0].amount, 0) * a.value) / 100);
+            else if (a.type === 'fixed_amount')
+                amount += Math.min(toMinor(a.value, market.currency), subtotal);
+            else if (a.type === 'free_shipping')
+                amount += shipping ?? 0;
+            else if (a.type === 'fixed_price')
+                amount += on(a.skus).reduce((s, l) => s + Math.max(0, l.item.price - toMinor(a.price, market.currency)) * l.quantity, 0);
+            else if (a.type === 'free_gift')
+                amount += units(a.skus).slice(0, a.quantity).reduce((s, x) => s + x, 0);
+            else if (a.cheapest_free) {
+                const all = units(a.skus);
+                amount += all.slice(0, Math.floor(all.length / a.x) * (a.x - a.y)).reduce((s, x) => s + x, 0);
+            }
             else
-                appliedList.push({ code: SANDBOX_CODE, title: '10% off', amount: Math.floor(subtotal / 10), method: 'across' });
+                amount += on(a.skus).reduce((s, l) => s + Math.floor(l.quantity / a.x) * (a.x - a.y) * l.item.price, 0);
         }
-        else
+        if (amount > 0)
+            applied.push({ ...(code ? { code } : {}), title: p.name, amount, ...(code ? {} : { automatic: true }), method: 'across' });
+    }
+    return { applied, used };
+}
+/**
+ * Discounts: the store's promotions (automatic ones, and those whose code was entered) plus the
+ * sandbox code, 10% off the items. A code that applies nothing is reported with a warning.
+ */
+function discounts(ctx, body, lines, messages, market, shipping) {
+    if (!ctx.shared.has('dev.ucp.shopping.discount'))
+        return undefined;
+    const codes = (body.discounts?.codes ?? []).map((c) => String(c));
+    const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
+    const { applied: appliedList, used } = promotionDiscounts(ctx, market, lines, codes, shipping);
+    const seen = new Set();
+    codes.forEach((code, i) => {
+        const key = code.toUpperCase();
+        if (seen.has(key))
+            messages.push(warn('discount_code_already_applied', `${code} is already applied.`, `$.discounts.codes[${i}]`));
+        else if (key === SANDBOX_CODE)
+            appliedList.push({ code: SANDBOX_CODE, title: '10% off', amount: Math.floor(subtotal / 10), method: 'across' });
+        else if (!used.has(key))
             messages.push(warn('discount_code_invalid', `${code} is not a valid code.`, `$.discounts.codes[${i}]`));
+        else if (!appliedList.some((d) => d.code?.toUpperCase() === key))
+            messages.push(warn('discount_code_invalid', `${code} does not apply to this order.`, `$.discounts.codes[${i}]`));
+        seen.add(key);
     });
+    if (body.discounts === undefined && !appliedList.length)
+        return undefined;
     return { codes, applied: appliedList };
 }
 function consent(ctx, buyer) {
@@ -251,7 +313,7 @@ function totals(lines, discount, shipping) {
 function cartFrom(ctx, body, existing) {
     const market = pickMarket(ctx, body.context ?? existing?.context);
     const { lines, messages } = buildLines(ctx, market, body.line_items, existing?.line_items);
-    const discount = discounts(ctx, body, lines, messages);
+    const discount = discounts(ctx, body, lines, messages, market);
     const cart = {
         ucp: envelope(ctx, 'cart'),
         id: existing?.id ?? id('cart'),
@@ -315,11 +377,6 @@ function evaluate(ctx, ck, requested) {
     ck.line_items = lines;
     if (lines.length === 0)
         messages.push(err('item_unavailable', 'The checkout has no purchasable items.', '$.line_items'));
-    const discount = discounts(ctx, requested, lines, messages);
-    if (discount)
-        ck.discounts = discount;
-    else
-        delete ck.discounts;
     if (!ck.buyer?.email)
         messages.push(err('missing', 'An email address is needed for the order confirmation.', '$.buyer.email'));
     let shipping;
@@ -353,6 +410,11 @@ function evaluate(ctx, ck, requested) {
     }
     else
         shipping = 0;
+    const discount = discounts(ctx, requested, lines, messages, market, shipping);
+    if (discount)
+        ck.discounts = discount;
+    else
+        delete ck.discounts;
     ck.totals = totals(lines, discount, shipping);
     const blocking = messages.some((m) => m.type === 'error');
     ck.status = blocking ? 'incomplete' : 'ready_for_complete';

package/dist/commands.js

@@ -10,6 +10,7 @@ import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from
 import { storefrontFiles } from './storefront.js';
 import { imageNotes, planAssets, uploadAssets } from './assets.js';
 import { pull } from './catalog.js';
+import { ACTIVE_LIMIT, activeWithoutCoupon } from './promotions.js';
 import { storefrontCheck } from './check.js';
 import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
@@ -19,13 +20,13 @@ import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
 export const VERSION = createRequire(import.meta.url)('../package.json').version;
 export const HELP = {
     init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials. Reuses the store if store.yml already exists.',
-    plan: 'Show what apply would create, update or delete: markets, products, images, and the store\'s name, policies and theme; missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
-    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/: markets, products, the theme (its settings, and the images in .commercelayer/img/ that the theme and products reference, uploaded when new or changed), name and policies. The store\'s website is live at preview_url after apply. Refuses deletes unless --allow-delete is given. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
+    plan: 'Show what apply would create, update or delete: markets, products, promotions, images, and the store\'s name, policies and theme; warnings flags more than 10 active promotions without a coupon (Commerce Layer applies 10); missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
+    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/: markets, products, promotions, the theme (its settings, and the images in .commercelayer/img/ that the theme and products reference, uploaded when new or changed), name and policies. The store\'s website is live at preview_url after apply. Refuses deletes (products, promotions) unless --allow-delete is given. Flex promotions need the Rules Engine: on an organization without it apply stops with flex_unavailable and applies nothing. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
     'catalog pull': 'Read the products from the catalog source in store.yml (catalog: { source: supabase | sheets | merchant, url, table }) and write them to .commercelayer/products/catalog.csv; then plan and apply as usual. Columns: sku, name, description, image_url, category and one price column per market currency, in lowercase (eur, usd). Supabase reads C11R_SUPABASE_URL and C11R_SUPABASE_KEY (the anon key) from .commercelayer/credentials or the environment; a Google Sheet needs its CSV link or a link anyone can open; a Merchant Center feed is RSS/XML or TSV.',
     'storefront init': 'Custom storefronts only: the hosted theme needs none of this (set theme: in store.yml and apply). Write a static storefront on drop-in.js, no build step: storefront/index.html (the products by category, a minicart that opens on add to cart, the hosted cart and checkout, and a product page at #/p/<sku>), styles.css (theme tokens first) and app.js. Product images are the store\'s, at /img/ (.commercelayer/img/, uploaded by apply); the site\'s own files go in storefront/assets/. Refuses to overwrite unless --force is given.',
     'storefront check': 'Custom storefronts only. Check the published storefront at the preview URL: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides, title, lang, viewport, description, and whether the folder changed since publish. Prints { status, summary, checks: [{ id, kind, status: pass|warn|fail, message, fix, items }] }; exits 1 when a check fails.',
     'storefront publish': 'Custom storefronts only: upload the storefront folder (store.yml storefront.path, default storefront) to the preview URL, where it replaces the hosted theme.',
-    'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline.',
+    'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline. discounts lists what promotions and codes took off; a code that applied nothing is a discount_code_invalid warning in messages.',
     'orders list': 'List the orders placed in the store, newest first, as UCP order entities.',
     'orders show': 'Show one order: c11r orders show <id or number>.',
     'ucp profile': 'Show the store\'s UCP business profile (/.well-known/ucp). With --agent, this CLI\'s own platform profile instead.',
@@ -79,6 +80,16 @@ export async function init(values) {
         next: 'Describe the store in .commercelayer/store.yml (products there or in .commercelayer/products/*.yml|csv, the theme under theme:, images in .commercelayer/img/), then run c11r plan and c11r apply: the website is live at preview_url.',
     };
 }
+/** Warnings plan and apply give about promotions: the active limit, and an API without them. */
+function promotionWarnings(state, desired) {
+    const out = [];
+    if (desired.promotions.length && state.promotions === undefined)
+        out.push('This API does not apply promotions yet: apply will refuse while store.yml has any.');
+    const active = activeWithoutCoupon(desired.promotions);
+    if (active.count > ACTIVE_LIMIT)
+        out.push(`${active.count} promotions without a coupon are active (one per action, in ${active.ids.join(', ')}): Commerce Layer applies at most ${ACTIVE_LIMIT}, the ones with the lowest priority number. Give the rest a coupon, end dates, or enabled: false.`);
+    return out.length ? out : undefined;
+}
 export async function plan() {
     const api = createApi(requireCredentials());
     const desired = loadStore();
@@ -90,6 +101,7 @@ export async function plan() {
         changes,
         deletes: changes.filter((c) => c.action === 'delete' && c.type !== 'asset').length,
         ...imageNotes(assets),
+        warnings: promotionWarnings(state, desired),
         next: assets.missing.length ? 'Put the missing images in .commercelayer/img/ (img/<file> in store.yml is .commercelayer/img/<file>), or fix the references: apply refuses until they are there.' : undefined,
     };
 }
@@ -148,6 +160,9 @@ export async function apply(flags) {
     if (assets.missing.length) {
         fail('missing_images', `The store references images that are not in .commercelayer/img/: ${assets.missing.join('; ')}.`, 'Put the files there (img/<file> in store.yml is .commercelayer/img/<file>), or fix or remove the references, then apply again.');
     }
+    if (desired.promotions.length && state.promotions === undefined) {
+        fail('promotions_unsupported', 'This API does not apply promotions yet.', 'Remove promotions: from store.yml to apply the rest, or update c11r (npx @commercelayer/agent-cli@latest) and try again.');
+    }
     // Images first, so the theme and products never point at a file the store host does not have yet.
     const uploaded = assets.supported ? await uploadAssets(api, assets) : 0;
     const body = {
@@ -156,6 +171,7 @@ export async function apply(flags) {
         name: desired.name,
         policies: desired.policies,
         theme: desired.theme ?? {},
+        promotions: desired.promotions,
         ...(assets.supported && { assets: assets.keep }),
         ...(flags.has('--allow-delete') && { allow_delete: true }),
         ...(flags.has('--full') && { full: true }),
@@ -165,9 +181,10 @@ export async function apply(flags) {
     const done = job ? await follow(api, started) : started;
     if (job && done.apply?.id === job.id && done.apply.status === 'failed') {
         const errors = done.apply.errors;
-        const list = errors.map((e) => (e.sku ? `${e.sku}: ${e.message}` : e.message)).join('; ');
-        const what = errors.length === 1 ? '1 product was refused' : `${errors.length} products were refused`;
-        fail('apply_failed', errors.length ? `${what}: ${list}` : 'The apply failed in Commerce Layer.', 'Fix those products in store.yml or the catalog source and run `c11r apply` again; the rest of the store is unchanged.');
+        const list = errors.map((e) => (e.sku ? `${e.sku}: ${e.message}` : e.promotion && !e.message.startsWith(`promotion ${e.promotion}:`) ? `promotion ${e.promotion}: ${e.message}` : e.message)).join('; ');
+        const promos = errors.filter((e) => e.promotion && !e.sku).length;
+        const what = errors.length === 1 ? (promos ? '1 promotion was refused' : '1 product was refused') : promos === errors.length ? `${errors.length} promotions were refused` : promos ? `${errors.length} items were refused` : `${errors.length} products were refused`;
+        fail('apply_failed', errors.length ? `${what}: ${list}` : 'The apply failed in Commerce Layer.', `Fix ${promos ? 'them' : 'those products'} in store.yml${promos ? '' : ' or the catalog source'} and run \`c11r apply\` again; the rest of the store is unchanged.`);
     }
     return {
         status: 'applied',
@@ -175,6 +192,8 @@ export async function apply(flags) {
         preview_url: done.preview_url,
         markets: desired.markets.length,
         products: desired.products.length,
+        promotions: desired.promotions.length || undefined,
+        warnings: promotionWarnings(state, desired),
         payment_gateway: 'sandbox (test payments only)',
         images_uploaded: uploaded || undefined,
         unused_images: assets.unused.length ? assets.unused : undefined,
@@ -254,8 +273,10 @@ export async function ordersTest(flags, values) {
     return {
         status: p.checkout.status === 'completed' ? 'paid' : p.checkout.status,
         order: p.order,
+        // What the promotions took off, in minor units like the totals; a code that applied nothing is in messages.
+        discounts: (p.checkout.discounts ?? p.ready.discounts)?.applied?.length ? (p.checkout.discounts ?? p.ready.discounts).applied : undefined,
         checkout_id: p.checkout.id,
-        messages: p.checkout.messages,
+        messages: p.checkout.messages ?? p.ready.messages,
         payment_handler: 'ai.commercelayer.sandbox (test payments only)',
         steps: p.steps,
     };

package/dist/promotions.js

@@ -0,0 +1,262 @@
+// promotions: in store.yml. The CLI validates the YAML sugar (single-key rules and actions,
+// categories, date-only days) and sends one normalized object per promotion in PUT /resources;
+// the API maps each to Commerce Layer promotions. Amounts stay in major units, like prices;
+// flex rules pass through as written (Rules Engine syntax, cents).
+import { fail } from './output.js';
+/** Commerce Layer needs both dates: without them the promotion runs from 2000 to 2100. */
+export const DEFAULT_STARTS = '2000-01-01T00:00:00Z';
+export const DEFAULT_ENDS = '2100-01-01T00:00:00Z';
+/** Promotions without a coupon that can be active at once: Commerce Layer's limit. */
+export const ACTIVE_LIMIT = 10;
+const KEYS = ['id', 'name', 'market', 'starts', 'ends', 'limit', 'priority', 'exclusive', 'enabled', 'rules', 'actions', 'flex'];
+const RULES = ['coupon', 'order_amount', 'skus', 'category'];
+const ACTIONS = ['percentage', 'fixed_amount', 'free_shipping', 'fixed_price', 'free_gift', 'buy_x_pay_y'];
+const SHAPE_HINT = 'See the promotions skill for the shape: https://commercelayer.ai/skills/promotions.md';
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const isInt = (v, min) => Number.isInteger(v) && v >= min;
+const list = (v) => (Array.isArray(v) ? v : [v]);
+/** A date or a date-time, as ISO UTC. A bare day starts at 00:00:00Z and ends at 23:59:59Z. */
+function isoDate(v, end, bad) {
+    const s = v instanceof Date ? v.toISOString().replace(/\.000Z$/, 'Z') : String(v);
+    const hint = 'Write a day, 2026-12-01, or a time in UTC, 2026-12-01T09:00:00Z.';
+    if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+        if (Number.isNaN(Date.parse(s)))
+            bad(`"${s}" is not a date.`, hint);
+        return `${s}T${end ? '23:59:59' : '00:00:00'}Z`;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(s) || Number.isNaN(Date.parse(s)))
+        bad(`"${s}" is not a date.`, hint);
+    return new Date(s).toISOString().replace(/\.000Z$/, 'Z');
+}
+/** Validate promotions: and normalize them to the wire shape, or fail invalid_promotion with the path. */
+export function checkPromotions(raw, markets, products) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        fail('invalid_promotion', 'promotions in store.yml is not a list.', `Write promotions as a YAML list under \`promotions:\`, one entry per promotion. ${SHAPE_HINT}`);
+    const skus = new Set(products.map((p) => p.sku));
+    const currencies = new Set(markets.map((m) => m.currency));
+    const ids = new Set();
+    const out = [];
+    raw.forEach((p, i) => {
+        let at = `promotions[${i}]`;
+        const bad = (msg, hint, path = at) => fail('invalid_promotion', `${path}: ${msg}`, hint);
+        if (!isObj(p))
+            bad('is not a map.', `Each promotion is a map with id, rules and actions. ${SHAPE_HINT}`);
+        const pr = p;
+        if (typeof pr.id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(pr.id))
+            bad(`id is ${pr.id === undefined ? 'missing' : `"${String(pr.id)}"`}.`, 'Give every promotion an id of lowercase letters, digits and dashes, such as welcome10. The store identifies the promotion by it: keep it stable.');
+        const id = pr.id;
+        if (ids.has(id))
+            bad(`two promotions have id ${id}.`, 'Give every promotion a unique id.');
+        ids.add(id);
+        at = `promotions[${i}] (${id})`;
+        for (const k of Object.keys(pr))
+            if (!KEYS.includes(k))
+                bad(`unknown key ${k}.`, `A promotion's keys are ${KEYS.join(', ')}.`);
+        const promo = { id, name: pr.name === undefined ? id : String(pr.name), starts: DEFAULT_STARTS, ends: DEFAULT_ENDS, exclusive: false, enabled: true };
+        if (!promo.name.trim() || promo.name.length > 255)
+            bad('name is empty or longer than 255 characters.', 'Write a short name the human will recognize in the dashboard.');
+        let currency;
+        if (pr.market !== undefined) {
+            const m = markets.find((x) => x.code === pr.market);
+            if (!m)
+                bad(`market ${String(pr.market)} is not in markets.`, `Use the code of one of the store's markets: ${markets.map((x) => x.code).join(', ')}.`);
+            promo.market = m.code;
+            currency = m.currency;
+        }
+        if (pr.starts !== undefined)
+            promo.starts = isoDate(pr.starts, false, (m, h) => bad(`starts ${m}`, h));
+        if (pr.ends !== undefined)
+            promo.ends = isoDate(pr.ends, true, (m, h) => bad(`ends ${m}`, h));
+        if (Date.parse(promo.ends) <= Date.parse(promo.starts))
+            bad('ends is not after starts.', 'Make the end date later than the start date.');
+        if (pr.limit !== undefined) {
+            if (!isInt(pr.limit, 1))
+                bad(`limit is ${String(pr.limit)}.`, 'limit is the total number of uses, a whole number of 1 or more.');
+            promo.limit = pr.limit;
+        }
+        if (pr.priority !== undefined) {
+            if (!isInt(pr.priority, 1))
+                bad(`priority is ${String(pr.priority)}.`, 'priority is a whole number of 1 or more; the lowest runs first.');
+            promo.priority = pr.priority;
+        }
+        for (const k of ['exclusive', 'enabled']) {
+            if (pr[k] !== undefined && typeof pr[k] !== 'boolean')
+                bad(`${k} is ${String(pr[k])}.`, `${k} is true or false.`);
+            if (pr[k] !== undefined)
+                promo[k] = pr[k];
+        }
+        if (pr.flex !== undefined) {
+            if (pr.rules !== undefined || pr.actions !== undefined)
+                bad('has flex and rules or actions.', 'A flex promotion keeps its rules and actions inside flex: remove the other rules and actions, or remove flex.');
+            const f = pr.flex;
+            if (!isObj(f) || !Array.isArray(f.rules) || f.rules.length === 0)
+                bad('flex has no rules.', 'Write flex: { rules: [...] }, each rule with conditions and actions. See docs.commercelayer.io/rules-engine.');
+            f.rules.forEach((r, j) => {
+                const path = `${at}.flex.rules[${j}]`;
+                if (!isObj(r) || !Array.isArray(r.conditions) || !r.conditions.length || !Array.isArray(r.actions) || !r.actions.length)
+                    bad('needs a list of conditions and a list of actions.', 'Each flex rule has conditions (field, matcher, value) and actions (type, selector, value).', path);
+            });
+            promo.flex = f;
+            out.push(promo);
+            return;
+        }
+        // Rules: a list of single-key maps; none means every order.
+        const rules = {};
+        let ruleSkus;
+        const seen = new Set();
+        const resolve = (v, kind, path) => {
+            if (kind === 'category') {
+                const name = String(v).split('>').map((s) => s.trim()).filter(Boolean).join(' > ');
+                const found = products.filter((x) => x.category === name || x.category?.startsWith(`${name} > `)).map((x) => x.sku);
+                if (!name || !found.length)
+                    bad(`no product is in category "${String(v)}".`, `Use a category of the store's products, written as in the products: ${[...new Set(products.map((x) => x.category).filter(Boolean))].join(', ') || 'none has a category yet'}.`, path);
+                return found.sort();
+            }
+            const l = list(v).map(String);
+            if (!l.length)
+                bad('skus is empty.', 'List one or more SKUs.', path);
+            for (const s of l)
+                if (!skus.has(s))
+                    bad(`${s} is not a product.`, 'Use SKUs of the store\'s products.', path);
+            return [...new Set(l)].sort();
+        };
+        const rawRules = pr.rules === undefined ? [] : pr.rules;
+        if (!Array.isArray(rawRules))
+            bad('rules is not a list.', `Write rules as a list: rules: [{ coupon: CODE }]. ${SHAPE_HINT}`);
+        rawRules.forEach((r, j) => {
+            const path = `${at}.rules[${j}]`;
+            if (!isObj(r) || Object.keys(r).length !== 1)
+                bad('is not a single rule.', `Each rule is one of ${RULES.join(', ')}, written as a one-key map: { coupon: CODE }.`, path);
+            const [k, v] = Object.entries(r)[0];
+            if (!RULES.includes(k))
+                bad(`unknown rule ${k}.`, `Rules are ${RULES.join(', ')}. For anything else, write a flex promotion.`, path);
+            const kind = k === 'category' ? 'skus' : k;
+            if (seen.has(kind))
+                bad(`has two ${kind === 'skus' ? 'skus or category' : k} rules.`, kind === 'skus' ? 'Use skus or category once per promotion: list every SKU in one rule, or make two promotions.' : `Use one ${k} rule per promotion; a coupon rule takes a list of codes.`, path);
+            seen.add(kind);
+            if (k === 'coupon') {
+                const l = list(v).map(String);
+                for (const c of l) {
+                    if (!/^[A-Za-z0-9_-]{8,40}$/.test(c))
+                        bad(`coupon "${c}" is not 8 to 40 letters, digits, - or _.`, 'Commerce Layer codes have 8 to 40 characters: WELCOME10, not WELCOME.', path);
+                }
+                if (!l.length)
+                    bad('coupon has no code.', 'Write coupon: CODE, or a list of codes.', path);
+                rules.coupons = [...new Set(l)];
+            }
+            else if (k === 'order_amount') {
+                if (isObj(v) && v.max !== undefined)
+                    bad('order_amount has a max.', 'Commerce Layer promotions match a minimum order amount only: remove max, or write a flex promotion.', path);
+                if (!isObj(v) || Object.keys(v).some((x) => x !== 'min') || !isNum(v.min) || v.min <= 0)
+                    bad('order_amount needs min, a positive amount.', 'Write order_amount: { min: 50 }, the minimum items total, in the market currency, in major units.', path);
+                rules.order_amount = { min: v.min };
+            }
+            else {
+                ruleSkus = resolve(v, k, path);
+                rules.skus = ruleSkus;
+            }
+        });
+        // Actions: one or more, a single-key map or the bare free_shipping.
+        if (!Array.isArray(pr.actions) || pr.actions.length === 0)
+            bad('has no actions.', `Add actions: what the promotion does, such as actions: [{ percentage: 10 }]. ${SHAPE_HINT}`);
+        const actions = [];
+        const types = new Set();
+        let needsCurrency = Boolean(rules.order_amount);
+        pr.actions.forEach((a, j) => {
+            const path = `${at}.actions[${j}]`;
+            const entry = a === 'free_shipping' ? { free_shipping: true } : a;
+            if (!isObj(entry))
+                bad('is not an action.', `Each action is one of ${ACTIONS.join(', ')}: { percentage: 10 }, or free_shipping.`, path);
+            const [k, v] = Object.entries(entry)[0] ?? [];
+            if (!ACTIONS.includes(k))
+                bad(`unknown action ${k ?? '(none)'}.`, `Actions are ${ACTIONS.join(', ')}. For anything else, write a flex promotion.`, path);
+            if (types.has(k))
+                bad(`has two ${k} actions.`, 'Use each action once per promotion.', path);
+            types.add(k);
+            const extra = Object.keys(entry).filter((x) => x !== k);
+            // Targets: skus or category next to the action, or inside its map; else the rule's.
+            const target = (o, required) => {
+                if (o.skus !== undefined && o.category !== undefined)
+                    bad('has skus and category.', 'Use one of them.', path);
+                if (o.skus !== undefined)
+                    return resolve(o.skus, 'skus', path);
+                if (o.category !== undefined)
+                    return resolve(o.category, 'category', path);
+                if (required && !ruleSkus)
+                    bad(`${k} needs the SKUs it applies to.`, `Add skus: [...] or category: ... to the action, or a skus or category rule.`, path);
+                return ruleSkus;
+            };
+            const only = (o, allowed) => {
+                for (const x of Object.keys(o))
+                    if (!allowed.includes(x))
+                        bad(`unknown key ${x} in ${k}.`, `${k} takes ${allowed.join(', ')}.`, path);
+            };
+            if (k === 'percentage') {
+                only(entry, ['percentage', 'skus', 'category']);
+                if (!isNum(v) || v <= 0 || v > 100)
+                    bad(`percentage is ${String(v)}.`, 'percentage is a number above 0 and up to 100: 10 is 10% off. To make shipping free, use free_shipping.', path);
+                const t = target(entry, false);
+                actions.push({ type: 'percentage', value: v, ...(t ? { skus: t } : {}) });
+            }
+            else if (k === 'fixed_amount') {
+                only(entry, ['fixed_amount']);
+                if (!isNum(v) || v <= 0)
+                    bad(`fixed_amount is ${String(v)}.`, 'fixed_amount is the amount off the order, in major units: 5 is 5 euros.', path);
+                actions.push({ type: 'fixed_amount', value: v });
+                needsCurrency = true;
+            }
+            else if (k === 'free_shipping') {
+                if (extra.length || (v !== true && v !== null && !(isObj(v) && !Object.keys(v).length)))
+                    bad('free_shipping takes no settings.', 'Write free_shipping on its own.', path);
+                actions.push({ type: 'free_shipping' });
+            }
+            else {
+                if (extra.length)
+                    bad(`${k} has keys next to it: ${extra.join(', ')}.`, `Put them inside: ${k}: { ... }.`, path);
+                if (!isObj(v))
+                    bad(`${k} is not a map.`, SHAPE_HINT, path);
+                const o = v;
+                if (k === 'fixed_price') {
+                    only(o, ['price', 'skus', 'category']);
+                    if (!isNum(o.price) || o.price <= 0)
+                        bad(`fixed_price.price is ${String(o.price)}.`, 'price is the price the SKUs sell at, in major units: 9.90.', path);
+                    actions.push({ type: 'fixed_price', price: o.price, skus: target(o, true) });
+                    needsCurrency = true;
+                }
+                else if (k === 'free_gift') {
+                    only(o, ['skus', 'category', 'quantity']);
+                    if (o.skus === undefined && o.category === undefined)
+                        bad('free_gift needs the SKUs given away.', 'Write free_gift: { skus: [GIFT-SKU], quantity: 1 }.', path);
+                    if (o.quantity !== undefined && !isInt(o.quantity, 1))
+                        bad(`free_gift.quantity is ${String(o.quantity)}.`, 'quantity is a whole number of 1 or more.', path);
+                    actions.push({ type: 'free_gift', skus: target(o, true), quantity: o.quantity ?? 1 });
+                }
+                else {
+                    only(o, ['x', 'y', 'cheapest_free', 'skus', 'category']);
+                    if (!isInt(o.x, 2) || !isInt(o.y, 1) || o.y >= o.x)
+                        bad(`buy_x_pay_y is x ${String(o.x)}, y ${String(o.y)}.`, 'x and y are whole numbers with x above y and y at least 1: { x: 3, y: 2 } is 3 for 2.', path);
+                    if (o.cheapest_free !== undefined && typeof o.cheapest_free !== 'boolean')
+                        bad('cheapest_free is not true or false.', 'cheapest_free is true or false.', path);
+                    actions.push({ type: 'buy_x_pay_y', x: o.x, y: o.y, cheapest_free: o.cheapest_free ?? false, skus: target(o, true) });
+                }
+            }
+        });
+        if (needsCurrency && !currency && currencies.size > 1)
+            bad('has an amount but no market, in a store with several currencies.', 'Set market: so the amount has a currency, or use a percentage.');
+        promo.rules = rules;
+        promo.actions = actions;
+        out.push(promo);
+    });
+    return out;
+}
+/**
+ * Commerce Layer promotions active without a coupon: each action of an enabled promotion that
+ * has not ended is one (the API makes one per action). Commerce Layer applies at most 10.
+ */
+export function activeWithoutCoupon(promotions, now = Date.now()) {
+    const live = promotions.filter((p) => p.enabled && !p.flex && !p.rules?.coupons && Date.parse(p.ends) > now);
+    return { count: live.reduce((n, p) => n + (p.actions?.length ?? 1), 0), ids: live.map((p) => p.id) };
+}

package/dist/store.js

@@ -8,6 +8,7 @@ import YAML from 'yaml';
 import { fail } from './output.js';
 import { paths } from './files.js';
 import { productFiles, readProductFile } from './products.js';
+import { checkPromotions } from './promotions.js';
 /** The keys a product may have. Stock is not one: inventory lives in Commerce Layer. */
 export const PRODUCT_KEYS = ['sku', 'name', 'description', 'image_url', 'category', 'prices'];
 export const THEME_KEYS = ['color', 'logo', 'hero', 'tagline'];
@@ -61,6 +62,18 @@ theme:
   # hero: img/hero.jpg   # the home page's wide image; without it a band in the accent
   # tagline: Small-batch coffee, roasted in Milan   # at most 120 characters
 
+promotions:
+  # Discount codes and automatic discounts: rules (when) and actions (what).
+  # The id is unique and stable. Amounts are in the market currency, like prices.
+  # - id: welcome10
+  #   name: Welcome, 10% off
+  #   rules: [{ coupon: WELCOME10 }]      # codes have 8 to 40 characters
+  #   actions: [{ percentage: 10 }]
+  # - id: free-shipping-50
+  #   market: eu
+  #   rules: [{ order_amount: { min: 50 } }]
+  #   actions: [free_shipping]
+
 storefront:
   # Only for a custom storefront (your own web app in this repo, published with
   # c11r storefront publish): it replaces the theme. Its folder, from the repo root.
@@ -144,7 +157,8 @@ export function loadStore() {
     const theme = checkTheme(doc.theme);
     const currencies = [...new Set(markets.map((m) => m.currency))];
     const products = checkProducts(sourced, currencies);
-    return { name: doc.name, markets, products, storefront: doc.storefront, policies, theme };
+    const promotions = checkPromotions(doc.promotions, markets, products);
+    return { name: doc.name, markets, products, storefront: doc.storefront, policies, theme, promotions };
 }
 /** The product rules, shared by loadStore and catalog pull: errors name each product's source. */
 export function checkProducts(sourced, currencies) {
@@ -231,7 +245,15 @@ export function diff(state, desired) {
             changes.push({ action: 'update', type: 'store', id: 'name' });
         if (state.policies !== undefined && canonical(state.policies) !== canonical(desired.policies))
             changes.push({ action: 'update', type: 'store', id: 'policies' });
-        if (state.theme !== undefined && canonical(state.theme) !== canonical(desired.theme))
+    }
+    // The theme is listed like a resource: a create when the store has none yet (first apply
+    // included), an update when it changes. An API that does not know themes (undefined) is skipped.
+    const hasTheme = (t) => Boolean(t && Object.keys(t).length);
+    if (!applied || state.theme !== undefined) {
+        const before = applied ? state.theme : null;
+        if (!hasTheme(before) && hasTheme(desired.theme))
+            changes.push({ action: 'create', type: 'store', id: 'theme' });
+        else if (hasTheme(before) && canonical(before) !== canonical(desired.theme))
             changes.push({ action: 'update', type: 'store', id: 'theme' });
     }
     const after = toApplied(desired);
@@ -248,5 +270,19 @@ export function diff(state, desired) {
             if (!(id in after[kind]))
                 changes.push({ action: 'delete', type, id });
     }
+    // Promotions, by id. An API that does not know them (undefined) is skipped: apply refuses instead.
+    if (!applied || state.promotions !== undefined) {
+        const before = (applied ? state.promotions : undefined) ?? {};
+        const want = Object.fromEntries((desired.promotions ?? []).map((p) => [p.id, p]));
+        for (const id of Object.keys(want)) {
+            if (!(id in before))
+                changes.push({ action: 'create', type: 'promotion', id });
+            else if (canonical(before[id]) !== canonical(want[id]))
+                changes.push({ action: 'update', type: 'promotion', id });
+        }
+        for (const id of Object.keys(before))
+            if (!(id in want))
+                changes.push({ action: 'delete', type: 'promotion', id });
+    }
     return changes;
 }

package/dist/ucp/buy.js

@@ -68,6 +68,8 @@ export async function buy(origin, opts = {}) {
             const why = (checkout.messages ?? []).filter((m) => m.type === 'error').map((m) => `${m.code} at ${m.path}: ${m.content}`).join('; ');
             fail('checkout_not_ready', `The checkout is ${checkout.status}: ${why}`, 'Fix the store (markets, countries, prices) and run the command again.');
         }
+        // The checkout as it was before paying: its warnings (a code that applied nothing) and discounts.
+        const ready = checkout;
         const completeCall = await shopping.completeCheckout(store, checkout.id, { payment: { instruments: [sandboxInstrument(opts.decline)] }, signals: TEST_SIGNALS });
         checkout = note(steps, 'pay', completeCall, '');
         steps[steps.length - 1].result = checkout.status === 'completed' ? `completed, order ${checkout.order.id}` : `${checkout.status}: ${(checkout.messages ?? []).map((m) => m.code).join(', ')}`;
@@ -76,7 +78,7 @@ export async function buy(origin, opts = {}) {
             order = note(steps, 'order', await shopping.getOrder(store, checkout.order.id), '');
             steps[steps.length - 1].result = `${order.label}, ${order.line_items.length} line item(s), ${order.totals.at(-1).amount} ${order.currency}`;
         }
-        return { store, steps, checkout, order };
+        return { store, steps, checkout, ready, order };
     }
     catch (e) {
         if (e instanceof UcpError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [