@craftware/crafty-sdk 0.10.4 → 0.12.0

package/skills/crafty-cms/references/online-store.md

@@ -117,6 +117,44 @@ An order can be read back with its token, which is in the order page link (`?t=`
 const order = await crafty.orders.get("CM-1001", token);
 ```
 
+## Discount coupons
+
+The merchant creates codes in the panel (**Cupones**), with `upsert_coupon` or `POST /api/v1/coupons`. One coupon per order:
+
+- Types: `percent` (with an optional `max_discount`), `fixed` (an amount) or `free_delivery`.
+- A coupon applies to all products or to chosen ones (`applies_to: "entries"` plus product slugs).
+- Optional limits: `min_subtotal` (the product subtotal before delivery), `max_uses`, `max_uses_per_email`, `starts_at` and `ends_at` (whole days in store time), and `is_active`.
+
+The visitor types the code on the hosted checkout. It shows the discount, or the reason the code doesn't apply.
+
+- The discount is spread over the lines before taxes.
+- "Free delivery from" looks at the subtotal after the discount.
+- A cancelled order gives its use back.
+- An order with nothing left to pay is marked paid with `payment_method: "none"`.
+
+To carry a code from a shared link (`https://monteverde.do/?cupon=BIENVENIDA10`) to the checkout:
+
+```ts
+cart.captureCoupon(); // on page load: keeps ?cupon= (or ?coupon=) in the cart
+const quote = await crafty.orders.quote(cart.items(), { coupon: cart.coupon() });
+// quote.discount_total, quote.delivery_discount, quote.coupon, quote.coupon_error { reason, message, missing }
+await crafty.checkout.start(cart.items(), { coupon: cart.coupon() });
+```
+
+Show `quote.coupon_error.message` as it is: it is already in the visitor's language. Possible `reason` values:
+
+- `not_found`
+- `paused`
+- `not_started`
+- `expired`
+- `exhausted`
+- `used_by_email`
+- `minimum` (with `missing`, the amount the cart still needs)
+- `not_eligible`
+- `too_many_attempts`
+
+Failed codes are rate limited per visitor. The cart forgets the code once the order is placed. Orders, webhooks and `orders.get()` carry `discount_total`, `delivery_discount`, `coupon` and each line's `discount`.
+
 ## 5. Orders and notifications
 
 - Each order gets a number per environment (`<prefix>1001`, `1002`, …), status **Nuevo**, payment **Pendiente**.
@@ -144,8 +182,8 @@ No API key is required; the site is in the URL. Errors use the usual `{ error, m
 | Method | Path | Notes |
 | --- | --- | --- |
 | GET | `/api/v1/sites/{site}/store` | Public settings. |
-| POST | `/api/v1/sites/{site}/orders/quote` | Body `{ items: [{ slug, variant?, quantity }], fulfillment?: "delivery" \| "pickup", locale? }`. |
-| POST | `/api/v1/sites/{site}/checkout` | Body `{ items, return_url?, cancel_url?, fields?, fulfillment?, locale? }` → 201 `{ data: { id, url, expires_at } }`. |
+| POST | `/api/v1/sites/{site}/orders/quote` | Body `{ items: [{ slug, variant?, quantity }], fulfillment?: "delivery" \| "pickup", locale?, coupon?, email? }`. |
+| POST | `/api/v1/sites/{site}/checkout` | Body `{ items, return_url?, cancel_url?, fields?, fulfillment?, locale?, coupon? }` → 201 `{ data: { id, url, expires_at } }`. |
 | GET | `/api/v1/sites/{site}/orders/{number}` | Token in `?token=` or `X-Order-Token`. |
 | GET | `/api/v1/sites/{site}/checkout/{id}` | `{ data: { placed } }`: whether the session became an order; 404 once pruned. |
 
@@ -158,9 +196,12 @@ For an ERP, POS or backend: an OAuth token (the same as MCP) with `crafty:read`
 | Method | Path | Notes |
 | --- | --- | --- |
 | GET | `/api/v1/orders` | Filters `status`, `payment_status`, `metadata[erp_id]=…` (up to 5 pairs), `per_page` (max 100). |
-| POST | `/api/v1/orders` | Body like `create_order`: `customer`, `fulfillment`, `address?`, `payment_method`, `items`, `fields?`, `metadata?`, `locale?`, `expected_total?` → 201. |
+| POST | `/api/v1/orders` | Body like `create_order`: `customer`, `fulfillment`, `address?`, `payment_method`, `items`, `fields?`, `metadata?`, `locale?`, `expected_total?`, `coupon?` → 201. |
 | GET | `/api/v1/orders/{number}` | The order with `payment_url` (the customer's order page), `fields`, `metadata`, `next_statuses` and `events`. |
-| PATCH | `/api/v1/orders/{number}` | Edit keys (`items` with `id` for existing lines, `quantity: 0` removes), plus `status`, `paid`, `payment_reference`, `internal_note`, `notify`. Returns the order and `applied`. |
+| PATCH | `/api/v1/orders/{number}` | Edit keys (`items` with `id` for existing lines, `quantity: 0` removes, `coupon` to add, keep or remove a code with `null`, `coupon_below_minimum: "keep" \| "remove"`), plus `status`, `paid`, `payment_reference`, `internal_note`, `notify`. Returns the order and `applied`. |
+| GET | `/api/v1/coupons` | The environment's coupons with `status`, `uses`, `orders`, `sales` and `discounted`. Editors need the `coupons` permission. |
+| POST | `/api/v1/coupons` | Body like `upsert_coupon`: `code`, `type`, `value`, `max_discount?`, `min_subtotal?`, `applies_to?`, `products?`, `max_uses?`, `max_uses_per_email?`, `starts_at?`, `ends_at?`, `is_active?` → 201. |
+| GET / PATCH / DELETE | `/api/v1/coupons/{code}` | Read, change (only the keys sent) or delete. A used coupon keeps its code and type, and DELETE pauses it instead. |
 
 Rejections use `{ error, message }` with the code (`PRICE_CHANGED` is 409 and includes the new `quote`).