@spree/docs 0.1.7 → 0.1.9

package/dist/developer/core-concepts/orders.md

@@ -238,23 +238,23 @@ Apply or remove promotional coupon codes during checkout:
 
 
 ```typescript SDK
-// Apply a coupon
-await client.carts.couponCodes.apply(cartId, 'SAVE20')
+// Apply a discount code
+await client.carts.discountCodes.apply(cartId, 'SAVE20')
 
-// Remove a coupon
-await client.carts.couponCodes.remove(cartId, 'SAVE20')
+// Remove a discount code
+await client.carts.discountCodes.remove(cartId, 'SAVE20')
 ```
 
 ```bash cURL
-# Apply a coupon
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/coupon_codes' \
+# Apply a discount code
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes' \
   -H 'Authorization: Bearer spree_pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "code": "SAVE20" }'
 
-# Remove a coupon
-curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/coupon_codes/SAVE20' \
+# Remove a discount code
+curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes/SAVE20' \
   -H 'Authorization: Bearer spree_pk_xxx' \
   -H 'X-Spree-Token: abc123'
 ```

package/dist/developer/core-concepts/promotions.md

@@ -278,13 +278,13 @@ Customers apply coupon codes during checkout via the Store API:
 
 
 ```typescript SDK
-// Apply a coupon code to the cart
-const cart = await client.carts.couponCodes.apply('cart_abc123', 'SUMMER20', {
+// Apply a discount code to the cart
+const cart = await client.carts.discountCodes.apply('cart_abc123', 'SUMMER20', {
   spreeToken: '<token>',
 })
 
-// Remove a coupon code from the cart
-await client.carts.couponCodes.remove('cart_abc123', 'SUMMER20', {
+// Remove a discount code from the cart
+await client.carts.discountCodes.remove('cart_abc123', 'SUMMER20', {
   spreeToken: '<token>',
 })
 ```

package/dist/developer/core-concepts/search-filtering.md

@@ -73,9 +73,14 @@ const { data: products } = await client.categories.products.list('clothing/shirt
   limit: 12,
 })
 
-// Or filter by category ID
+// Or filter by category ID (includes descendants)
 const { data: products } = await client.products.list({
-  categories_id_eq: 'ctg_xxx',
+  in_category: 'ctg_xxx',
+})
+
+// Multiple categories (OR logic, checkbox filters)
+const { data: products } = await client.products.list({
+  in_categories: ['ctg_shirts', 'ctg_pants'],
 })
 ```
 
@@ -84,8 +89,12 @@ const { data: products } = await client.products.list({
 curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
   -H 'Authorization: Bearer spree_pk_xxx'
 
-# Filter by category ID
-curl 'https://api.mystore.com/api/v3/store/products?q[categories_id_eq]=ctg_xxx' \
+# Filter by category ID (includes descendants)
+curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \
+  -H 'Authorization: Bearer spree_pk_xxx'
+
+# Multiple categories (OR logic)
+curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirts&q[in_categories][]=ctg_pants' \
   -H 'Authorization: Bearer spree_pk_xxx'
 ```
 

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -248,15 +248,21 @@ Gift cards are applied using the same coupon codes endpoint as promotion codes.
 
 ```typescript SDK
 // Apply gift card code to cart (works for guests and registered customers)
-const cart = await client.carts.couponCodes.apply('cart_abc123', 'abc1234def', {
+// Gift cards use a dedicated endpoint — they reduce amount_due, not total
+const cart = await client.carts.giftCards.apply('cart_abc123', 'abc1234def', {
+  spreeToken: '<token>',
+})
+
+// Remove gift card (ID from cart.gift_card.id)
+await client.carts.giftCards.remove('cart_abc123', cart.gift_card.id, {
   spreeToken: '<token>',
 })
 ```
 
 ```bash cURL
 # Apply gift card to cart (works for guests and registered customers)
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/coupon_codes' \
-  -H 'Authorization: Bearer spree_pk_xxx' \
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/gift_cards' \
+  -H 'X-Spree-Api-Key: pk_xxx' \
   -H 'X-Spree-Token: <token>' \
   -H 'Content-Type: application/json' \
   -d '{ "code": "abc1234def" }'

package/dist/developer/core-concepts/webhooks.md

@@ -163,22 +163,56 @@ Each webhook request includes these headers:
 
 ### Verifying Webhook Signatures
 
-To ensure webhooks are genuinely from your Spree store, verify the signature:
+To ensure webhooks are genuinely from your Spree store, verify the signature.
+
+#### Next.js (recommended)
+
+Use `@spree/next/webhooks` for a ready-made Route Handler:
+
+```typescript
+// src/app/api/webhooks/spree/route.ts
+import { createWebhookHandler } from '@spree/next/webhooks'
+
+export const POST = createWebhookHandler({
+  secret: process.env.SPREE_WEBHOOK_SECRET!,
+  handlers: {
+    'order.completed': async (event) => {
+      // event.data is the order payload (same shape as Store API)
+      await sendOrderConfirmationEmail(event.data)
+    },
+    'order.canceled': async (event) => {
+      await sendCancellationEmail(event.data)
+    },
+  },
+})
+```
 
-```ruby
-# In your webhook receiver
-def verify_webhook(request)
-  payload = request.body.read
-  signature = request.headers['X-Spree-Webhook-Signature']
-  secret_key = ENV['SPREE_WEBHOOK_SECRET'] # Your endpoint's secret_key
+#### Any JavaScript/TypeScript framework
 
-  expected = OpenSSL::HMAC.hexdigest('SHA256', secret_key, payload)
+Use `@spree/sdk/webhooks` for framework-agnostic verification:
 
-  ActiveSupport::SecurityUtils.secure_compare(signature, expected)
-end
+```typescript
+import { verifyWebhookSignature } from '@spree/sdk/webhooks'
+import type { WebhookEvent } from '@spree/sdk/webhooks'
+import type { Order } from '@spree/sdk'
+
+// Hono, Cloudflare Workers, or any Web Fetch API-based framework
+app.post('/webhooks/spree', async (req, res) => {
+  const body = await req.text()
+  const signature = req.headers['x-spree-webhook-signature']
+  const timestamp = req.headers['x-spree-webhook-timestamp']
+
+  if (!verifyWebhookSignature(body, signature, timestamp, process.env.SPREE_WEBHOOK_SECRET!)) {
+    return res.status(401).json({ error: 'Invalid signature' })
+  }
+
+  const event: WebhookEvent<Order> = JSON.parse(body)
+  // handle event...
+  res.json({ received: true })
+})
 ```
 
-Example in a Rails controller:
+#### Ruby
 
 ```ruby
 class WebhooksController < ApplicationController
@@ -209,7 +243,8 @@ class WebhooksController < ApplicationController
     request.body.rewind
 
     signature = request.headers['X-Spree-Webhook-Signature']
-    expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['SPREE_WEBHOOK_SECRET'], payload)
+    timestamp = request.headers['X-Spree-Webhook-Timestamp']
+    expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['SPREE_WEBHOOK_SECRET'], "#{timestamp}.#{payload}")
 
     ActiveSupport::SecurityUtils.secure_compare(signature.to_s, expected)
   end

package/dist/developer/sdk/quickstart.md

@@ -61,13 +61,15 @@ The SDK uses a resource builder pattern for nested resources:
 | `carts` | `paymentMethods` | `list` |
 | `carts` | `paymentSessions` | `create`, `get`, `update`, `complete` |
 | `carts` | `fulfillments` | `list`, `update` |
-| `carts` | `couponCodes` | `apply`, `remove` |
+| `carts` | `discountCodes` | `apply`, `remove` |
+| `carts` | `giftCards` | `apply`, `remove` |
 | `carts` | `storeCredits` | `apply`, `remove` |
 | `customer` | `addresses` | `list`, `get`, `create`, `update`, `delete`, `markAsDefault` |
 | `customer` | `creditCards` | `list`, `get`, `delete` |
 | `customer` | `giftCards` | `list`, `get` |
 | `customer` | `orders` | `list` |
 | `customer` | `paymentSetupSessions` | `create`, `get`, `complete` |
+| `policies` | — | `list`, `get` |
 | `categories` | `products` | `list` |
 | `wishlists` | `items` | `create`, `update`, `delete` |
 

package/dist/developer/sdk/store/cart-checkout.md

@@ -55,16 +55,26 @@ await client.carts.items.update(cartId, lineItemId, {
 await client.carts.items.delete(cartId, lineItemId, options);
 ```
 
-### Coupon Codes
+### Discount Codes
 
 ```typescript
 const options = { spreeToken: cart.token };
 
-// Apply a coupon code
-await client.carts.couponCodes.apply(cartId, 'SAVE20', options);
+// Apply a discount code
+await client.carts.discountCodes.apply(cartId, 'SAVE20', options);
 
-// Remove a coupon code
-await client.carts.couponCodes.remove(cartId, 'SUMMER20', options);
+// Remove a discount code
+await client.carts.discountCodes.remove(cartId, 'SAVE20', options);
+```
+
+### Gift Cards
+
+```typescript
+// Apply a gift card (reduces amount_due, not total)
+const cart = await client.carts.giftCards.apply(cartId, 'GC-ABCD-1234', options);
+
+// Remove a gift card (ID from cart.gift_card.id)
+await client.carts.giftCards.remove(cartId, 'gc_abc123', options);
 ```
 
 ## Checkout

package/dist/developer/storefront/nextjs/spree-next-package.md

@@ -20,6 +20,9 @@ Set environment variables and the client initializes automatically:
 ```env
 SPREE_API_URL=https://api.mystore.com
 SPREE_PUBLISHABLE_KEY=spree_pk_xxx
+
+# Required for webhook-based emails (see Webhooks section below)
+SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
 ```
 
 ### Explicit initialization
@@ -120,19 +123,21 @@ Checkout functions use the implicit cart resolved from cookies. No `orderId` is
 import {
   getCheckout,
   updateCheckout,
-  getFulfillments,
   selectDeliveryRate,
-  applyCoupon,
-  removeCoupon,
+  applyDiscountCode,
+  removeDiscountCode,
+  applyGiftCard,
+  removeGiftCard,
   complete,
 } from '@spree/next';
 
 const checkout = await getCheckout();
 await updateCheckout({ shipping_address: { ... }, billing_address: { ... } });
-const fulfillments = await getFulfillments();
 await selectDeliveryRate(fulfillmentId, deliveryRateId);
-await applyCoupon('SAVE20');
-await removeCoupon(promotionId);
+await applyDiscountCode('SAVE20');
+await removeDiscountCode('SAVE20');
+await applyGiftCard('GC-ABCD-1234');
+await removeGiftCard('gc_abc123');
 await complete();
 ```
 
@@ -282,6 +287,48 @@ const products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR'
 const category = await getCategory('clothing/shirts', {}, { locale: 'de', country: 'DE' });
 ```
 
+## Webhooks
+
+Handle Spree webhook events in your Next.js app with `@spree/next/webhooks`:
+
+```typescript
+// src/app/api/webhooks/spree/route.ts
+import { createWebhookHandler } from '@spree/next/webhooks'
+
+export const POST = createWebhookHandler({
+  secret: process.env.SPREE_WEBHOOK_SECRET!,
+  handlers: {
+    'order.completed': async (event) => {
+      await sendOrderConfirmationEmail(event.data)
+    },
+    'order.canceled': async (event) => {
+      await sendCancellationEmail(event.data)
+    },
+    'order.shipped': async (event) => {
+      await sendShippingNotification(event.data)
+    },
+    'customer.password_reset_requested': async (event) => {
+      await sendPasswordResetEmail(event.data)
+    },
+  },
+})
+```
+
+The handler verifies HMAC-SHA256 signatures, rejects replayed requests, routes events to your handlers, and returns 200 immediately (handlers run async).
+
+### Local development
+
+Webhooks require a publicly accessible URL. Use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/) for local development:
+
+```bash
+brew install cloudflared
+cloudflared tunnel --url http://localhost:3001
+```
+
+Then create a webhook endpoint in **Spree Admin → Settings → Developers → Webhooks** pointing to your tunnel URL + `/api/webhooks/spree`.
+
+For more details, see [Webhooks](../../core-concepts/webhooks.md).
+
 ## TypeScript
 
 All types are re-exported from `@spree/sdk`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",