# SmartCut — full documentation

> Cloud-based cutlist optimization API + hosted cut-to-size e-commerce. Source: https://smartcut.dev

---
# SmartCut API Documentation

URL: https://smartcut.dev/docs

> Cloud-based cutting-optimization platform: REST API, embeddable calculator, hosted e-commerce, WordPress plugin and embedded diagrams.

SmartCut is a cloud platform for **material cutting optimization**. Send it a list of parts and stock, and it returns efficient cutting layouts for sheet, linear and roll materials. Kerf, grain, trim, edge-banding, machining and saw constraints are all handled server-side, by the same optimisation engine that powers [Cutlist Evolution](https://cutlistevo.com).

You can consume it however suits your product.

- **REST API**. Submit a calculation, poll for the result, then export to PDF, DXF, SVG, CSV, labels and machine formats (PTX, Biesse, Mayer …). Processing is async, several algorithms are available, and the response carries full metadata.
- **Embedded JavaScript calculator**. Drop a cut-to-size pricing and quoting widget straight into your own checkout.
- **Embedded diagram**. Show an interactive cutting layout on any page with a single `<iframe>`.
- **Hosted e-commerce**. A complete cut-to-size storefront with Stripe payments, stock and orders, and no development.
- **WordPress / WooCommerce plugin**. The same cut-to-size selling experience inside WordPress.

## Explore the docs

- [API Reference](/docs/api) covers endpoints, request/response schema and authentication.
- [Guide](/docs/guide) explains the concepts, the terminology, and how to model your cutting jobs.
- [MCP server](/docs/mcp) runs optimisations from Claude, Cursor or your own LLM client.
- [Updates](/docs/updates) is the REST API changelog.
- [Hosted store](/docs/ecommerce) documents the analytics, webhooks and order-management APIs behind the hosted storefront.
- [Embedded checkout](/docs/ecommerce-checkout) is the client-side embedded calculator and checkout.
- [Store config MCP](/docs/ecommerce-mcp) configures your storefront from an LLM client.
- [Embedded diagram](/docs/embed) lists the iframe parameters, colours and messages, and how to render a result JSON you host yourself.
- [WordPress plugin](/docs/wordpress-plugin) walks through installation and configuration.

## Interactive API reference

Browse and try every endpoint live:

- [**API v3**](/api-docs/v3) is the current version.
- [API v2](/api-docs/v2) is maintained, and [API v1](/api-docs/v1) is deprecated.
- [Inventory & orders](/api-docs/ecommerce) holds the hosted store's materials, stock and order endpoints.

## Get started

1. **[Create an account](https://smartcut.dev/account)** and grab your API key.
2. Read the **[Guide](/docs/guide)** to model your stock, parts and saw.
3. Make your first call against the **[v3 reference](/api-docs/v3)**. Submit a calculation, then fetch the result.
4. **[Export](/docs/api)** the layout to your preferred format, or embed the diagram/calculator on your site.

Need a hand? Use the live chat on [smartcut.dev](https://smartcut.dev) or get in touch via the [contact page](https://smartcut.dev/contact).

---

# API Reference

URL: https://smartcut.dev/docs/api

> Run SmartCut cutting optimization from your own software over a REST API. Submit parts and stock, get back cutting patterns, diagrams and machine files.

SmartCut is a hosted cutting-optimization API for sheet, linear and roll
materials. You send a list of parts and the stock you can buy, and it returns a
cutting pattern with diagrams, labels and machine-ready files.

The specification, runnable examples in four languages and the MCP
configuration all live in the public repository at
[github.com/jgmedialtd/smartcut-api](https://github.com/jgmedialtd/smartcut-api).

:::tip[Prefer an LLM client?]
The same v3 API is available over the [Model Context Protocol](/docs/mcp).
Submit jobs, fetch layouts and generate exports from Claude, Cursor or your own
agent, using the same API key.
:::

## Quick start

Get an API key from [your account](https://smartcut.dev/account), then submit a
job. **Pass the key raw in the `Authorization` header. There is no `Bearer`
prefix**, and adding one returns 401. It is the commonest integration mistake by
a distance.

```bash
curl -X POST https://api.smartcut.dev/v3/calculate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "saw": { "cutType": "guillotine", "cutPreference": "l", "bladeWidth": 3, "stockType": "sheet" },
    "stock": [ { "l": 2400, "w": 1200, "t": 18, "material": "Plywood", "grain": "l" } ],
    "parts": [ { "l": 400, "w": 300, "t": 18, "material": "Plywood", "q": 5 } ]
  }'
```

That responds with a job id:

```json
{ "jobId": 12345 }
```

Optimization takes longer than a request should block for, so it runs
asynchronously. Poll until the result exists, then fetch it:

```bash
# 200 = ready, 404 = not finished yet, 410 = expired and gone.
# This endpoint answers with a STATUS CODE and no body.
curl -i "https://api.smartcut.dev/v3/result/ready?id=12345" -H "Authorization: YOUR_API_KEY"

curl "https://api.smartcut.dev/v3/result?id=12345" -H "Authorization: YOUR_API_KEY"
```

In production you would usually register a [webhook](/docs/webhooks) instead and
skip polling entirely.

The result carries one entry per stock piece, listing the parts placed on it
with their positions, the cuts needed to produce them, and the offcut left over.
The export endpoints turn that same result into PDF, CSV, DXF, SVG or a native
saw file.

Complete runnable versions in **curl, Node, Python and PHP** are in the
[examples directory](https://github.com/jgmedialtd/smartcut-api/tree/main/examples).

## There is no SDK, by design

The API is a JSON body and one header, so `fetch` is already the client, and a
client generated in your own idiom will fit your codebase better than one we
hand-wrote. Point any generator at the specification:

```bash
npx openapi-typescript https://smartcut.dev/openapi/v3.json -o smartcut.d.ts
npx @hey-api/openapi-ts -i https://smartcut.dev/openapi/v3.json -o src/smartcut
openapi-generator-cli generate -i https://smartcut.dev/openapi/v3.json -g python -o ./smartcut-python
```

## Interactive reference

**V3 is current. Build against it.**

<a href="/api-docs/v3" target="_blank">V3 reference →</a>

V2 is maintained and receives no new features.

<a href="/api-docs/v2" target="_blank">V2 reference →</a>

V1 is deprecated and kept only for integrations that already use it. Do not
start new work against it.

<a href="/api-docs/v1" target="_blank">V1 reference →</a>

The `saw` object has its own explorer: every field with its allowed values and
defaults, which saw states each one applies to, the stock-type × cut-type
matrix, the rules that resolve contradictory settings instead of rejecting
them, and the recognised saw profiles. Paste a saw into it and it shows exactly
what the API would run.

<a href="/api-docs/saw-settings" target="_blank">Saw settings explorer →</a>

---

# Guide

URL: https://smartcut.dev/docs/guide

> Helpful definitions and ways of doing things

However you are interacting with the API, a few conventions hold throughout. They are defined here.

## Coordinate system & side definitions

Throughout the process we need to be able to refer to sides and directions, while catering for part rotation.

For our x and y coordinate system, y increases as you move up.

The side labels are used throughout. L indicates stock length if used as a direction or the longer side. W indicates stock width (shorter side) if used as a direction or the shorter side.

### Stock

- Stock is always arranged with the long sides horizontally. Stock never rotates.
- Longer sides are labelled L1 and L2.
- Shorter sides are known as the width and labelled W1 and W2.
- Adding trim to stock.trim.l1 will trim moving in from the bottom side, reducing the width of the stock.

![Coordinate system stock](/images/stock-coords.png)

### Parts

- Parts can rotate, but as the L1,L2,W1,W2 sides refer to the longer and shorter sides these values do not change with rotation.

![Coordinate system parts](/images/part-coords.png)

## Orientation models

To suit various local conventions for defining part orientation we support different orientation models. These define how part rotation is defined and how sides are labelled.

### Model 0 (default, used by API)

- Model 0 is used by the API.
- For model 0, the part orientation is defined by the orientationLock property on the part. The values for part.l and part.w DO NOT affect rotation.
- On stock without grain, orientationLock = 'l' means the longer side of the part is aligned with the longer side of the stock (this is horizontal on our diagrams).
- On stock **with** grain, the lock is read relative to the grain: orientationLock = 'l' means the part's length follows the grain, 'w' means its width follows the grain, whichever axis the grain runs along. Leave it empty for free rotation.

### Model 1 (can be used by UI)

- Orientation is controlled by the values in the 'length' / 'l' and 'width' / 'w' properties of each part.
- The part is rotated so that the side defined by the 'l' property is aligned with the longer side of the stock.
- Clicking the rotation button allows for free rotation, overriding the l/w defined orientation.
- Side labels (L1/L2/W1/W2) are not remapped in outputs. They always use the internal definition shown in the diagrams above, which is separate from the L and W dimension columns.

### Model 2 (can be used by UI)

- Orientation is controlled by the values in the 'length' / 'l' and 'width' / 'w' properties of each part.
- The value used in the 'length' / 'l' property determines the grain dimension.
- Clicking the rotation button allows for free rotation, overriding the l/w defined orientation.
- Banding L values match L column values
- L and W columns are updated in exports to match local expectations (e.g. CSV output)
- Side labels (L1/L2/W1/W2) are not remapped in outputs. They always use the internal definition shown in the diagrams above, which is separate from the L and W dimension columns.

### Use of sides (L1,L2,W1,W2)

Where sides are defined directly, for example in banding.sides or trim, our internal definition of L1,L2,W1,W2 always applies. The orientation model makes no difference. The diagrams above show that definition.

## Related

- [API reference](/docs/api/) is where these conventions are applied, field by field.
- [Embedded diagrams](/docs/embed/) render the layout using the coordinate system above.
- [Webhooks](/docs/webhooks/) deliver the result once an optimisation finishes.

---

# MCP server

URL: https://smartcut.dev/docs/mcp

> Run SmartCut cutting-pattern optimisations from Claude, Cursor or a custom agent over the Model Context Protocol, using your existing API key.

SmartCut exposes its optimisation API as a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. An LLM client can submit cutting jobs, fetch layouts and generate exports directly, in natural language. That covers Claude Desktop, Claude.ai, Cursor, and anything you build yourself.

It mirrors the [REST v3 API](/docs/api): same engine, same authentication, same usage quota. Anything you can do over REST you can do over MCP.

## Endpoint

```text
POST https://api.smartcut.dev/mcp
```

The transport is **Streamable HTTP**. Nothing needs installing, because the server is hosted and remote. You point your client at the URL above and authenticate with your API key.

SmartCut is also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as **`dev.smartcut/cutlist-optimizer`**, so clients that browse the registry can find it without any of the configuration below.

## Credentials

You authenticate with your **existing SmartCut API key**. There is no separate MCP token to create.

1. Sign in at [smartcut.dev/account](https://smartcut.dev/account) (an active **API subscription** is required).
2. Copy your **API key** from the account page.
3. Give it to your MCP client as an `Authorization` header (see below). The value is the **raw key**, with no `Bearer ` prefix.

:::caution
Your API key is a secret. Store it in an environment variable rather than pasting it directly into a config file, and never commit it to source control.
:::

## Connect a client

Most LLM clients connect to a remote MCP server through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. Add SmartCut to your client's MCP config (e.g. Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "smartcut": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.smartcut.dev/mcp",
        "--header", "Authorization:${SMARTCUT_API_KEY}"
      ],
      "env": {
        "SMARTCUT_API_KEY": "your-api-key"
      }
    }
  }
}
```

Passing the key via the `env` block, rather than inline in `args`, keeps it out of the args list and works around clients that strip spaces from arguments. Note there is no space after `Authorization:`.

A ready-made copy of that config, plus the same tool reference, lives in the public repository at [github.com/jgmedialtd/smartcut-api](https://github.com/jgmedialtd/smartcut-api/tree/main/mcp).

If your client supports remote/HTTP MCP servers **natively** (a URL plus custom headers), configure it directly instead:

- **URL**: `https://api.smartcut.dev/mcp`
- **Header**: `Authorization: <your-api-key>`

Restart the client and the SmartCut tools below become available.

## Tools

Each tool maps 1:1 to a v3 API endpoint:

| Tool | Does |
|---|---|
| `calculate` | Submit a job and (by default) wait in-call for the finished layout. |
| `validate` | Pre-flight your inputs (will the parts fit, why not). No job is run and nothing is charged. |
| `status` | Check a job: queued / active / completed / failed / cancelled. |
| `result` | Fetch a finished layout by job id. |
| `cancel` | Cancel a queued or running job you own. |
| `usage` | Your plan usage: used / limit / remaining. |
| `export` | Generate a `pdf`, `csv`, `ptx`, `dxf`, `svg` or `mayer` file and return a download URL. |
| `labels` | Generate a printable labels PDF and return a download URL. |
| `list_cut_types` | The valid `stockType → cutType → cutPreference` combinations, so the model can build a correct request without leaving the chat. |
| `import_parts` | Send parts you have extracted (from a PDF or a photo of a cutting plan, say) straight into an open [Cutlist Evolution](https://cutlistevo.com) editor. The user opens **Import → AI** in the app and gives you the short connection code. The parts arrive as a preview for them to confirm. This does **not** run an optimisation and is not charged. |

## How `calculate` runs

Optimisation is asynchronous, but the `calculate` tool bridges that to a single call:

1. It submits the job, then waits in-call (default up to ~25 s, override with `waitMs`).
2. If the job finishes in time, it returns the **full layout** there and then.
3. If it doesn't, it returns `{ jobId, status: "running" }`. The result still arrives at any `webhook` you supplied, and the model can fetch it later with the `result` tool.

This keeps normal jobs to one round-trip while large or batch jobs stay fully async.

## Billing & limits

The MCP and the REST API share **one quota**. A `calculate` call counts against your plan exactly like a `POST /v3/calculate`, and `validate` / `status` / `usage` are free. Rate limits are the same per-minute budget as the REST API. Result fetching is scoped to your own jobs.

## See also

- [API Reference](/docs/api) covers the underlying REST v3 API and authentication.
- [Interactive v3 reference](/api-docs/v3) runs every endpoint live.
- [Store config MCP](/docs/ecommerce-mcp) is the e-commerce counterpart, for configuring a hosted storefront.

---

# E-commerce Integration Guide

URL: https://smartcut.dev/docs/ecommerce

> Analytics tracking, webhook events, and API reference for SmartCut e-commerce

:::tip[Configure your store from an LLM client]
You can manage your storefront's materials, stock, pricing and extras in natural language with the [Store config MCP](/docs/ecommerce-mcp).
:::

## Google Analytics & Google Tag Manager

SmartCut checkout pages support Google Analytics 4 (GA4) and Google Tag Manager (GTM) for tracking customer behaviour. Configure these in your organisation's e-commerce settings under the **Analytics & Tracking** tab.

### Setup

For **Google Analytics 4**, enter your GA Measurement ID (format: `G-XXXXXXXX`). SmartCut injects the `gtag.js` script and sends events directly to GA4.

For **Google Tag Manager**, enable GTM and enter your Container ID (format: `GTM-XXXXXXX`). SmartCut injects the GTM container script and pushes all events to the `window.dataLayer`. You can then configure triggers and tags within GTM as needed.

You can configure either or both. When **only GA4** is configured, events are sent directly via `gtag`. When **GTM is enabled** (with or without a GA4 ID), events are pushed to the `dataLayer` only. To avoid duplicate events, forward them to GA4 with a GA4 tag inside your GTM container.

### Tracked Events

The following events are automatically fired on your checkout pages. These use standard GA4 event names, which GA4 recognises and reports on automatically.

| Event | When | Key Parameters |
|-------|------|----------------|
| `page_view` | Checkout page loaded | `store` |
| `view_item` | Optimisation completed | `store` |
| `add_to_cart` | Item added to basket | `currency`, `value`, `items[]` |
| `begin_checkout` | Customer proceeds to order form | `currency`, `value`, `items[]` |
| `purchase` | Order confirmed | `transaction_id`, `value`, `currency` |

### dataLayer Format

Each event is pushed to `window.dataLayer` in the following format:

```js
{
  event: 'add_to_cart',
  currency: 'GBP',
  value: 48.00,
  items: [
    { item_name: 'MDF 18mm', quantity: 1, price: 48.00 }
  ]
}
```

The `purchase` event includes a `transaction_id` matching the order reference:

```js
{
  event: 'purchase',
  transaction_id: 'A1B2C3',
  value: 199.98,
  currency: 'GBP'
}
```

### GTM Trigger Examples

To capture these events in Google Tag Manager, create a **Custom Event** trigger for each event name:

1. Go to **Triggers** > **New** > **Custom Event**
2. Set the event name (e.g. `add_to_cart`)
3. Attach it to your GA4 or other tags

For the `purchase` event, you can access `transaction_id`, `value`, and `currency` as dataLayer variables.

### Notes

- Events are not fired in admin preview mode
- The `page_view` and `view_item` events include a `store` parameter with the checkout slug (or `custom_domain` for custom domain stores)
- The `purchase` event fires on the order confirmation page, once per checkout redirect, and will not duplicate on page refresh

---

## Test Mode

SmartCut e-commerce supports a test/production mode system. Test mode lets you configure and preview settings (pricing, shipping, Stripe keys, email, webhooks) independently from your live store, using the same inventory.

### How It Works

- **Production mode** is the default. All public checkout pages use production settings.
- **Test mode** maintains a separate copy of your operational settings. Inventory (stock, materials, extras, products) is shared between both modes.
- Toggle between modes using the **Production / Test** buttons in the admin bar, visible on all e-commerce admin pages.

### What Is Separate Per Mode

| Setting | Separate | Notes |
|---------|----------|-------|
| Config (pricing, stock filter, part rules, custom fields, etc.) | Yes | |
| Stripe keys | Yes | Use `pk_test_` / `sk_test_` keys in test mode |
| Email provider | Yes | Configure a test email provider independently |
| Shipping options | Yes | Test different shipping rates and formulas |
| Webhooks | Yes | Point test webhooks at a different URL |
| Stock & materials | No | Shared. Import is disabled in test mode |
| Products & categories | No | Shared |
| Extras (banding, finish, etc.) | No | Shared (but extras *config* like rules/locations is per-mode) |
| Company profile & branding | No | Shared |
| Slug & custom domain | No | Shared |
| Published status | No | Only production can be published |

### Previewing Test Settings

Append `?mode=test` to your checkout URL to view the store with test settings applied:

```
https://smartcut.dev/ecommerce/your-slug?mode=test
```

The admin settings page shows this URL automatically when in test mode. A yellow **Test mode** banner appears at the top of the checkout to distinguish it from production.

### Orders in Test Mode

Orders are **not created** in test mode. The checkout flow runs normally (customer can fill in the form, select shipping, etc.) but when submitting:

- No order is saved to the database
- No emails are sent
- No webhooks are fired
- No inventory is decremented
- No Stripe checkout session is created

The customer sees a message confirming it was a test submission.

### Stripe Keys

A warning is shown in the Stripe settings tab if there is a mismatch between the ecommerce mode and the Stripe key type:

- Test mode with live keys warns you to use test keys for safe testing
- Production mode with test keys warns that customers cannot make real payments

### Copying Settings

Use the buttons in the admin bar to copy settings between modes:

- **Apply to Production** overwrites production settings with the current test settings
- **Copy to Test** / **Reset from Production** overwrites test settings with the current production settings

Only mode-specific settings are copied (config, stripe, email, shipping options, webhooks). Shared fields (company, branding, slug, inventory) are never affected.

### First Use

When you first switch to test mode, your current production settings are automatically copied as the starting point. You can then modify test settings independently.

---

## Webhooks

SmartCut can send webhook notifications to your server when e-commerce events occur. Configure your webhook endpoint URL and the events you want to receive in your organisation settings.

### Delivery

Webhooks are sent as `POST` requests with a JSON body. Each request includes the following headers:

| Header | Description |
|--------|-------------|
| `Content-Type` | `application/json` |
| `X-SmartCut-Event` | The event name, e.g. `order.created` |
| `X-SmartCut-Delivery` | Unique delivery ID (UUID). **Stable across retries**, so use it as an idempotency key |
| `X-SmartCut-Attempt` | Which attempt this is, starting at 1 |
| `X-SmartCut-Timestamp` | Unix timestamp (seconds) of the delivery attempt |
| `X-SmartCut-Signature` | HMAC signature. See below |

Respond with any `2xx` status to acknowledge. Anything else counts as a failure.

### Retries

Failed deliveries are attempted **up to 13 times over roughly 26 hours**: the first delivery plus 12 retries, with delays of 10s, 30s, 1m, 5m, 15m, 30m, 1h, 2h, 4h, then 6h (×3). Each delay is jittered slightly.

| Response | Retried? |
|----------|----------|
| `2xx` | Delivered. No retry |
| `5xx` | Yes |
| `429` / `408` | Yes. A `Retry-After` header is honoured (capped at 6 hours) |
| Other `4xx` | No. We treat these as "the request is wrong", and resending it unchanged cannot help |
| `3xx` | No. Redirects are **not** followed |
| Timeout (10s) or network error | Yes |

Because retries reuse the same `X-SmartCut-Delivery` ID, you should treat that ID as an idempotency key and ignore a delivery you have already processed.

### Endpoints that keep failing

If we cannot deliver to your endpoint for **24 hours**, we'll email you a warning and keep retrying. If it's still failing after **72 hours**, we'll **disable the endpoint** and stop sending events to it.

A disabled endpoint has to be re-enabled by hand in your store settings. We never re-enable one automatically. Any successful delivery at any point resets the clock.

### Verifying the signature

Every delivery is signed with a secret unique to your endpoint. You can reveal or rotate it in your store settings under **Webhooks**.

The `X-SmartCut-Signature` header looks like:

```text
X-SmartCut-Signature: t=1720000000,v1=5257a869e7b...
```

`v1` is an HMAC-SHA256, in hex, of the string `{timestamp}.{raw request body}`, using your signing secret as the key. Note the timestamp is **inside** the signed payload: that's what lets you reject replayed deliveries.

To verify: take `t` from the header, concatenate it with a `.` and the **raw** request body, HMAC that with your secret, and compare against `v1` using a constant-time comparison. Use the raw body, before any JSON parsing, because re-serialising changes the bytes and breaks the signature. Reject the request if the timestamp is more than a few minutes old.

```js
import crypto from 'crypto'

function verifySmartCutWebhook( header, rawBody, secret, toleranceSeconds = 300 )
{
    const parts = Object.fromEntries( header.split( ',' ).map( p => p.trim().split( '=' ) ) )
    const timestamp = Number( parts.t )

    // Reject replays: the signature is still valid, but the delivery is stale.
    if ( Math.abs( Date.now() / 1000 - timestamp ) > toleranceSeconds ) return false

    const expected = crypto
        .createHmac( 'sha256', secret )
        .update( `${ timestamp }.${ rawBody }`, 'utf8' )
        .digest( 'hex' )

    const a = Buffer.from( expected )
    const b = Buffer.from( parts.v1 || '' )

    return a.length === b.length && crypto.timingSafeEqual( a, b )
}
```

If you have not yet generated a signing secret, deliveries are sent unsigned (no `X-SmartCut-Signature` header) rather than being dropped.

### Events

| Event | Description |
|-------|-------------|
| `order.created` | A new order has been placed |
| `order.payment_completed` | An unpaid (invoice) order has been settled |
| `order.status_changed` | The order status has been updated |
| `inventory.decremented` | Stock quantities have been reduced after an order |

### Check `paymentStatus` before you fulfil

**`order.created` does not guarantee the order is paid.** Always read the `paymentStatus` field:

- With **card checkout**, we hold the order internally until Stripe confirms payment, then send `order.created` with `paymentStatus: "paid"`.
- **Direct orders** are created already paid, so `order.created` carries `paymentStatus: "paid"`.
- With **pay-by-invoice / on-account** (if you've enabled it), the customer orders without paying. You receive `order.created` with **`paymentStatus: "unpaid"`**. Later, when you mark the invoice as settled in the admin, you receive **`order.payment_completed`** with `paymentStatus: "paid"`.

If your integration must not act on unpaid orders, either check `paymentStatus === "paid"` on `order.created`, or subscribe to `order.payment_completed` and treat that as your go-ahead for invoice orders.

### Order Webhook

Sent for `order.created` and `order.status_changed` events.

#### Payload

```json
{
  "event": "order.created",
  "orderId": "abc123",
  "organisationId": "org456",
  "timestamp": "2026-03-06T12:00:00.000Z",
  "data": {
    "status": "pending",
    "previousStatus": "draft",
    "paymentStatus": "paid",
    "customer": {
      "id": "cust_9f2a1b",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+44 7700 900000",
      "notes": "Please call before delivery",
      "address": {
        "line1": "123 High Street",
        "line2": "Flat 4",
        "city": "London",
        "state": "Greater London",
        "postalCode": "SW1A 1AA",
        "country": "GB"
      }
    },
    "pricing": {
      "total": 199.98,
      "currency": "GBP",
      "breakdown": [
        { "label": "Items Subtotal", "amount": 129.99, "type": "subtotal" },
        { "label": "Minimum Order Fee", "amount": 20.01, "type": "charge" },
        { "label": "Shipping", "amount": 10.00, "type": "charge" },
        { "label": "VAT (20%)", "amount": 39.98, "type": "tax" },
        { "label": "Total", "amount": 199.98, "type": "total" }
      ]
    },
    "shipping": {
      "method": "standard",
      "cost": 10.00,
      "address": {
        "line1": "123 High Street",
        "line2": "Flat 4",
        "city": "London",
        "state": "Greater London",
        "postalCode": "SW1A 1AA",
        "country": "GB"
      }
    },
    "itemCount": 3,
    "partsCount": 24,
    "createdAt": "2026-03-06T11:55:00.000Z",
    "items": [
      {
        "itemId": "item-uuid-1",
        "jobId": "12345",
        "includeOffcuts": true,
        "files": {
          "pdf": "https://example.s3.amazonaws.com/exports/12345/layout.pdf",
          "zip": "https://example.s3.amazonaws.com/exports/12345/files.zip"
        },
        "parts": [
          { "id": "1", "l": 600, "w": 400, "quantity": 2, "material": "MDF", "thickness": 18, "stock": { "id": "1.0", "code": "WM-18" } },
          { "id": "2", "l": 580, "w": 350, "quantity": 3, "material": "MDF", "thickness": 18, "stock": { "id": "1.0", "code": "WM-18" } }
        ]
      }
    ],
    "results": [
      {
        "jobId": 12345,
        "saw": {},
        "stock": [],
        "parts": [],
        "cuts": [],
        "offcuts": [],
        "unusableParts": [],
        "metadata": {}
      }
    ]
  }
}
```

#### Fields

##### Top-level

| Field | Type | Description |
|-------|------|-------------|
| `event` | string | One of `order.created`, `order.status_changed` |
| `orderId` | string | Unique order identifier |
| `organisationId` | string | Your organisation ID |
| `timestamp` | string | ISO 8601 timestamp of when the webhook was sent |

##### data

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | string | Yes | Current order status |
| `previousStatus` | string | No | Previous status (present on `order.status_changed`) |
| `paymentStatus` | string | No | Payment status |
| `customer` | object | Yes | The customer's details. See [data.customer](#datacustomer) |
| `pricing` | object | Yes | Order total, currency, and a line-item breakdown |
| `shipping` | object | No | The chosen shipping option and delivery address. See [data.shipping](#datashipping). Absent for collection/no-shipping orders |
| `itemCount` | number | Yes | Number of line items in the order |
| `partsCount` | number | Yes | Total number of individual parts |
| `createdAt` | string | Yes | ISO 8601 timestamp of order creation |
| `items` | array | Yes | Per-job breakdown of parts, files, and stock references. Use with the ecommerce API (see below) |
| `results` | array | No | Full V3 API optimisation results for each job, including part placement coordinates and stock references. See [V3 API docs](/api-docs/v3) |

##### data.items[]

Each entry corresponds to one basket item (job) in the order. Items and results share the same order, so `items[0]` corresponds to `results[0]`, and so on. Use `itemId` with the [ecommerce API endpoints](#mark-parts-cut) to track cutting progress.

| Field | Type | Description |
|-------|------|-------------|
| `itemId` | string | Basket item ID. Use as `itemId` in mark-cut / mark-complete / adjust-cut requests |
| `jobId` | string | Optimisation job ID |
| `includeOffcuts` | boolean | Whether the customer opted in to receive offcuts for this job (`false` if not opted in) |
| `files` | object | Export file URLs (if available) |
| `files.pdf` | string | Layout PDF URL |
| `files.zip` | string | ZIP archive URL (contains machining PDF, CSV, PTX, DXF as configured) |
| `parts` | array | Parts for this item (one entry per unique part, with `quantity` for count) |

##### data.items[].parts[]

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Part identifier (e.g. `"1"`, `"2"`), derived from the integer portion of the part ID. Use to match parts across `results[].parts[]` and in mark-cut / mark-complete requests |
| `l` | number | Part length (long side) |
| `w` | number | Part width (short side) |
| `quantity` | number | Number of this part required |
| `material` | string | Material name (if specified) |
| `thickness` | number | Material thickness (if specified) |
| `stock` | object | Stock/material reference (if available) |
| `stock.id` | string | Stock ID. References the corresponding `results[].stock[].id` |
| `stock.code` | string | Stock code |

##### data.results[]

Each entry is a full V3 API response containing the optimisation result for one job in the order. See the <a href="/api-docs/v3" target="_blank">V3 API documentation</a> for the complete response schema.

| Field | Type | Description |
|-------|------|-------------|
| `jobId` | number | Job identifier |
| `saw` | object | Saw configuration used |
| `stock` | array | Stock items |
| `parts` | array | Parts with coordinates and properties |
| `cuts` | array | Cut instructions |
| `offcuts` | array | Remaining offcut pieces |
| `unusableParts` | array | Parts that could not be placed |
| `metadata` | object | Complete analysis and metrics (efficiency, waste, costs, material summary) |

##### data.customer

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Registered customer-account id, present when the buyer was signed in. Use it to match/dedupe the customer in your own system across their orders |
| `name` | string | Yes | Customer full name |
| `email` | string | Yes | Customer email address |
| `phone` | string | No | Customer phone number |
| `notes` | string | No | Free-text note the buyer left on the order |
| `address` | object | No | The customer's address: their saved account address when available, otherwise the address entered for this order. Same fields as `data.shipping.address`. Absent when no address is on file |

##### data.pricing

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `total` | number | Yes | Order total |
| `currency` | string | Yes | ISO 4217 currency code |
| `breakdown` | array | Yes | Ordered list of pricing line items (see below) |

##### data.pricing.breakdown[]

Each entry represents a line in the pricing summary. Only non-zero charges are included. The final entry is always the total.

| Field | Type | Description |
|-------|------|-------------|
| `label` | string | Display label (e.g. "Items Subtotal", "VAT (20%)", "Total") |
| `amount` | number | Amount in the order currency |
| `type` | string | One of `subtotal`, `charge`, `tax`, `total` |

Possible line items (in order, when applicable):

| Label | Type | When present |
|-------|------|--------------|
| Items Subtotal | `subtotal` | Always |
| Samples Subtotal | `subtotal` | Material samples ordered |
| Minimum Order Fee | `charge` | Order below minimum and store charges the difference |
| Shipping | `charge` | Shipping cost > 0 |
| VAT / GST / Sales Tax (rate%) | `tax` | Tax enabled on the store |
| Total | `total` | Always |

##### data.shipping

Optional. Present when shipping details are available.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `method` | string | No | The shipping option the customer selected |
| `cost` | number | No | The price of the selected shipping option, in the order currency (`0` for free shipping) |
| `address.line1` | string | Yes | Street address |
| `address.line2` | string | No | Additional address line |
| `address.city` | string | Yes | City |
| `address.state` | string | No | State / county / region |
| `address.postalCode` | string | Yes | Postal/ZIP code |
| `address.country` | string | Yes | ISO 3166-1 alpha-2 country code |

### Inventory Webhook

Sent when stock quantities are decremented after an order is processed.

#### Payload

```json
{
  "event": "inventory.decremented",
  "orderId": "abc123",
  "organisationId": "org456",
  "timestamp": "2026-03-06T12:01:00.000Z",
  "data": {
    "changes": [
      {
        "stockId": "stock789",
        "stockName": "18mm White Melamine",
        "material": "Melamine",
        "code": "WM-18",
        "thickness": 18,
        "dimensions": {
          "length": 2440,
          "width": 1220
        },
        "previousQuantity": 50,
        "newQuantity": 47,
        "decrementedBy": 3,
        "deleted": false
      }
    ]
  }
}
```

#### data.changes[]

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `stockId` | string | Yes | Stock item ID |
| `stockName` | string | No | Human-readable stock name |
| `material` | string | No | Material name |
| `code` | string | No | Material code |
| `thickness` | number | No | Material thickness |
| `dimensions.length` | number | No | Stock length |
| `dimensions.width` | number | No | Stock width |
| `previousQuantity` | number | Yes | Quantity before decrement |
| `newQuantity` | number | Yes | Quantity after decrement |
| `decrementedBy` | number | Yes | Number of units consumed |
| `deleted` | boolean | No | Whether the stock item was fully consumed |

### Testing Webhooks

Use the test endpoint to verify your webhook URL is reachable. A test webhook sends a simple payload:

```json
{
  "event": "test",
  "timestamp": "2026-03-06T12:00:00.000Z",
  "message": "This is a test webhook from SmartCut"
}
```

## Orders API

These endpoints allow you to track orders and parts through the cutting and completion workflow. All requests require your API key in the `Authorization` header.

**Order status progression:** `pending → cut → complete → dispatched`

### Update Order Status

```
PATCH /ecommerce/orders/:id
```

Updates the status of an order.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | string | Yes | One of `pending`, `cut`, `complete`, `dispatched`, `cancelled` |
| `updateInventory` | boolean | No | Decrement inventory stock when marking as `cut` (default: `false`) |
| `forceOverwrite` | boolean | No | Skip partial progress warning when marking as `cut` (default: `false`) |
| `resetCuts` | boolean | No | Reset all part cut counts when reverting to `pending` (default: `false`) |

**Example:**

```json
{ "status": "complete" }
```

**Responses:**

| Status | Description |
|--------|-------------|
| `200` | Order updated. Returns the updated order document |
| `400` | Invalid status value |
| `403` | No active e-commerce subscription. Body carries `code: "SUBSCRIPTION_REQUIRED"` |
| `404` | Order not found. Also returned for an order belonging to another organisation, and for an order in the other (test/production) mode. A foreign order is never reported as `403` |
| `409` | Partial cut progress detected. Pass `forceOverwrite: true` to proceed |

When a `409` is returned, the response body contains:

```json
{
  "error": "Order has parts with partial cut progress.",
  "code": "PARTIAL_PROGRESS",
  "data": {
    "partsWithProgress": [
      { "itemName": "Item abc", "partIndex": 0, "current": 2, "total": 5 }
    ]
  }
}
```

#### Side effects

- **Customer status email** (optional): if email is configured and the per-status notification toggle is enabled (under email settings → Notifications → Order Status Changes), the customer is sent a short email when the status moves to `pending`, `cut`, `complete`, `dispatched`, or `cancelled`. Each status has its own toggle. By default `complete`, `dispatched` and `cancelled` are on, while `pending` and `cut` are off.
- **Order webhook** (optional): if an `order.status_changed` webhook is configured, a webhook fire-and-forget is dispatched on every status change.

---

### Mark Parts Cut

```
PATCH /ecommerce/orders/parts/mark-cut
```

Increments the `numberCut` count for one or more parts. When all parts in an order reach their full quantity, the order is automatically set to `cut`.

**Request body:**

```json
{
  "updates": [
    { "orderId": "66abc123", "itemId": "item-uuid", "id": "1", "count": 1 }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `orderId` | string | Yes | Order ID |
| `itemId` | string | Yes | Basket item ID within the order |
| `id` | string | Yes | Part identifier. Matches `id` from `items[].parts[]` |
| `count` | number | Yes | Number of additional instances to mark as cut (minimum: 1) |

**Responses:**

| Status | Description |
|--------|-------------|
| `200` | Request processed. Returns per-order results and any auto-promoted order IDs. An unknown order, item or part does **not** change the status code. It is reported per entry (see below) |
| `400` | Missing or invalid request body: `updates` not a non-empty array, an entry missing `orderId`/`itemId`/`id`/`count`, or `count` below `1` |
| `403` | No active e-commerce subscription. Body carries `code: "SUBSCRIPTION_REQUIRED"` |
| `404` | No organisation found for the authenticated user. **Not** returned for an unknown or foreign order, item or part |

```json
{
  "success": true,
  "data": {
    "results": [{ "orderId": "66abc123", "success": true }],
    "autoMarkedOrders": ["66abc123"]
  }
}
```

`autoMarkedOrders` contains IDs of orders automatically promoted to `cut` because all parts reached full quantity.

#### Per-entry failure reporting

The parts endpoints (`mark-cut`, `mark-complete`, `adjust-cut`, `adjust-complete`) are batch endpoints. An unknown order, unknown basket item or unknown part is **not** an HTTP error. The response is still `200` with a top-level `"success": true`, and the failure appears as an entry in `data.results`:

```json
{
  "orderId": "66abc123",
  "success": false,
  "error": "Order not found"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `orderId` | string | The order the entry refers to |
| `success` | boolean | `false` when that entry failed |
| `error` | string | Present only when `success` is `false` |

`error` is one of `Order not found`, `Item <itemId> not found`, `Part <id> not found`, or the message of an unexpected error raised while saving that order.

**Do not branch on the HTTP status code alone.** Always walk `data.results` and check each entry's `success` flag. A batch in which every update failed still returns `200` with `"success": true` at the top level. Note also that a single `orderId` can produce more than one entry: a failed part within an order pushes a `success: false` entry, while the order's other successful parts still push a `success: true` entry.

---

### Mark Parts Complete

```
PATCH /ecommerce/orders/parts/mark-complete
```

Increments the `numberComplete` count for one or more parts. When all parts in an order reach their full quantity and the order is in `cut` status, the order is automatically set to `complete`.

Accepts the same request body format as [Mark Parts Cut](#mark-parts-cut).

**Invariant:** `numberComplete ≤ numberCut ≤ partQuantity`. If a request would cause `numberComplete` to exceed `numberCut`, the value is silently clamped to `numberCut` rather than rejected. This means parts must be cut before they can be completed.

**Responses:**

| Status | Description |
|--------|-------------|
| `200` | Request processed. Returns per-order results and any auto-promoted order IDs. `numberComplete` may be clamped to `numberCut`. An unknown order, item or part is reported [per entry](#per-entry-failure-reporting), not by status code |
| `400` | Missing or invalid request body: `updates` not a non-empty array, an entry missing `orderId`/`itemId`/`id`/`count`, or `count` below `1` |
| `403` | No active e-commerce subscription. Body carries `code: "SUBSCRIPTION_REQUIRED"` |
| `404` | No organisation found for the authenticated user. **Not** returned for an unknown or foreign order, item or part |

---

### Adjust Parts Cut

```
PATCH /ecommerce/orders/parts/adjust-cut
```

Decrements cut counts for individual parts, or resets all cut counts for a basket item to zero. When a decrement causes any part to fall below its full quantity on an order with status `cut`, the order is automatically reverted to `pending`.

When `numberCut` is reduced, `numberComplete` is automatically clamped down to maintain the invariant `numberComplete ≤ numberCut`. The `resetAll` mode resets both `numberCut` and `numberComplete` to zero.

**Request body (decrement):**

```json
{
  "updates": [
    { "orderId": "66abc123", "itemId": "item-uuid", "id": "1", "count": -1 }
  ]
}
```

**Request body (reset all cuts for an item):**

```json
{
  "resetAll": { "orderId": "66abc123", "itemId": "item-uuid" }
}
```

**Responses:**

| Status | Description |
|--------|-------------|
| `200` | Request processed. Returns per-order results and any orders reverted to `pending` |
| `400` | Missing or invalid request body: neither `updates` nor `resetAll` supplied, `resetAll` missing `orderId` or `itemId`, `updates` not a non-empty array, or an entry missing `orderId`/`itemId`/`id`/`count` |
| `403` | No active e-commerce subscription. Body carries `code: "SUBSCRIPTION_REQUIRED"` |
| `404` | No organisation found for the authenticated user. In `resetAll` mode only, also `Order not found` or `Item not found`. A foreign order is reported as `404`, never `403` |

The two modes report failures differently:

- In **`resetAll` mode**, an unknown order or unknown basket item is a genuine `404`. An item that exists but has no parts returns `200` with a `results` entry `{ "success": false, "error": "No parts found in item" }`.
- In **`updates` mode**, an unknown order, item or part returns `200` and is reported [per entry](#per-entry-failure-reporting), exactly as for `mark-cut`.

```json
{
  "success": true,
  "data": {
    "results": [{ "orderId": "66abc123", "success": true }],
    "revertedOrders": ["66abc123"]
  }
}
```

`revertedOrders` contains IDs of orders automatically reverted to `pending` because one or more parts fell below full quantity.

---

### Adjust Parts Complete

```
PATCH /ecommerce/orders/parts/adjust-complete
```

Adjusts completion counts for individual parts (increment or decrement). Each part's completion count is clamped between `0` and `min( partQuantity, numberCut )`. The invariant `numberComplete ≤ numberCut ≤ partQuantity` is enforced, so you cannot complete a part that has not been cut.

**Request body:**

```json
{
  "updates": [
    { "orderId": "66abc123", "itemId": "item-uuid", "id": "1", "count": 1 }
  ]
}
```

Use a positive `count` to increment and a negative `count` to decrement. The value is clamped to the valid range `[0, min( partQuantity, numberCut )]`.

**Responses:**

| Status | Description |
|--------|-------------|
| `200` | Request processed. Returns per-order results. An unknown order, item or part is reported [per entry](#per-entry-failure-reporting), not by status code |
| `400` | Missing or invalid request body: `updates` not a non-empty array, or an entry missing `orderId`/`itemId`/`id`/`count` |
| `403` | No active e-commerce subscription. Body carries `code: "SUBSCRIPTION_REQUIRED"` |
| `404` | No organisation found for the authenticated user. **Not** returned for an unknown or foreign order, item or part |

```json
{
  "success": true,
  "data": {
    "results": [{ "orderId": "66abc123", "success": true }]
  }
}
```

---

## Stripe Payments

SmartCut checkout pages can accept payments via Stripe. Each organisation connects their own Stripe account, and SmartCut never handles funds directly.

### Setup

1. **Create or log in to your Stripe account** at [dashboard.stripe.com](https://dashboard.stripe.com)
2. **Get your API keys** from **Developers → API Keys**. We recommend using [Restricted Keys](https://stripe.com/docs/keys#limit-access) with the following permissions:
   - Write access to **Checkout Sessions**
   - Write access to **Webhook Endpoints** *(for automatic webhook setup)*
   - Read access to **Account** *(optional, used for Test Connection)*
3. **Enter your keys in SmartCut** under your e-commerce settings → Stripe tab:
   - Publishable key (`pk_live_...` or `pk_test_...`)
   - Secret key (`sk_live_...`, `sk_test_...`, or a restricted key `rk_live_...` / `rk_test_...`)
4. **Save**. SmartCut then creates the webhook endpoint in your Stripe account and stores the signing secret

If automatic setup fails (e.g. your restricted key doesn't have webhook permissions), you can manually add a webhook endpoint in **Developers → Webhooks → Add endpoint**:
   - Set the endpoint URL to `https://api.smartcut.dev/ecommerce-stripe-webhook`
   - Select `checkout.session.completed` as the event to listen for
   - Copy the **Signing Secret** (`whsec_...`) and enter it in the Stripe tab

### How It Works

When Stripe is enabled, the checkout flow changes:

1. Customer completes the order form and clicks **Pay Now**
2. SmartCut creates a pending order and redirects the customer to a Stripe-hosted checkout page
3. After successful payment, Stripe sends a `checkout.session.completed` event to your webhook endpoint
4. SmartCut verifies the webhook signature, marks the order as paid, generates the PDF, sends confirmation emails, and fires any configured order webhooks

Without the webhook, SmartCut has no way to confirm that payment succeeded, and orders stay in an `unpaid` state.

### Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Orders stay `unpaid` after payment | Webhook not reaching SmartCut | Check your endpoint URL in Stripe and ensure the signing secret is saved |
| "Webhook not configured" in server logs | Signing secret missing for this organisation | Add the `whsec_...` secret in the Stripe tab |
| "Signature verification failed" in server logs | Signing secret mismatch | Re-copy the secret from your Stripe webhook endpoint settings |
| Test connection warns about webhook | Signing secret not saved yet | Save your Stripe settings including the webhook signing secret |

## 3D Product Visualiser: Schema Reference

Formula products can carry an optional **assembly spec** alongside their formula spec. The assembly spec describes how the formula's resolved panels are arranged in 3D space: what joins what, where mirrors live, how shelves repeat. It drives the storefront's interactive 3D preview.

The spec is JSON. Edit it via the product editor's "Edit 3D assembly" dialog, or pre-populate by clicking "Load example" to start from the bundled cabinet or shaker door.

### Coordinate system

Right-handed, mm units, world origin at the centre of the product.

| Axis | + direction | − direction |
|---|---|---|
| **x** | right | left |
| **y** | top | bottom |
| **z** | front (toward camera) | back |

Every part has six **faces** named by world-relative direction: `top`, `bottom`, `left`, `right`, `front`, `back`. The face naming is fixed regardless of the part's local orientation.

### Top-level shape

```jsonc
{
  "name": "Optional spec name",
  "templates": { /* … see Sub-assemblies … */ },
  "instances": [
    /* one entry per physical part */
  ]
}
```

An assembly spec is a flat list of **instances**, each one a physical part in the resolved scene. Sub-assemblies (templates + instantiations) are flattened into instances at parse time, so the resolver only ever sees concrete instances.

### Instance: common fields

```jsonc
{
  "id":   "leftSide",                       // unique identifier for this part
  "from": "side",                           // formula panel key — supplies l/w/t/material
  "take": 0,                                // which of the q copies (default 0)
  "axes": { "l": "y", "w": "z", "t": "x" }, // map panel dims to world axes
  /* exactly one positioning verb: */
  "anchor": "origin",
  "join":   { /* … */ },
  "mirrorOf": "leftSide",
  "repeat":   { /* … */ },
  /* optional transforms applied after positioning: */
  "rotation":  { /* … */ },
  "translate": { /* … */ },
  /* optional visibility gate: */
  "when": "= inputs.hasDoor"
}
```

**`axes`** maps the panel's local **l** (length), **w** (width) and **t** (thickness) onto world x/y/z. All three must be distinct. A back panel lying in the XY plane uses `{ l: "x", w: "y", t: "z" }`. A vertical side panel with thickness on x uses `{ l: "y", w: "z", t: "x" }`.

**`from`** is required for every panel-backed instance. The resolver looks up the matching panel in the formula spec, and its `l/w/t` become the part's bounding-box extents. If the formula spec computes `q: 0` for the panel, the instance is silently skipped (and dependents cascade-skip too).

**`when`** is an optional formula expression. If it evaluates to falsy (zero), the instance is skipped, with the same cascade as `q: 0`. Use it to gate hardware on a customer input independently of any panel quantity.

### Positioning: `anchor`

```jsonc
{ "anchor": "origin" }                        // centre at (0, 0, 0)
{ "anchor": { "at": [ 100, 0, 0 ] } }         // centre at (100, 0, 0)
{ "anchor": { "at": [ "= inputs.x", 0, 0 ] } } // formulas allowed
```

Anchor instances are roots. Every other instance positions itself relative to one. There must be at least one anchor in any spec.

### Positioning: `join` (face-to-face)

```jsonc
{
  "join": {
    "to":         "leftSide",  // reference instance id (must exist)
    "myFace":     "left",      // this instance's face that touches…
    "theirFace":  "right",     // …the reference instance's face
    "align": [ /* up to 2 alignment rules — see below */ ]
  }
}
```

The contact face pair pins one axis (the one perpendicular to both faces). Faces must be on the same axis (e.g. `left`/`right`) and oppose (`+1` and `-1` signs), so *my-right touches their-left*, not *my-right touches their-right*. The remaining two axes are pinned by `align` rules.

#### Alignment rules

Three discriminated shapes:

```jsonc
{ "my": "top",  "their": "top"   }        // edge-to-edge
{ "center": "y" }                          // axis centres match
{ "axis": "z", "offset": 12 }              // my centre = their centre + N
```

Edge alignment names two faces, and the resolver pins the relevant axis so my-face meets their-face. Same-edge pairs (`top`/`top`) and cross-edge pairs (`back`/`front`) both work. The signs do the work.

If you don't supply a rule for an axis, the centres match by default.

### Positioning: `mirrorOf`

```jsonc
{
  "id":       "rightSide",
  "mirrorOf": "leftSide",
  "axis":     "x",          // reflect along this axis
  "center":   0             // optional mirror plane (default 0)
}
```

Reflects an already-placed instance across an axis. The mirrored part inherits the source's geometry (panel reference, rotation, translate). If the source is a **repeat group** (id `<base>@n`), the mirror produces a parallel group `<mirrorId>@n`.

### Positioning: `repeat`

Three flavours:

#### `between`: even spacing between two anchors

```jsonc
{
  "repeat": {
    "count":   "= inputs.numShelves",
    "between": [ "bottom.top", "top.bottom" ],
    "spacing": "even",
    "offset":  { "x": 0, "z": "= inputs.depth - 50" }, // override non-spacing axes
    "shift":   "= 0 - inputs.thickness / 2"             // additive on spacing axis
  }
}
```

Each anchor is `<instanceId>.<face>`. Copies are evenly spaced between the two anchors with `count + 1` gaps (so `count = 1` lands a single copy at the midpoint). Default position on non-spacing axes is the midpoint between the anchor parts.

#### `axis`: fixed spacing along one axis

```jsonc
{
  "repeat": {
    "count":   3,
    "axis":    "y",
    "spacing": 200,
    "startAt": -200,
    "offset":  { "x": 0, "z": "= inputs.depth" } // optional
  }
}
```

Stamps `count` copies starting at `startAt`, separated by `spacing`. Useful for stacked drawers, fixed shelves, etc.

#### `around`: symmetric spacing around a centreline

```jsonc
{
  "repeat": {
    "count":   12,
    "around":  { "axis": "x", "center": 0 },
    "spacing": 90
  }
}
```

Centres copies symmetrically on the centreline. Odd counts get one copy on the centre, then pairs at `±spacing`, `±2·spacing`, and so on. Even counts get pairs at `±½·spacing`, `±1½·spacing`, and so on. Useful for slats and balusters.

Repeated parts get ids like `<id>@0`, `<id>@1`, … etc.

### Rotation

```jsonc
{
  "rotation": {
    "axis":    "y",
    "degrees": "= 0 - inputs.doorOpenAngle",
    "pivot":   [ "left", "front" ]   // edge formed by two faces
  }
}
```

Applied after positioning. `pivot` defaults to the part centre. A single face name (e.g. `"left"`) pivots around that face's centre. A pair of faces names the **edge** where they meet, which is the right model for door hinges. The two faces must lie on different non-rotation axes.

Bounding boxes use the unrotated AABB, so dimensions and click-selection use the part's pre-rotation extents.

### Translation

```jsonc
{
  "translate": {
    "axis":     "z",
    "distance": "= inputs.depth * inputs.drawerOpen / 100"
  }
}
```

Linear offset along one axis, baked into the part's world position before rotation. Use it for "drawer slid forward by N mm" effects.

### Sub-assemblies (templates)

Define a reusable group of instances once, instantiate it many times.

```jsonc
{
  "templates": {
    "drawerBox": {
      "params": [ "drawerHeight" ],          // optional declared param names
      "instances": [
        // The instance with `anchor` is the template's ROOT.
        { "id": "front", "from": "drawerFront", "anchor": "origin", /* … */ },
        { "id": "leftSide", "from": "drawerSide",
          "join": { "to": "front", "myFace": "front", "theirFace": "back", /* … */ } },
        { "id": "rightSide", "mirrorOf": "leftSide", "axis": "x" },
        // … back, bottom …
      ]
    }
  },
  "instances": [
    {
      "id":          "drawer",
      "instantiate": "drawerBox",
      "params":      { "drawerHeight": "= inputs.drawerHeight" },
      "join":        { /* placement of the template root */ },
      "translate":   { "axis": "z", "distance": "= inputs.depth * inputs.drawerOpen / 100" }
    }
  ]
}
```

#### Expansion rules

- **Id namespacing.** Inner instances expand to `<outerId>/<localId>`, giving `drawer/front`, `drawer/leftSide`, and so on. Local references inside the template (`join.to: "front"`) are rewritten to the prefixed form automatically.
- **Cross-scope refs.** Inner instances can reference an **outer-scope** instance by prefixing with `outer/`: `"to": "outer/leftSide"`. The prefix is stripped at expansion.
- **Root inheritance.** The instantiation's `anchor` / `join` / `mirrorOf` replaces the template root's anchor. This is optional. If you don't supply positioning, the template's own anchor stands.
- **Forwarded fields.** `translate`, `rotation`, `when` on the instantiate block are forwarded to the root, so the whole sub-tree slides / rotates / gates as a unit.
- **Parameters.** Template formulas can reference `params.<name>`. The instantiator supplies the values, and those values can themselves be formulas that reference `inputs.X`.
- **Nested templates.** A template can instantiate another template. Expansion iterates until no instantiations remain.
- **Repeat-of-instantiate.** Use `repeat-axis` or `repeat-around` to stamp out N copies of a template (each becomes its own sub-tree under id `<outerId>@<n>/<localId>`). `repeat-between` of an `instantiate` is **not** supported, because the resolver would need to interleave with expansion.

### Worked example: stacked drawers

```jsonc
{
  "templates": {
    "drawerBox": { /* 5 inner instances as shown above */ }
  },
  "instances": [
    /* … carcass: back, sides, top, bottom … */
    {
      "id":          "drawer",
      "instantiate": "drawerBox",
      "repeat": {
        "count":   "= inputs.numDrawers",
        "axis":    "y",
        "spacing": "= inputs.drawerHeight + 2",
        "startAt": "= inputs.thickness + inputs.drawerHeight / 2 - inputs.height / 2",
        "offset":  { "x": 0, "z": "= inputs.depth" }
      },
      "translate": { "axis": "z", "distance": "= inputs.depth * inputs.drawerOpen / 100" }
    }
  ]
}
```

A `numDrawers: 3` cabinet expands to 15 instances (5 per drawer × 3) with ids `drawer@0/front`, `drawer@0/leftSide`, …, `drawer@2/bottom`. The `translate` is forwarded through the repeat so all three drawers respect `drawerOpen` together.

### Hardware (pricing-only)

The assembly spec has no separate hardware kind. Every instance is a panel backed by a formula entry. Pricing-only items (hinges, slides, shelf pins) live in the formula spec's `hardware` block and are summed into the cart total without rendering in the 3D preview. Built-in primitives weren't realistic enough to justify visualising. If you need visible fittings later, import them as separate panels with appropriate dimensions.

### Validation + error surfacing

The dialog's live preview parses each edit against the schema and runs the resolver. Surface errors include:

| Message | Cause |
|---|---|
| `\`from\` (formula panel key) is required …` | Non-mirrored instance missing `from` |
| `Edge alignment faces must share an axis …` | `{ my: "top", their: "left" }`. Top is on y, left on x |
| `Contact faces must oppose …` | `myFace: "right"` and `theirFace: "right"` (same sign) |
| `No formula panel "X"` | `from: "X"` doesn't exist in the paired formula spec |
| `Unresolved instances (cyclic or unknown reference) …` | Two instances joining to each other, or a reference to an unknown id |
| `Unknown template "X"` | `instantiate: "X"` with no template by that name |
| `Template … must have exactly one instance with \`anchor\`` | Template missing or has multiple roots |
| `Template expansion did not converge` | A template instantiates itself directly or indirectly |
| `Repeat-between of an \`instantiate\` is not supported` | Use `repeat-axis` or `repeat-around` |

When two parts overlap, the resolver flags them in the preview (red edge outlines) without throwing, so the author can iterate without the preview disappearing.

---

# E-commerce cut-list calculator

URL: https://smartcut.dev/docs/ecommerce-checkout

> Embedded JavaScript widget for cut-list calculation on e-commerce websites

An embedded JavaScript widget that provides a complete cut-list calculator for your e-commerce, estimation or quotation website functionality.

## Overview

SmartCut Checkout allows you to:

- Embed a cut-list calculator directly on your website
- Calculate prices / estimates in real-time on the client side
- Filter & sort products in your catalogue
- Customize the UI to match your brand
- Support multiple materials, thicknesses, dimensions, extras, and configurations
- No server-side integration required

## Quick Start

### Installation

Include the script and default css styling in your HTML:

```html
<link rel="stylesheet" href="https://cutlistevo.com/checkout/checkout.css" />
<script type="module" src="https://cutlistevo.com/checkout/checkout.js"></script>
```

### Basic Usage

```html
<!-- Container for the calculator -->
<div id="smartcut-app"></div>

<script>
// Configuration
const initData = {
  stock: [
    {
      l: 2440,
      w: 1220,
      t: 18,
      cost: 65,
      material: 'Plywood'
    }
  ],
  saw: {
    stockType: 'sheet',
    bladeWidth: 3.2,
    cutType: 'efficiency',
    cutPreference: 'l'
  },
  options: {
    locale: 'en-US',
    currency: 'USD'
  }
}

// Wait for the ready event and then call init
window.addEventListener('smartcut/ready', () => {
  window.smartcutCheckout.init(initData)
})

// Listen for calculation events
window.addEventListener('smartcut/calculating', () => {
  console.log('Calculation started')
})

// Listen for results
window.addEventListener('smartcut/result', (e) => {
  const result = e.detail
  console.log('Optimization complete:', result)
  console.log('Total stock cost:', result.checkout.formattedTotalStockCost)
})
</script>
```

## Configuration

### Stock Configuration

Define the available stock materials:

```javascript
const initData = {
  stock: [
    {
      l: 2440,
      w: 1220,
      t: 18,
      cost: 65,
      material: 'Plywood'
    }
  ],
  saw: {
    stockType: 'sheet',
    bladeWidth: 3.2,
    cutPreference: 'l'
  },
  options: {
    locale: 'en-US',
    currency: 'USD',
    apiVersion: 3 // 2 or 3 (default: 3)
  }
}
```

**Stock Item Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `l` | number | Sheet length in mm (required) |
| `w` | number | Sheet width in mm (required) |
| `t` | number | Sheet thickness in mm (required) |
| `material` | string | Friendly display name shown in the material picker (required) |
| `code` | string | Unique SKU / identifier for this specific stock item (recommended, see below) |
| `cost` | number | Cost per sheet |
| `weight` | number | Weight in kg |
| `description` | string | Description shown in the picker |
| `imageUrl` | string | Product image URL. Surfaced in results too. |
| `brand` | string | Brand name (shown as picker hierarchy) |
| `variant` | string | Variant / decor name |
| `fullSizeOnly` | boolean | When `true`, the customer cannot enter custom part sizes on this material |
| `grain` | `'l'` \| `'w'` \| `''` | Grain direction of this stock, stated against its long side (`'l'` = along the length, `'w'` = across it, `''` = none). To constrain how a part sits relative to the grain, set `orientationLock` on the part. |
| `category` | string | Category for filtering (used by Product Filtering UI) |
| `tags` | string[] | Searchable tags (used by Product Filtering UI) |
| `available` | boolean | Available-for-purchase flag (used by Product Filtering UI) |

#### How the material picker is built

Stock items are **grouped by their `material` field** into a single picker entry. Multiple items with the same `material` but different dimensions (e.g. different thicknesses or sheet sizes) all appear under one dropdown row. The customer selects the material once, and the calculator then filters the available thicknesses.

The **`code` field** is the per-item identifier: it distinguishes between individual stock rows that share the same `material` name, and it is carried through to the calculation result so you can map each used sheet back to a specific product in your catalogue.

```javascript
// Two sheet sizes of the same material — one picker entry, two thickness options
stock: [
  { l: 2440, w: 1220, t: 18, cost: 65, material: 'Birch Plywood', code: 'BPW-2440-18' },
  { l: 2440, w: 1220, t: 12, cost: 48, material: 'Birch Plywood', code: 'BPW-2440-12' },
]

// Two different materials — two picker entries
stock: [
  { l: 2440, w: 1220, t: 18, cost: 65, material: 'Birch Plywood',  code: 'BPW-18' },
  { l: 2440, w: 1220, t: 18, cost: 45, material: 'White MDF',      code: 'MDF-18' },
]
```

When `code` is omitted, the calculator falls back to the composed label (`brand` + `variant` + `material`) as the grouping key. That works for simple setups. It can also make items appear as separate entries when any of those fields differs between rows of the same material. **Always supply `code` when passing multiple stock rows.**

### Parts Configuration

Pre-populate the calculator with parts at init time. Parts arrive as an array on the `parts` key of the init payload:

```javascript
const initData = {
  stock: [...],
  parts: [
    {
      l: 600,
      w: 400,
      t: 18,
      q: 4,
      name: 'Shelf',
      material: 'Plywood',
      orientationLock: 'l', // 'l', 'w', or '' (free)
      banding: {
        sides: { l1: 'oak|1mm', l2: 'oak|1mm', w1: '', w2: '' }
      },
      finish: {
        faces: { a: 'spray|matt', b: '' }
      },
      labels: { room: 'Kitchen', order: 'ORD-001' }, // saw label-printer fields
      customData: { projectId: '12345', orderRef: 'ORD-001' }
    }
  ],
  options: {...}
}
```

Pre-populated parts pass through validation, defaults are applied, then each part is added to the calculator's parts list (existing parts are cleared first). Per-part validation issues are surfaced as inline errors in the UI rather than blocking the whole init.

**Part Properties:**
| Property | Type | Description |
|----------|------|-------------|
| `l` | number | Part length in mm (defaults to 1 if missing) |
| `w` | number | Part width in mm (defaults to 1 if missing) |
| `t` | number \| string | Thickness (optional, inherits from stock if not set) |
| `q` | number | Quantity (default: 1) |
| `name` | string | Part name/label. **Normalised to UPPERCASE** on intake. |
| `material` | string | Material identifier for stock matching. **Normalised to UPPERCASE** on intake. Match this against the uppercase form of your stock's `material` field. |
| `orientationLock` | `'l'` \| `'w'` \| `''` | Orientation constraint: length-locked, width-locked, or free |
| `banding` | object | Edge banding. V3 nested form: `{ sides: { l1, l2, w1, w2 } }`. Legacy V2 flat form (`{ x1, x2, y1, y2 }` and `0`/`1` boolean shorthands) is accepted and migrated automatically. |
| `finish` | object | Surface finish. V3 nested form: `{ faces: { a, b } }`. Legacy flat `{ a, b }` (with `0`/`1`) is accepted and migrated. |
| `planing` | object | Planing configuration |
| `labels` | object | Typed saw label-printer fields for this part, the same per-part `labels` object the [V3 API](https://smartcut.dev/api-docs/v3) `Part` model documents (`barcode1`, `barcode2`, `room`, `pallet`, `drawing`, `order`, `colour`, `productInfo`, `productNumber`, 50 chars each). Supply these when your system already knows them. Use [`options.labelFields`](#saw-label-fields) instead when the **customer** should type them. |
| `customData` | object | Arbitrary key-value data attached to the part. **This is the only field that round-trips**. It appears verbatim on the matching part in the `smartcut/result` event, so it's the supported way to attach your own identifiers (order refs, line-item IDs, etc.) for reconciliation. |
| `stockId` | string | Lock part to a specific stock item (by stock `code`) |

**Pre-populating after init.** As an alternative to passing parts on `init`, host code can fire a `smartcut/load` window event whose `detail` matches the calculate-data structure (see [`smartcut/load` event](#smartcutload-input-event)). The calculator will clear existing parts and import the supplied ones the same way as init-time pre-population.

### Saw Options

Saw configuration should be provided in the `saw` property (recommended) or in `options` for backward compatibility.

#### Complete Saw Configuration
```javascript
saw: {
  stockType: 'sheet', // 'sheet', 'linear', or 'roll'
  bladeWidth: 3.2, // Blade width in mm
  cutType: 'guillotine', // 'efficiency', 'guillotine', 'beam', 'nesting'
  cutPreference: 'l', // 'l' (length), 'w' (width), 'flex' (try both per sheet)
  stackHeight: 60, // Maximum stack height in mm (beam saws only)
  efficiencyOptions: { // Optional efficiency settings
    primaryCompression: 'l' // 'l' (length) or 'w' (width) - primary compression direction
  },
  guillotineOptions: { // Optional guillotine settings
    strategy: 'efficiency', // 'efficiency' or 'time'
    maxPhase: 0, // Maximum cutting phase depth (0 = unlimited, 1-10)
    headCuts: false, // Enable head cuts for optimization
    limitStripDimensions: false // Prefer narrower strips to reduce cuts
  },
  options: { // Additional saw options
    stockSelection: 'efficiency', // 'efficiency' or 'smallest' - stock selection method
    stackingMode: 'identical', // 'dimensions', 'identical', or 'none' - part stacking mode
    minSpacing: 0 // Minimum spacing between parts in mm
  }
}
```

**Cut Type Values:**
- `'efficiency'` - Standard efficiency optimization
- `'guillotine'` - Guillotine cutting (only straight cuts across entire stock)
- `'beam'` - Beam saw optimization
- `'nesting'` - Nesting optimization (sheet stock only)

Which values apply depends on `stockType`. `'sheet'` accepts `'guillotine'`, `'efficiency'`, `'beam'` and `'nesting'`. `'roll'` accepts `'guillotine'` and `'efficiency'`. `'linear'` has no cut types at all: linear stock is simply cut to length, and `cutType` is ignored.

**Cut Preference Values:**
- `'l'` - Prefer length-first cuts
- `'w'` - Prefer width-first cuts
- `'flex'` - Try both `'l'` and `'w'` per sheet and keep the better orientation. Charged at 2× the standard credit rate.

Cut preference only applies when `cutType` is `'guillotine'` or `'beam'`.

**Stock Selection Values:**
- `'efficiency'` - Select stock that maximizes material efficiency (default)
- `'smallest'` - Prefer smaller stock sizes when possible

**Stacking Mode Values:**
- `'identical'` - Stack only parts with identical dimensions and properties (default)
- `'dimensions'` - Stack parts with same dimensions regardless of other properties
- `'none'` - Disable part stacking

### Configuration Options

#### API Version
```javascript
options: {
  apiVersion: 3 // 2 or 3 (default: 3)
}
```

**API Version Differences:**
- **Version 2**: Uses flat extras structure (`{ banding: { x1: string, x2: string, y1: string, y2: string } }`)
- **Version 3**: Uses nested extras structure (`{ extras: { banding: { sides: { l1: string, l2: string } } } }`)

See [Result Format](#result-format) for details on the differences between versions.

#### Emit API Result
```javascript
options: {
  enable: {
    emitAPIResult: true // Include full API v3 response in result (default: false)
  }
}
```

When enabled, the result object will include an `apiResultV3` property containing the complete API v3 response format. This is useful when you need the standardized API response structure regardless of which `apiVersion` is configured for the checkout result.

See [API Result V3](#api-result-v3) in the Result Format section for the structure.

#### Debug Mode
```javascript
options: {
  enable: {
    debug: true // Enable debug output in console (default: false)
  }
}
```

When enabled, additional debug information will be logged to the browser console during calculations.

#### Unit System
```javascript
options: {
  unitSystem: 'metric' // 'metric' or 'imperial' (default: 'metric')
}
```

Controls the unit system used for display and input. `'imperial'` switches dimensions to inches in the UI. Internally all values remain in millimetres.

#### Stock Grain
```javascript
options: {
  stockGrain: 'l' // 'l', 'w', or '' — default grain direction applied to stock items without an explicit grain field
}
```

#### Number Format
```javascript
options: {
  numberFormat: 'decimal', // 'decimal' or 'fraction'
  decimalPlaces: 2,
  fractionRoundTo: 0 // For fraction formatting
}
```

#### Orientation Model
```javascript
options: {
  orientationModel: 0, // 0, 1, or 2 (controls how INPUT parts handle orientation)
  resultOrientationModel: 0 // 0, 1, or 2 (controls how RESULT parts are reported)
}
```

**Orientation Model Values:**
- `0` - Default (used by the API). Orientation is set by each part's `orientationLock` property. The `l` / `w` values do not affect rotation, and `l` is simply the larger dimension.
- `1` - `l` = stock length. The `l` / `w` values drive orientation: the side given as `l` is aligned with the stock's long side.
- `2` - `l` = grain direction. The `l` / `w` values drive orientation: the side given as `l` is aligned with the stock's grain.

`resultOrientationModel` lets you display results in a different orientation convention than the inputs (e.g. accept any orientation on input but always report results with length on the longer side).

#### Part Limits
```javascript
options: {
  maxParts: 100,    // Maximum parts per order (0 = unlimited, default: 0)
  minDimension: 10, // Minimum allowed part dimension in mm (default: 0)
  partTrim: 0,      // Amount to trim from each part dimension before optimisation, in mm
  minSpacing: 0     // Minimum spacing between adjacent parts in mm
}
```

`partTrim` is applied symmetrically to `l` and `w` at calculation time. Use it when you want to optimise on rough sizes but cut to a finished size. `minSpacing` adds a gap between parts independent of blade kerf.

#### Pagination
```javascript
options: {
  partsPerPage: 10, // Parts shown per page when pagination enabled
  enable: {
    pagination: true // Enable pagination for parts list
  }
}
```

#### Field Order
```javascript
options: {
  fieldOrder: 'l, w, t, q, name, orientation' // Custom field display order
}
```

Control the order of input fields in the parts form. Provide a comma-separated list of field IDs.

#### Custom Fields
```javascript
options: {
  customFields: [
    {
      type: 'string',
      label: 'Project Name',
      id: 'projectName',
      placeholder: 'Enter project name'
    },
    {
      type: 'integer',
      label: 'Quantity',
      id: 'quantity',
      default: 1
    },
    {
      type: 'select',
      label: 'Finish',
      id: 'finish',
      outputType: 'string',
      options: [
        { label: 'Matt', value: 'matt' },
        { label: 'Gloss', value: 'gloss' }
      ]
    },
    {
      type: 'checkbox',
      label: 'Rush Order',
      id: 'rush',
      trueValue: 'yes',
      falseValue: 'no',
      default: 'no'
    }
  ]
}
```

#### Saw Label Fields

```javascript
options: {
  labelFields: [ 'room', 'order', { id: 'barcode1', label: 'CNC Program' } ]
}
```

Adds a column to the parts form for each saw label-printer field, so the customer
fills them in as they order. These are the fields the saw's own label printer /
barcode machine reads. **Today only the PTX export consumes them**. Biesse XML and
Mayer .MAY are to follow. A job whose parts carry labels but exports to a format
with no label support still calculates: the fields are simply dropped at emit time.

Unlike `customFields`, which write to the untyped `customData` bag, these write to
each part's typed `labels` object, the same contract the
[V3 API](https://smartcut.dev/api-docs/v3) documents, so a storefront order and an
API job produce identical PTX label columns.

Available fields: `barcode1`, `barcode2`, `room`, `pallet`, `drawing`, `order`,
`colour`, `productInfo`, `productNumber`.

Values your own system already holds don't need a column at all, so pass them straight
through on the part's `labels` object when pre-populating parts (see
[Parts Configuration](#parts-configuration)), exactly as an API job would. Use
`labelFields` for the fields the customer should fill in.

Each entry is either the field name on its own, or `{ id, label }` to set the column
heading. Without a `label` the heading is the field name as-is. Set one to your
operators' wording (`Job No.`, `Rack`). Values are capped at 50 characters, matching
what the saw file accepts, and longer entries are trimmed as they are typed.

##### Job-level label fields

`customer` belongs to the whole job rather than a part, so it isn't a column. Set it
on `options.labels`, the same object the [V3 API](https://smartcut.dev/api-docs/v3)
takes at the top level of a request:

```javascript
options: {
  labels: { customer: 'ACME Kitchens' }
}
```

It is sent verbatim with the calculation and printed as PTX `JOBS.CUSTOMER`. Max 100
characters. Omit it and the payload is unchanged from a shop that never sets one.

#### UI Customization

Control colors, enabled features, and field order:

```javascript
options: {
  enable: {
    // Extras + machining
    banding: false,       // Edge banding column on parts (default: false)
    finish: false,        // Finishing column on parts (default: false)
    planing: false,       // Planing column on parts (default: false)
    machining: false,     // Machining operations (holes, corners) (default: false)

    // Parts list UI
    orientation: true,    // Part orientation lock control (default: true)
    partName: true,       // Allow naming parts (default: true)
    pagination: false,    // Paginate parts list (default: false)
    progressNumber: true, // Show progress/step numbers in UI (default: true)
    focus: true,          // Highlight selected part in diagram on row focus (default: true)
    click: true,          // Allow clicking parts in the diagram to select them (default: true)
    groups: false,        // User-defined part groups (default: false)
    fullStock: false,     // "Full sheet" toggle per part — purchase entire sheet without cutting (default: false)
    imageUpload: false,   // Image upload column on parts (default: false)

    // Diagram
    diagram: true,        // Show cutting diagram (default: true)
    diagramNav: false,    // Diagram navigation controls when multiple sheets (default: false)

    // Import
    csvImport: false,     // CSV import for parts (default: false)
    csvTemplate: false,   // Show CSV template download link in import dialog (default: false)

    // Diagnostics
    debug: false          // Verbose debug logging — also flippable via `?debug` URL param (default: false)
  },
  colors: {
    partA: '#118ab2',
    partB: '#06d6a0',            // Alternating part color
    stock: '#ffd166',
    button: '#118ab2',           // Required
    buttonText: '#ffffff',       // Required
    headerBackground: '#ffffff', // Header background color
    headerText: '#212529'        // Header text color
  }
}
```

When `enable.fullStock` is on, parts can be toggled to "full sheet" mode. If multiple sheet sizes exist for the chosen material, a dimension picker dialog opens. If `fullSizeOnly: true` is set on the stock, the part is locked into full-sheet mode automatically.

### Extras Configuration

Extras are additional services like edge banding, finishing, planing, and machining that can be applied to parts with custom pricing.

#### Basic Extras Setup

```javascript
const initData = {
  stock: [...],

  // Edge banding configuration
  banding: {
    labels: ['type', 'thickness'],
    pricing: {
      'oak|1mm': 1.0,
      'oak|2mm': 1.1,
      'pine|1mm': 2.0,
      'maple|1mm': 3.0
    }
  },

  // Finish configuration
  finish: {
    labels: ['type', 'style'],
    pricing: {
      'spray|matt': 1.0,
      'spray|satin': 1.1,
      'lacquer|matt': 2.0,
      'lacquer|satin': 2.2
    }
  },

  // Planing configuration
  planing: {
    labels: ['type'],
    pricing: {
      'standard': 0.5,
      'premium': 0.8
    }
  },

  options: {...}
}
```

> **Labels must match the pricing levels.** Each `pricing` key is a `|`-joined tuple with one choice per entry in `labels`. The number of `labels` must equal the number of `|`-separated levels in **every** key. For example, `labels: ['type', 'thickness']` (2) pairs with `'oak|1mm'` (2 levels). A key with the wrong level count (or a `labels` length that doesn't match) means the extra can't be built, and the widget shows "`<Type>` options couldn't be loaded".
>
> An extra only renders when its type is enabled in `options.enable` (e.g. `options.enable.banding = true`). A disabled type ships no UI even if `labels`/`pricing` are present, and produces no error.

#### Catalogue-linked extras (admin-configured)

Banding and finish can instead be **linked to a catalogue** in the SmartCut admin (the **Extras** tab) rather than defined inline here. When a shop uses a catalogue-linked extra, SmartCut supplies its options to the widget automatically and the customer picks from an **on-demand cascade** (for example decor → finish → colour) instead of the inline `labels`/`pricing` grid above.

For these you don't author `labels`/`pricing`. The catalogue owns both the option schema and the pricing, and large lists (such as an edge-banding decor range) are loaded on demand rather than embedded in the config. CSV-imported banding lists are handled this way. This is transparent to the embedding page: the widget renders the appropriate picker per extra. The inline `labels`/`pricing` form documented above is for shops that define their extras directly in `init()`.

#### Extras Location Filtering

Control which sides and faces are available for each extra type by adding a `locations` property directly to each extra configuration:

```javascript
// Available sides: 'side.l1', 'side.l2', 'side.w1', 'side.w2' (main edges)
//                  'side.a', 'side.b', 'side.c', 'side.d' (corners)
// Available faces: 'face.a', 'face.b'

banding: {
  labels: ['material', 'thickness'],
  pricing: {...},
  locations: ['side.l1', 'side.l2', 'side.w1', 'side.w2'] // Only main edges
},

finish: {
  labels: ['type'],
  pricing: {...},
  locations: ['face.a', 'face.b'] // Both faces
},

planing: {
  labels: ['type'],
  pricing: {...},
  locations: ['side.w1', 'side.w2', 'face.a', 'face.b'] // Edges and faces
}
```

#### Extras Location Groups

Create custom groupings of locations for bulk operations with optional pricing by adding a `groups` array directly to each extra configuration:

```javascript
planing: {
  labels: ['type'],
  pricing: {
    'standard': 0.5,
    'premium': 0.8
  },
  locations: ['side.w1', 'side.w2', 'face.a', 'face.b'],
  groups: [
    {
      id: 'two-sided',
      label: '2 sided',
      locations: ['face.a', 'face.b'],
      price: 100,
      hideIndividualLocations: true // Optional: hide individual location controls when group is available
    },
    {
      id: 'four-sided',
      label: '4 sided',
      locations: ['face.a', 'face.b', 'side.w1', 'side.w2'],
      price: 200,
      hideIndividualLocations: true,
      // Optional: Group-level validation rules
      rules: {
        longSide: { min: 200 },
        shortSide: { min: 150 },
        message: '4-sided planing requires minimum 200x150mm parts'
      }
    }
  ]
},

banding: {
  labels: ['material'],
  pricing: {...},
  groups: [
    {
      id: 'all-corners',
      label: 'All Corners',
      locations: ['side.a', 'side.b', 'side.c', 'side.d']
    },
    {
      id: 'long-sides',
      label: 'Long Sides',
      locations: ['side.l1', 'side.l2']
    }
  ]
}
```

**Group Properties:**
- `id` (required) - Unique identifier for the group
- `label` (required) - Display name shown in the UI
- `locations` (required) - Array of location strings included in this group
- `price` (optional) - Fixed price for the entire group (overrides individual location pricing)
- `hideIndividualLocations` (optional) - When `true`, hides the individual location controls for locations in this group
- `rules` (optional) - Validation rules that apply when using this group (see [Group-Level Validation Rules](#group-level-validation-rules))

#### Extras Validation Rules

Apply dimension constraints to control which parts can have extras applied by adding a `rules` property directly to each extra configuration:

```javascript
planing: {
  labels: ['type'],
  pricing: {...},
  locations: [...],
  rules: {
    t: {
      min: 8,
      max: 230
    },
    shortSide: {
      min: 10,
      max: 620
    },
    longSide: {
      max: 1000
    },
    message: 'Planing requires thickness 8-230mm, short side 10-620mm, and long side max 1000mm'
  }
},

banding: {
  labels: ['material'],
  pricing: {...},
  rules: {
    t: {
      min: 12,
      max: 30
    },
    message: 'Banding is only available for 12-30mm thick materials'
  }
},

finish: {
  labels: ['type'],
  pricing: {...},
  rules: {
    longSide: {
      max: 2400
    },
    shortSide: {
      max: 1200
    },
    message: 'Finish is only available for parts smaller than 2400x1200mm'
  }
}
```

**Validation Rule Fields:**
- `longSide.min` / `longSide.max` - Constraints on the longer dimension
- `shortSide.min` / `shortSide.max` - Constraints on the shorter dimension
- `t.min` / `t.max` - Thickness constraints
- `formula` (optional) - JavaScript expression for complex validation (can reference `longSide`, `shortSide`, `t`)
- `message` - Custom error message shown when validation fails
- `locations` (optional) - Array of location-specific rules (see [Location-Specific Validation Rules](#location-specific-validation-rules))

When a part doesn't meet the validation rules, the extras options will be disabled and an error message displayed.

#### Location-Specific Validation Rules

Apply different validation constraints to individual locations within an extra type. This allows fine-grained control over which parts can use specific edges or faces:

```javascript
banding: {
  labels: ['material'],
  pricing: {...},
  rules: {
    // Type-level rules (apply to all locations by default)
    longSide: { min: 100 },
    shortSide: { min: 50 },
    message: 'Banding requires minimum 100x50mm parts',

    // Location-specific rules (override type-level for specific locations)
    locations: [
      {
        location: 'side.l1',
        longSide: { min: 500 },
        message: 'L1 banding only available for parts >= 500mm long side'
      },
      {
        location: 'side.l2',
        longSide: { min: 500 },
        message: 'L2 banding only available for parts >= 500mm long side'
      }
    ]
  }
}
```

**Location Rule Properties:**
- `location` (required) - The location this rule applies to (e.g., `'side.l1'`, `'face.a'`)
- `longSide` / `shortSide` / `t` - Dimension constraints for this location
- `formula` (optional) - JavaScript expression for complex validation
- `message` (optional) - Custom error message for this location

#### Group-Level Validation Rules

Groups can have their own validation rules that apply when any location in the group is selected:

```javascript
planing: {
  labels: ['type'],
  pricing: {...},
  groups: [
    {
      id: 'four-sided',
      label: '4 Sided',
      locations: ['face.a', 'face.b', 'side.w1', 'side.w2'],
      price: 200,
      rules: {
        longSide: { min: 200 },
        shortSide: { min: 150 },
        t: { min: 18 },
        message: '4-sided planing requires minimum 200x150x18mm parts'
      }
    }
  ]
}
```

#### Rule Precedence

When multiple rules could apply to a location, the most specific rule wins:

1. **Location-specific rule** - Rules defined in `rules.locations[]` for a specific location
2. **Group rule** - Rules defined on a group that contains the location
3. **Type-level rule** - The base rules for the extra type

Only one rule level applies per location - the most specific one completely overrides less specific rules.

**Example:**
```javascript
banding: {
  rules: {
    longSide: { min: 100 },  // Type-level: default for all locations
    locations: [
      { location: 'side.l1', longSide: { min: 500 } }  // Location-specific: overrides for l1
    ]
  },
  groups: [
    {
      id: 'all-sides',
      locations: ['side.l1', 'side.l2', 'side.w1', 'side.w2'],
      rules: { longSide: { min: 200 } }  // Group rule: applies to group members without location rules
    }
  ]
}
```

In this example:
- `side.l1`: Uses location rule (min 500mm) - most specific
- `side.l2`, `side.w1`, `side.w2`: Use group rule (min 200mm) - group is more specific than type
- Any other location: Uses type-level rule (min 100mm) - fallback

### Part Validation Rules

Apply dimension constraints to parts themselves to control which parts can be processed by adding a `partRules` property to the init data:

```javascript
const initData = {
  stock: [...],

  // Part validation rules
  partRules: {
    // Basic dimension constraints
    l: {
      min: 50,
      max: 2400
    },
    w: {
      min: 20,
      max: 1200
    },
    t: {
      min: 12,
      max: 30
    },
    longSide: {
      min: 100,
      max: 2400
    },
    shortSide: {
      min: 50,
      max: 1200
    },

    // Cross-dimensional rule: at least one side must meet primaryMin,
    // and the other side must meet secondaryMin
    crossDimensionalRule: {
      primaryMin: 50,
      secondaryMin: 20
    },

    // Optional custom message
    message: 'At least one side must be ≥ 50 mm and the other side must be ≥ 20 mm'
  },

  options: {...}
}
```

**Part Validation Rule Fields:**
- `l.min` / `l.max` - Length constraints
- `w.min` / `w.max` - Width constraints
- `t.min` / `t.max` - Thickness constraints
- `longSide.min` / `longSide.max` - Constraints on the longer dimension
- `shortSide.min` / `shortSide.max` - Constraints on the shorter dimension
- `crossDimensionalRule` (optional) - Cross-dimensional validation
  - `primaryMin` - At least one side must be ≥ this value
  - `secondaryMin` - The other side must be ≥ this value
- `formula` (optional) - Formula expression for complex validation (can reference `l`, `w`, `t`, `longSide`, `shortSide`)
  - Supports arithmetic operators: `+`, `-`, `*`, `/`
  - Supports comparison operators: `>`, `<`, `>=`, `<=`, `==`
  - Supports logical operators: `&&` (AND), `||` (OR)
  - Supports ternary operator: `condition ? trueValue : falseValue`
- `message` - Custom error message shown when validation fails

**Example with formula:**
```javascript
partRules: {
  formula: '(l >= 50 && w >= 20) || (w >= 50 && l >= 20)',
  message: 'At least one side must be ≥ 50 mm and the other side must be ≥ 20 mm'
}
```

**Complex formula example:**
```javascript
partRules: {
  formula: '(l * w) > 100000 && t >= 12',
  message: 'Part must have area > 100,000 mm² and thickness ≥ 12 mm'
}
```

When a part doesn't meet the validation rules, an error message will be displayed below the part and calculation will be blocked until the issue is resolved.

### Custom Validation Rules

For more complex validation scenarios, you can use custom validation rules that support full access to part properties including extras and machining. This is configured via the EcommerceSettings admin page or by adding a `customValidation` property to the init data:

```javascript
const initData = {
  stock: [...],

  // Custom validation rules
  customValidation: {
    enabled: true,
    rules: [
      {
        id: 'min-size',
        enabled: true,
        name: 'Minimum Part Size',
        formula: 'longSide >= 100 && shortSide >= 50',
        message: 'Parts must be at least 100mm x 50mm'
      },
      {
        id: 'banding-thickness',
        enabled: true,
        name: 'Banding Thickness Check',
        formula: '!hasBanding || t >= 12',
        message: 'Banding requires minimum 12mm thickness'
      },
      {
        id: 'machining-thickness',
        enabled: true,
        name: 'Machining Thickness Check',
        formula: '!hasMachining || t >= 18',
        message: 'Machining operations require minimum 18mm thickness'
      }
    ]
  },

  options: {...}
}
```

**Custom Validation Rule Fields:**
- `id` - Unique identifier for the rule
- `enabled` - Whether the rule is active (default: true)
- `name` - User-friendly name for the rule (optional)
- `formula` - Condition that must evaluate to true for the part to be valid
- `message` - Error message shown when validation fails

**Available Variables:**

| Variable | Type | Description |
|----------|------|-------------|
| `l` | number | Part length |
| `w` | number | Part width |
| `t` | number | Part thickness |
| `q` | number | Part quantity |
| `longSide` | number | max(l, w) |
| `shortSide` | number | min(l, w) |
| `material` | string | Material name |
| `name` | string | Part name |
| `grain` | string | The part's grain direction, derived from its `orientationLock` and the grain of the stock it is bound to: `'l'`, `'w'`, or `''` when the part is free to rotate or the stock has no grain |
| `fullStock` | boolean | Full stock purchase flag |
| `hasBanding` | boolean | True if any banding applied |
| `hasFinish` | boolean | True if any finish applied |
| `hasPlaning` | boolean | True if any planing applied |
| `hasMachining` | boolean | True if any machining operations |
| `extras.banding.sides.l1` | string | Banding on long side 1 |
| `extras.banding.sides.l2` | string | Banding on long side 2 |
| `extras.banding.sides.w1` | string | Banding on short side 1 |
| `extras.banding.sides.w2` | string | Banding on short side 2 |
| `extras.finish.faces.a` | string | Finish on face A |
| `extras.finish.faces.b` | string | Finish on face B |
| `machining.holes` | number | Number of holes |
| `machining.corners` | number | Number of corner operations |

**Supported Operators:**
- Arithmetic: `+`, `-`, `*`, `/`
- Comparison: `>`, `<`, `>=`, `<=`, `==`
- Logical: `&&` (AND), `||` (OR), `!` (NOT)
- Ternary: `condition ? trueValue : falseValue`
- Parentheses: `(expression)`

**Example Rules:**

```javascript
// Minimum area requirement
{
  formula: '(l * w) >= 10000',
  message: 'Parts must have minimum 10,000mm² area'
}

// Combined extras check
{
  formula: '!(hasBanding && hasFinish) || longSide >= 200',
  message: 'Parts with both banding and finish must be at least 200mm'
}

// Specific banding requirement
{
  formula: "extras.banding.sides.l1 == '' || t >= 15",
  message: 'Banding on long side 1 requires minimum 15mm thickness'
}

// Machining hole limit
{
  formula: 'machining.holes <= 10',
  message: 'Maximum 10 holes per part'
}
```

When a part fails custom validation, an error message will be displayed and calculation will be blocked until the issue is resolved.

#### Complete Extras Example

```javascript
const initData = {
  stock: [
    {
      l: 2440,
      w: 1220,
      t: 18,
      cost: 65,
      material: 'Plywood'
    }
  ],

  // Edge banding
  banding: {
    labels: ['material', 'thickness'],
    pricing: {
      'oak|1mm': 1.0,
      'oak|2mm': 1.2,
      'pine|1mm': 0.8,
      'maple|1mm': 1.5
    },
    locations: ['side.l1', 'side.l2', 'side.w1', 'side.w2'],
    rules: {
      t: { min: 12, max: 30 },
      message: 'Banding only available for 12-30mm thick materials'
    }
  },

  // Finishing
  finish: {
    labels: ['type', 'style'],
    pricing: {
      'spray|matt': 5.0,
      'spray|satin': 5.5,
      'lacquer|matt': 8.0,
      'lacquer|satin': 8.5
    },
    locations: ['face.a', 'face.b'],
    rules: {
      longSide: { max: 2400 },
      shortSide: { max: 1200 },
      message: 'Finish is only available for parts smaller than 2400x1200mm'
    }
  },

  // Planing
  planing: {
    labels: ['type'],
    pricing: {
      'standard': 2.0,
      'premium': 3.5
    },
    locations: ['face.a', 'face.b', 'side.w1', 'side.w2'],
    groups: [
      {
        id: 'two-sided',
        label: 'Two Sides (Top & Bottom)',
        locations: ['face.a', 'face.b'],
        price: 100,
        hideIndividualLocations: true
      },
      {
        id: 'four-sided',
        label: 'Four Sides (All Faces & Edges)',
        locations: ['face.a', 'face.b', 'side.w1', 'side.w2'],
        price: 200,
        hideIndividualLocations: true
      }
    ],
    rules: {
      t: { min: 8, max: 230 },
      shortSide: { min: 10, max: 620 },
      longSide: { max: 1000 },
      message: 'Planing requires: thickness 8-230mm, width 10-620mm, length max 1000mm'
    }
  },

  saw: {
    stockType: 'sheet',
    bladeWidth: 3.2,
    cutType: 'guillotine',
    cutPreference: 'l'
  },

  options: {
    locale: 'en-US',
    currency: 'USD',
    apiVersion: 3, // 2 or 3 (default: 3)

    // Enable extras features
    enable: {
      banding: true,
      finish: true,
      planing: true,
      machining: false
    }
  }
}
```

### Product Catalog

Surface a product browser on the checkout so customers can pick from your catalogue before configuring parts. Independent of [Product Filtering](#product-filtering) (which filters the stock list).

```javascript
const initData = {
  stock: [...],
  products: {
    enabled: true,        // Show the product browser tab
    showCategories: true  // Group products by category in the browser
  },
  options: {...}
}
```

A user picking a "simple" product fires [`smartcut/product-selected`](#smartcutproduct-selected). Picking a "formula" (configurable) product hands off to the [Configurator](#configurator-formula-products) instead. Stock filter "Create Cut List" confirmations fire [`smartcut/selection-confirmed`](#smartcutselection-confirmed).

You can deep-link directly to a product by appending `?product=<productId>` to the page URL. The calculator picks up the parameter on mount.

### API / Order Lookup

Wire up the storefront's order-lookup view and the live-inventory watcher by supplying the host's API config:

```javascript
const initData = {
  api: {
    baseUrl: 'https://your-storefront.example.com',
    orgSlug: 'your-org-slug',
    isCustomDomain: false,  // true if storefront is on a custom domain
    wsServer: 'wss://your-storefront.example.com', // optional
    orgId: '66abc123...'    // optional Mongo org id (required with wsServer)
  },
  options: {...}
}
```

Appending `?view=track-order` (or `?view=order-lookup`) to the page URL opens the order-lookup view on mount instead of the calculator.

When both `wsServer` and `orgId` are set, the calculator connects via Socket.IO and fires [`smartcut/inventoryUpdated`](#smartcutinventoryupdated) whenever stock changes for the org.

### Configurator (Formula Products)

Enable formula-driven (parametric) products, typically used for configurable cabinets. Customer inputs such as height and width drive a JS formula that emits the parts list:

```javascript
const initData = {
  config: {
    configurator: {
      enabled: true,
      url: 'https://your-host.example.com/configurator.html', // optional iframe URL
      spec: { /* configurator spec, opaque to the widget */ }
    }
  },
  options: {...}
}
```

A product whose `type === 'formula'` (via the Product Catalog) routes to the Configurator. On confirmation the calculator receives the generated parts and falls through to the normal calculate flow.

### Machining Configuration

Advanced machining features for holes, corners, and custom operations:

```javascript
const initData = {
  machining: {
    faces: {
      enabled: true
    },
    holes: {
      enabled: true,
      defaultDiameter: 5,
      minDiameter: 5,
      maxDiameter: 10,
      enableDepth: true,
      minDepth: 5
    },
    hingeHoles: {
      enabled: true,
      minimumHoleDistance: 10,
      defaultDistanceFromEdge: 22,
      defaultOuterSpacing: 10,
      defaultHingeLength: 50
    },
    shelfHoles: {
      enabled: true,
      diameters: [5, 10]
    },
    corners: {
      enabled: true,
      types: ['radius', 'bevel'],
      enableBanding: true
    }
  },

  options: {
    enable: {
      machining: true
    }
  }
}
```

## Events

The embedded checkout dispatches custom window events for integration. Events fall into two groups:

- **Output events** (`smartcut/...`). The widget dispatches these on `window`, and host code listens.
- **Input events** ([`smartcut/load`](#smartcutload-input-event)). Host code dispatches these, and the widget listens.

### `smartcut/ready`
Fired when the calculator is loaded and ready to initialize.

```javascript
window.addEventListener('smartcut/ready', () => {
  window.smartcutCheckout.init(initData)
})
```

### `smartcut/initComplete`
Fired when initialization is complete.

```javascript
window.addEventListener('smartcut/initComplete', () => {
  console.log('Calculator initialized')
})
```

### `smartcut/calculating`
Fired when a calculation starts.

```javascript
window.addEventListener('smartcut/calculating', () => {
  console.log('Calculation in progress...')
})
```

### `smartcut/beforeCalculate`
Fired after internal validation passes but before the calculation is sent to the server. This allows you to add custom validation logic using JavaScript and optionally prevent the calculation from proceeding.

**Event properties:**
- `cancelable: true` - Call `event.preventDefault()` to cancel the calculation
- `event.detail.data` - The calculation data that would be sent (parts, stock, saw config, etc.)
- `event.detail.error` - Set this to a string to display a custom error message

```javascript
window.addEventListener('smartcut/beforeCalculate', (event) => {
  const calculationData = event.detail.data

  // Example: Custom validation - check total quantity
  const totalQuantity = calculationData.inputShapes.reduce(
    (sum, part) => sum + (part.q || 1),
    0
  )

  if (totalQuantity > 500) {
    // Prevent the calculation
    event.preventDefault()
    // Set a custom error message to display
    event.detail.error = 'Maximum 500 parts per order. Please split your order.'
    return
  }

  // Example: Check part dimensions
  for (const part of calculationData.inputShapes) {
    if (part.l > 3000 || part.w > 2000) {
      event.preventDefault()
      event.detail.error = `Part "${part.name || 'Unnamed'}" exceeds maximum dimensions (3000x2000mm)`
      return
    }
  }

  // Validation passed - calculation will proceed
  console.log('Custom validation passed, calculating...')
})
```

**When the calculation is prevented:**
- The calculate button is re-enabled (thinking state is reset)
- If `event.detail.error` is set, the error message is displayed to the user
- The `smartcut/result` event will not fire

**Calculation data structure (`event.detail.data`):**
```typescript
{
  inputSaw: {
    stockType: string,
    bladeWidth: number,
    cutType: string,
    cutPreference: string,
    // ... other saw properties
  },
  inputShapes: Array<{
    l: number,
    w: number,
    t: number | null,
    q: number,
    material: string | null,
    name: string | null,
    orientationLock: string | null,
    extras?: {...},
    customData?: Record<string, any>
  }>,
  inputStock: Array<{
    l: number,
    w: number,
    t: number | null,
    q: number,
    material: string | null,
    cost: number | null,
    // ... other stock properties
  }>,
  extrasOptions: {...} | null
}
```

### `smartcut/result`
Fired when optimization results are available.

```javascript
window.addEventListener('smartcut/result', (e) => {
  const result = e.detail

  // Optimization metadata
  console.log(result.metadata)

  // Parts used in optimization
  console.log(result.parts)

  // Stock sheets used
  console.log(result.stock)

  // Formatted pricing with currency
  console.log(result.checkout.formattedTotalStockCost)
  console.log(result.checkout.formattedBandingCost)
  console.log(result.checkout.formattedFinishCost)
  console.log(result.checkout.formattedPlaningCost)
})
```

### `smartcut/validationError`
Fired when input validation fails.

```javascript
window.addEventListener('smartcut/validationError', () => {
  console.log('Please check your inputs')
})
```

### `smartcut/product-selected`
Fired when a customer picks a **simple** (non-configurable) product from the Product Catalog browser.

```javascript
window.addEventListener('smartcut/product-selected', (event) => {
  console.log('Picked product:', event.detail.product)
  // event.detail = { product: Product, type: 'simple' }
})
```

Formula products do not emit this event. They route to the Configurator instead.

### `smartcut/selection-confirmed`
Fired when the customer presses **"Create Cut List"** in the Product Filtering UI (the stock filter's confirmation step).

```javascript
window.addEventListener('smartcut/selection-confirmed', () => {
  console.log('Customer confirmed stock selection')
})
```

No detail payload. The widget scrolls to the calculator after dispatching.

### `smartcut/inventoryUpdated`
Fired when the live-inventory watcher detects a stock change for the configured org. Requires [`api.wsServer` and `api.orgId`](#api--order-lookup) to be set.

```javascript
window.addEventListener('smartcut/inventoryUpdated', () => {
  // Refresh your stock display or re-run a calculation
})
```

No detail payload.

### `smartcut/load` (input event)

Host-dispatched event the widget **listens** for. Use this to load a saved cut list after init. It is equivalent to pre-populating `parts` on init, but available at any time:

```javascript
window.dispatchEvent(new CustomEvent('smartcut/load', {
  detail: {
    inputs: {
      parts: [
        { l: 600, w: 400, t: 18, q: 4, material: 'Plywood', name: 'Shelf' },
        { l: 800, w: 300, t: 18, q: 2, material: 'Plywood', name: 'Side' }
      ]
    }
  }
}))
```

The widget clears existing parts and loads each part via the same path as init-time pre-population. Useful when the customer signs in and you want to restore their last basket, or when integrating with a "saved designs" feature in your storefront.

## Result Format

The result object returned via the `smartcut/result` event contains different structures based on the `apiVersion` setting.

### API Version 2 Result Structure

When `apiVersion: 2` is set, results use a **flat extras structure**:

```typescript
{
  jobId: number,

  metadata: {
    totalStockCost: number,
    bandingLengthByType: Record<string, number>,
    finishAreaByType: Record<string, number>,
    planingAreaByType: Record<string, number>,
    addedPartTally: Record<string, number>,
    usedStockTally: Record<string, number>,
    unplacedParts: Array<Part>
  },

  parts: Array<{
    l: number,
    w: number,
    t: number | null,
    q: number,
    material: string | null,
    name: string | null,
    orientationLock: '' | 'l' | 'w' | null,
    // Flat extras structure (API v2)
    banding?: Record<string, string | boolean>, // e.g., { x1: 'oak|1mm', x2: 'oak|1mm', y1: '', y2: '' }
    finish?: Record<string, string | boolean>, // e.g., { a: true, b: false }
    planing?: Record<string, string | boolean>,
    customData?: Record<string, any>
  }>,

  stock: Array<{
    id: string,
    name: string | null,
    l: number,
    w: number,
    t: number | null,
    material: string | null,
    q: number,
    trim?: { x1: number, x2: number, y1: number, y2: number },
    cost?: number,
    discount?: number,        // Configured percentage discount (0–100), surfaced to pricing formulas
    pricingFormula?: string,  // Per-stock pricing override evaluated at checkout
    // Analysis is aggregated across all stock with same parentId when stacking
    // Most values are summed; areaEfficiency is averaged
    analysis?: {
      areaEfficiency: number,   // Average efficiency across all stacked stock
      finishArea: number,       // Total finish area
      bandingLength: number,    // Total banding length
      partArea: number,         // Total part area
      totalParts: number,       // Total number of parts
      stackedNumberOfCuts: number,
      numberOfCuts: number,
      stackedCutLength: number,
      cutLength: number,
      rollLength: number
    },
    sheets?: Array<{...}>,      // Per-sheet analysis (same shape as `analysis` per row) — see V3 below
    customData?: Record<string, any>
  }>,

  offcuts: Array<{
    l: number,
    w: number,
    t: number | null,
    q: number,
    stockId: string
  }>,

  inputs: {
    parts: Array<Part> // Same structure as parts above
  }
}
```

### API Version 3 Result Structure

When `apiVersion: 3` is set (default), results use a **nested extras structure**:

```typescript
{
  jobId: number,

  metadata: {
    totalStockCost: number,
    bandingLengthByType: Record<string, number>,
    finishAreaByType: Record<string, number>,
    planingAreaByType: Record<string, number>,
    addedPartTally: Record<string, number>,
    usedStockTally: Record<string, number>,
    unplacedParts: Array<Part>
  },

  parts: Array<{
    l: number,
    w: number,
    t: number | null,
    q: number,
    material: string | null,
    name: string | null,
    orientationLock: '' | 'l' | 'w' | null,
    // Nested extras structure (API v3)
    extras?: {
      banding?: {
        sides: Record<string, string | boolean> // e.g., { l1: 'oak|1mm', l2: 'oak|1mm', w1: '', w2: '' }
      },
      finish?: {
        faces: Record<string, string | boolean> // e.g., { a: true, b: false }
      },
      planing?: {
        sides?: Record<string, string | boolean>,
        faces?: Record<string, string | boolean>
      }
    },
    customData?: Record<string, any>
  }>,

  stock: Array<{
    id: string,
    name: string | null,
    l: number,
    w: number,
    t: number | null,
    material: string | null,
    q: number,
    trim?: { l1: number, l2: number, w1: number, w2: number }, // Note: uses l1/l2/w1/w2 in v3
    cost?: number,
    // Analysis is aggregated across all stock with same parentId when stacking
    // Most values are summed; areaEfficiency is averaged
    analysis?: {
      areaEfficiency: number,   // Average efficiency across all stacked stock
      finishArea: number,       // Total finish area
      bandingLength: number,    // Total banding length
      partArea: number,         // Total part area
      totalParts: number,       // Total number of parts
      stackedNumberOfCuts: number,
      numberOfCuts: number,
      stackedCutLength: number,
      cutLength: number,
      rollLength: number
    },
    // Additional v3 fields
    color?: { hex: string, name: string } | string,
    weight?: number,
    imageUrl?: string,
    tags?: string[],
    available?: boolean,
    discount?: number,         // Configured percentage discount (0–100), surfaced to pricing formulas
    pricingFormula?: string,   // Per-stock pricing override evaluated at checkout
    sheets?: Array<{           // Per-sheet analysis — present when the cut server emits per-sheet data.
      areaEfficiency: number,  // Pricing formulas iterate these when set so usedFraction reflects each
      finishArea: number,      // physical sheet, not the order-wide average.
      bandingLength: number,
      partArea: number,
      totalParts: number,
      stackedNumberOfCuts: number,
      numberOfCuts: number,
      stackedCutLength: number,
      cutLength: number,
      rollLength: number
    }>,
    customData?: Record<string, any>
  }>,

  offcuts: Array<{
    l: number,
    w: number,
    t: number | null,
    q: number,
    stockId: string
  }>,

  inputs: {
    parts: Array<Part> // Same structure as parts above
  }
}
```

### Using Result Data

```javascript
window.addEventListener('smartcut/result', (e) => {
  const result = e.detail

  // Get total cost from metadata
  const totalCost = result.metadata.totalStockCost

  // Get parts with optimization data
  const optimizedParts = result.parts

  // Get stock usage
  const stockUsed = result.stock

  // Get offcuts for reuse
  const offcuts = result.offcuts

  // Access extras based on API version
  const apiVersion = 3 // Your configured version

  result.parts.forEach(part => {
    if (apiVersion === 2) {
      // API v2: Flat structure
      const bandingX1 = part.banding?.x1
      const finishFaceA = part.finish?.a
    } else {
      // API v3: Nested structure
      const bandingL1 = part.extras?.banding?.sides?.l1
      const finishFaceA = part.extras?.finish?.faces?.a
    }
  })

  // Get extras costs breakdown from metadata
  const bandingCosts = result.metadata.bandingLengthByType
  const finishCosts = result.metadata.finishAreaByType
  const planingCosts = result.metadata.planingAreaByType
})
```

### API Result V3

When the `emitAPIResult` option is enabled, the result object includes an `apiResultV3` property containing the complete API v3 response. This provides a standardized format matching the SmartCut API v3 specification:

```typescript
{
  // Standard checkout result properties...
  jobId: number,
  metadata: {...},
  parts: [...],
  stock: [...],
  offcuts: [...],
  inputs: {...},

  // Additional API v3 response (when emitAPIResult: true)
  apiResultV3?: {
    jobId: number,
    saw: {
      stockType: string,
      bladeWidth: number,
      cutType: string,
      cutPreference: string
    },
    stockList: Array<{...}>,
    shapeList: Array<{...}>,
    cutList: Array<{...}>,
    offcuts: Array<{...}>,
    unusableShapes: Array<{...}>,
    metadata: {...}
  }
}
```

This is useful when integrating with systems that expect the full API v3 response format, or when you need access to additional data like `cutList` that isn't included in the standard checkout result.

```javascript
window.addEventListener('smartcut/result', (e) => {
  const result = e.detail

  // Access the API v3 response if available
  if (result.apiResultV3) {
    console.log('Cut list:', result.apiResultV3.cutList)
    console.log('Shape list:', result.apiResultV3.shapeList)
  }
})
```


## Product Filtering

Enable dynamic stock selection with filtering and search:

```javascript
const initData = {
  stock: [
    {
      l: 2800,
      w: 2070,
      t: 18,
      cost: 95,
      material: 'White MDF',
      code: 'MDF-2800-18',
      category: 'Sheet Materials',
      tags: ['mdf', 'white', 'standard'],
      available: true
    }
  ],

  stockFilter: {
    enabled: true,
    config: {
      displayMode: 'grid', // 'grid' or 'list'
      enableSearch: true,
      itemsPerPage: 20,
      allowMultipleSelection: true,
      availableFilters: [
        {
          field: 'material',
          type: 'multiselect',
          label: 'Material'
        },
        {
          field: 't',
          type: 'range',
          label: 'Thickness (mm)',
          min: 0,
          max: 30
        },
        {
          field: 'category',
          type: 'multiselect',
          label: 'Category'
        }
      ]
    }
  },

  options: {...}
}
```

## Support

- **Email**: hello@cutrevolution.com
- **Chat**: https://smartcut.dev/
## Related

- [Hosted store](/docs/ecommerce/) is the storefront this checkout backs.
- [Inventory API](/docs/ecommerce-inventory/) covers the materials and stock behind the quote.
- [Store config MCP](/docs/ecommerce-mcp/) configures the same store from an LLM client.

---

# Store config MCP

URL: https://smartcut.dev/docs/ecommerce-mcp

> Configure your SmartCut storefront from your own LLM client over MCP: materials, stock, pricing, extras and formulas.

If you run a [hosted SmartCut store](/docs/ecommerce), you can configure it from your own LLM client (Claude Desktop, Claude.ai, Cursor or a custom agent) over the [Model Context Protocol](https://modelcontextprotocol.io). "Add an 18mm oak product line", "raise banding prices 10%", "list my out-of-stock sheets" become things you can just ask for.

It exposes the same store-configuration operations as the admin UI: materials, stock, settings, pricing, extras and formula validation. Writes go through the **same validated path**, so nothing the MCP does can put your store into a state the admin couldn't.

## Endpoint

```text
POST https://api.smartcut.dev/ecommerce/mcp
```

A hosted, remote MCP server over **Streamable HTTP**, with nothing to install. Each request is scoped to **your store only**: your organisation is resolved from your API key, so a tool can never read or change another store's data.

## Credentials

You authenticate with your **existing SmartCut API key**. There is no separate MCP token.

1. Sign in at [smartcut.dev/account](https://smartcut.dev/account). You need an active **e-commerce subscription** with **API access**.
2. Copy your **API key** from the account page.
3. Give it to your MCP client as an `Authorization` header (see below). The value is the **raw key**, with no `Bearer ` prefix.

:::caution
Your API key is a secret and can change your live store. Keep it in an environment variable, not inline in a config file, and never commit it.
:::

## Connect a client

Most clients connect through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. Add the store server to your client's MCP config (e.g. Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "smartcut-store": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.smartcut.dev/ecommerce/mcp",
        "--header", "Authorization:${SMARTCUT_API_KEY}"
      ],
      "env": {
        "SMARTCUT_API_KEY": "your-api-key"
      }
    }
  }
}
```

Passing the key via `env` keeps it out of the args list and avoids clients that strip spaces from arguments. Note there is no space after `Authorization:`.

If your client supports remote/HTTP MCP servers **natively** (a URL plus custom headers), use:

- **URL**: `https://api.smartcut.dev/ecommerce/mcp`
- **Header**: `Authorization: <your-api-key>`

## Tools

| Tool group | Does |
|---|---|
| `ecommerce_materials_list` / `_get` / `_create` / `_update` / `_delete` | Manage materials (product lines). |
| `ecommerce_stock_list` / `_get` / `_create` / `_update` / `_delete` | Manage stock (the cuttable sheets / lengths). |
| `ecommerce_settings_get` / `_update` | Operational store settings. |
| `ecommerce_pricing_get` / `_update` | Global pricing configuration. |
| `ecommerce_extras_list` / `_get` / `_create` / `_update` / `_delete` / `_delete_all` / `_reorder` | Manage extras: banding, finish, planing, machining, add-ons. |
| `ecommerce_formula_validate` | Dry-run an extras or shipping pricing formula before saving it. |

### Safety

- Destructive and bulk tools (`*_delete`, `*_delete_all`, bulk creates) require an explicit `confirm: true` and echo what will change before acting, so the model can't delete a product line on a misread.
- Settings are operational only. The MCP will not touch payment credentials, custom-domain verification, or publish state. Those stay in the admin UI by design.

## See also

- [Hosted store](/docs/ecommerce) covers the storefront, analytics, webhooks and order APIs.
- [MCP server](/docs/mcp) is the optimisation counterpart, for running cutting calculations.

---

# Embedded Diagram

URL: https://smartcut.dev/docs/embed

> Embed a SmartCut cut list visualisation on your website using an iframe

Embed an interactive cutting layout visualisation on your website using a simple iframe. It displays the optimised cut layout for a given calculation result. It can also talk to the surrounding page via `postMessage`.

Point it at a result of ours by job ID (`result`), or at a copy of the result
JSON you host yourself (`src`, see [Your own JSON](#your-own-json)).

## Quick Start

```html
<!-- Replace the result value with your calculation job ID -->
<div id="smartcut-vis-message">Loading...</div>

<iframe
  id="smartcut-vis"
  src="https://cutlistevo.com/embed/?result=1733"
  allowtransparency="true"
  frameborder="0"
  height="0"
></iframe>
```

Set the `src` attribute dynamically using the `jobId` returned by the `/v3/calculate` API call:

```javascript
const jobId = 1733 // returned by /v3/calculate
document.getElementById('smartcut-vis').src =
  `https://cutlistevo.com/embed/?result=${jobId}`
```

A live example is available at: `https://cutlistevo.com/embed/?result=1733`

A result stays available for 24 hours. Past that the diagram shows "no result",
unless you kept the JSON and served it yourself, which is what `src` is for.

## Parameters

Pass parameters as query string values on the iframe `src` URL.

| Parameter | Description |
|-----------|-------------|
| `result` | The calculation job ID to display. **Required** unless `src` is given |
| `src` | URL of a result JSON you host yourself, described in [Your own JSON](#your-own-json). Used in place of `result` |
| `dn` | Set to `true` to disable the stock navigation controls |
| `hs` | Set to `true` to hide the stock information header |

## Your own JSON

Save the result JSON when you receive it, put it anywhere you can serve a file
from, whether that is S3, your own CDN or your app's storage, then point the
embed at that URL with `src` instead of `result`:

```javascript
const src = encodeURIComponent('https://cdn.example.com/jobs/1733.json')
document.getElementById('smartcut-vis').src =
  `https://cutlistevo.com/embed/?src=${src}`
```

URL-encode the value, so a query string of its own does not merge into the
embed's. Every other parameter behaves exactly as it does for `result`, including
colours, navigation and `postMessage`.

This is worth doing when:

- **the diagram has to outlive our copy**, such as an order confirmation, an
  archived quote or a job sheet a customer opens weeks later
- **the page must not depend on our API**. With `src` the iframe never calls us,
  so the layout still draws if our service is unreachable
- **the result never came from a job you can re-request**, because you hold the
  JSON and not a job ID we can look up

### Accepted JSON

Either of the two result documents you can already obtain:

| Document | Where it comes from |
|----------|---------------------|
| V3 API result | the body of `GET /v3/result?id=…`, or the result delivered for `POST /v3/calculate` |
| Embed result | the body of `GET /result/embedded?id=…` |

V1/V2 API results are **not** accepted. They name sides `x1/x2/y1/y2` and nest
parts under each stock, which is a different document rather than a renamed one.
Re-fetch the job through V3, or store the embed result.

Store the response body verbatim, with no re-shaping and no unwrapping. If your own
records wrap it (`{ order, result }`), keep the result at a URL of its own:

```javascript
// when the calculation completes, keep a copy
const result = await fetch(`https://api.smartcut.dev/v3/result?id=${jobId}`, {
  headers: { Authorization: process.env.SMARTCUT_API_KEY } // raw key, no Bearer
}).then((r) => r.json())

await putSomewherePublic(`jobs/${jobId}.json`, JSON.stringify(result))
```

### Requirements

- Serve the file over **HTTPS** from an absolute URL. An `http` URL is blocked as
  mixed content by the browser.
- Send `Access-Control-Allow-Origin: https://cutlistevo.com` (or `*`) with the
  file. The iframe fetches it directly, so without CORS the browser blocks it.
- Keep the file **publicly readable**: the request is sent without credentials,
  so cookies and auth headers of yours play no part.
- Stay under **25 MB**.

### Diagnosing a failure

The reason is posted to the surrounding page as an `error` message (see
[iframe Messages](#iframe-messages)) and logged to the iframe's console:

| Message | Meaning |
|---------|---------|
| `src must be an absolute URL` | the value was relative, or not a URL |
| `src must be an http or https URL` | the value used another scheme (`data:`, `file:`, …) |
| `could not fetch the JSON at src` | the host did not answer, or CORS blocked the read |
| `src responded 404` | the host answered, with that status |
| `src did not return valid JSON` | the body did not parse, often an error page |
| `src JSON must be a V3 API result …` | the JSON parsed but is not a result document |

## Colours

Customise the colour scheme using HEX values (without the `#` prefix).

| Parameter | Description |
|-----------|-------------|
| `pca` | Part colour A |
| `pcb` | Part colour B |
| `pch` | Part colour on hover |
| `pcs` | Part colour when selected |
| `sc` | Stock (board) background colour |
| `tc` | Text colour |

**Example:**

```
https://cutlistevo.com/embed/?result=1733&pca=BAD0F5&pcb=346AC9&pch=E09318&pcs=D35A5A&sc=EBEB58
```

## iframe Messages

Communicate with the embed using the browser's `postMessage` API.

### Messages from the iframe

Listen for these events on `window`:

| Type | Description |
|------|-------------|
| `resize` | The embed has resized. `w` and `h` carry the new dimensions in pixels. |
| `loaded` | The visualisation has loaded and a result was found. `payload` carries the stock IDs. |
| `noResult` | No result was found for the given job ID, or the JSON at `src` held no placed parts. |
| `error` | An error occurred. `message` carries the error text. |
| `partClick` | A part was clicked. `message` carries part data. |

### Messages to the iframe

Send these events to the iframe using `contentWindow.postMessage`:

| Type | Fields | Description |
|------|--------|-------------|
| `navigate` | `stockID` | Navigate to a specific stock item by its ID (e.g. `'1.0'`) |

## Notes

- The embed must be hosted on a page served over **HTTPS**. It will not work on HTTP.
- The iframe height starts at `0`. The `resize` message sets it.
- A result is kept for **24 hours**. Beyond that, render it from
  [your own JSON](#your-own-json).
- `src` replaces `result`: give one or the other, and `src` wins if both are set.

## Full Example

### HTML

```html
<div id="smartcut-vis-message">Loading...</div>

<iframe
  id="smartcut-vis"
  src="https://cutlistevo.com/embed/?result=1733"
  allowtransparency="true"
  frameborder="0"
  height="0"
></iframe>
```

The same iframe, reading JSON you host. Only the query parameter changes:

```html
<iframe
  id="smartcut-vis"
  src="https://cutlistevo.com/embed/?src=https%3A%2F%2Fcdn.example.com%2Fjobs%2F1733.json"
  allowtransparency="true"
  frameborder="0"
  height="0"
></iframe>
```

### JavaScript

```javascript
window.addEventListener('message', (e) => {
  if (!e.data) return
  if (e.data?.origin !== 'smartcut') return

  switch (e.data.type) {
    case 'resize':
      document.getElementById('smartcut-vis').style.height = e.data.h + 'px'
      break
    case 'loaded':
      document.getElementById('smartcut-vis-message').style.display = 'none'
      document.getElementById('smartcut-vis').style.visibility = 'visible'
      break
    case 'noResult':
      document.getElementById('smartcut-vis-message').innerText = 'No result found'
      break
    case 'error':
      document.getElementById('smartcut-vis-message').innerText = e.data.message
      break
    case 'partClick':
      console.log(e.data.message)
      break
  }
}, false)

// Navigate to a specific stock item
document.getElementById('smartcut-vis').contentWindow.postMessage(
  { type: 'navigate', stockID: '1.0' }
)
```

### CSS

```css
#smartcut-vis,
#smartcut-vis-message {
  width: 100%;
  max-width: 1000px;
}

#smartcut-vis {
  background-color: rgba(255, 255, 255, 0.3);
  box-sizing: border-box;
  visibility: hidden;
}
```

## Related

- [API guide](/docs/guide/) covers producing the layout this diagram renders.
- [Hosted store](/docs/ecommerce/) is the ready-made alternative to embedding.
- [WordPress plugin](/docs/wordpress-plugin/) does the same thing without writing code.

---

# WordPress Plugin

URL: https://smartcut.dev/docs/wordpress-plugin

> SmartCut WordPress WooCommerce plugin documentation

The SmartCut WordPress plugin integrates cutting optimization directly into your WooCommerce store, enabling cut-to-size e-commerce functionality.

## Essentials

Before getting started, ensure these foundational requirements are met:

1. **Add your domain** to your SmartCut account (24-hour activation period, or contact support for expedited activation)
2. **Install WooCommerce plugin** on your WordPress site
3. **Use the Storefront theme** (the official WooCommerce theme)
4. **Minimize plugin installations** - keep additional plugins to a minimum
5. **Avoid page builder tools** until compatibility is thoroughly verified
6. **Skip caching plugins** that may alter JavaScript loading order
7. **Enable automatic plugin updates** to stay current with the latest features

:::caution[Important]
Most issues encountered are related to the points above. Following these guidelines will ensure smooth operation.
:::

## Installation

1. Download the latest `smartcut.zip` from [Github](https://github.com/jgmedialtd/smartcut-wp-plugin/releases/latest/)
2. In WordPress admin, navigate to **Plugins** > **Add New** > **Upload Plugin**
3. Upload the `smartcut.zip` file
4. Activate the plugin

### Local Server Testing

For local development, use `localhost` as the hostname rather than custom domains or IP addresses to enable proper domain validation.

## Product Category Setup

Create a dedicated product category to identify cut-to-size items:

1. Create a new product category in WooCommerce
2. Navigate to **SmartCut** > **General settings**
3. Configure the category for cut-to-size products
4. Apply this category to all relevant products

:::tip
Complete this step before other configuration tasks to streamline your setup.
:::

## Product Templates

The SmartCut admin menu offers template generation featuring example products:

1. Navigate to **SmartCut** > **Templates**
2. Select a template that matches your business structure
3. Customize the template to your needs
4. Ensure the category slug aligns with your saved settings

## Global and Product Settings

Settings operate in a hierarchy: **Product settings override Global settings**.

Implement global settings strategically to reduce administrative overhead when updates are needed across your store.

## Pricing Strategies

SmartCut supports multiple pricing approaches:

- **Full sheet pricing** - Price based on complete sheets
- **Part area-based pricing** - Calculate price by part area
- **Cut length pricing** - Price based on linear cutting
- **Full sheet plus cut length** - Combined pricing model
- **Full sheet plus number of parts** - Price by sheet and part count
- **Additional surcharge options** - Custom pricing adjustments

## Product Structure

### Attribute Configuration

WooCommerce product attributes manage variable options. Follow these guidelines:

#### Simple Products with Fixed Stock

- Use **length** and **width** attributes (millimeters or inches)
- Optional **thickness** attribute (required for beam saws)

#### Variable Products with Multiple Thicknesses

- Use **thickness** attribute separated by pipes: `8 | 12 | 16`
- Omit units

#### Variable Products with Multiple Sizes

- Use **size** format: `2440×1220`
- Multiple options: `2440×1220 | 1000×1000`
- Do not combine with length/width attributes

#### Variable Products with Full-Size Purchase Option

- Add "Cut-to-size" as a text option
- Example: `2440×1220 | 1000×1000 | Cut-to-size`

:::danger[Critical]
Do not add units to dimensions or sizes. The plugin will handle unit conversion based on your store settings.
:::

## Edge Banding and Finishes

These "extras" are managed via standard WooCommerce products linked to cut-to-size offerings. They can be hidden from customers by setting them as **Private**.

### Naming Constraints

:::caution
Extras names must only contain numbers, letters, underscores, hyphens & brackets. No other special characters are allowed.
:::

### Pricing Specifications

- **Banding**: Priced by meter or foot
- **Finishes**: Priced by square meter or square foot

### Simple Extra Products

Use simple products when presenting a single list of choices. Each option requires its own product with controlled pricing. Product slugs identify extras in orders, PDFs, and CSV files.

### Variable Extra Products

Introduced in version 3.1, variable extras allow breaking up choices (e.g., separate color and thickness selection):

1. Add attributes to the extra product
2. Generate variations
3. Set prices accordingly

:::caution[Restriction]
When using variable extra products, add only one product slug at a time to avoid errors.
:::

## CSV Import for Parts

When **Settings** > **Cut list configuration** > **Enable CSV import** is enabled, users can import parts via CSV.

1. Download the example template from the support documentation
2. Ensure the template is available on your site

:::danger[Critical Requirement]
Units used in the import must match your store-wide units set in **Settings** > **Cut list configuration**.
:::

CSV columns include:
- Length
- Width
- Quantity
- Rotation
- Name

All columns are optional and can be removed as needed.

## Translation

Translation occurs in two stages:

### 1. Cut List Widget
Manual translation via provided Google Doc

### 2. Store Text
Use WooCommerce-compatible translation plugins:
- **Loco Translate** (officially supported)
- Other compatible WooCommerce translation plugins

## Troubleshooting

### Cut List Interface Not Displaying

Verify the following checklist:

- ✅ SmartCut plugin installed and activated
- ✅ Domain added to SmartCut account with proper www designation
- ✅ Cut-to-size category created and applied to products
- ✅ Product pricing configured (simple products or variations)
- ✅ Product stock status set appropriately
- ✅ Storefront theme in use
- ✅ Minimal plugin interference
- ✅ Caching properly configured
- ✅ Browser cache cleared

### Server Connection Issues

**For local servers:** Use `localhost` as the hostname.

**For live URLs:**
- Confirm domain registration in your SmartCut account
- Allow 24 hours for activation
- Contact support for expedited processing if needed

Common error message: *"We are having trouble connecting to the server"*

This typically indicates:
- Localhost configuration issues, or
- Incomplete domain setup

### Version Downgrade

If you need to revert to a previous version:

1. Access your SmartCut account dashboard
2. Navigate to the plugin downloads section
3. Select and download the desired version of `smartcut.zip`
4. Upload via WordPress **Plugins** menu

## Support

The platform is designed for self-service setup using provided templates as references.

For assistance:
- **Email**: hello@cutrevolution.com
- **API Updates**: [API Changelog](/docs/updates)
- **Custom Development**: Available at standard hourly rates

---

**Current Plugin Version:** 4.3.9
**Platform:** Built for WooCommerce

## See it running

[store.smartcut.dev](https://store.smartcut.dev) is a stock WordPress and WooCommerce install running this plugin. Browse it like a customer before installing anything.

---

# Inventory API

URL: https://smartcut.dev/docs/ecommerce-inventory

> Manage your store's materials and stock over HTTPS: create and update product lines, adjust quantities atomically, and sync from an ERP.

If you run a [hosted SmartCut store](/docs/ecommerce), you can manage its inventory from your own systems: an ERP, a warehouse system, a stock-control spreadsheet, a nightly script. Everything the admin Inventory page does to materials and stock is available over HTTPS, through the **same validated path**, so nothing the API does can put your store into a state the admin couldn't.

This page explains the model and the things worth knowing before you write against it. Once you're writing calls, the **[endpoint reference](/api-docs/ecommerce)** lists every parameter, schema and response, with a console to try them in.

## The model

Inventory has two levels:

- A **material** is a product line, such as "18mm Oak MFC". It carries a `code` that is unique within your store, plus the defaults shared by everything beneath it: price, colour, grain, category, edge banding.
- A **stock** item is one cuttable sheet or length of that material, with its own dimensions and quantity.

One material has many stock items, typically one per thickness, or per sheet size.

```text
Material  OAK-18  "18mm Oak MFC"   cost 42.50
   ├── Stock  2440 × 1220 × 18   q 40
   └── Stock  3050 × 1220 × 18   q 12
```

Stock is always addressed **under its material**, so the relationship comes from the URL and is never something you have to send:

```bash
POST /ecommerce/api/materials/{materialId}/stock
```

## Credentials

You authenticate with your **existing SmartCut API key**, the same one the optimisation API uses.

1. Sign in at [smartcut.dev/account](https://smartcut.dev/account). You need an active **e-commerce subscription**.
2. Copy your **API key** from the account page.
3. Send it as an `Authorization` header. The value is the **raw key**, with no `Bearer ` prefix.

```bash
curl https://api.smartcut.dev/ecommerce/api/materials \
  -H 'Authorization: YOUR_API_KEY'
```

:::caution
Your API key can change and delete live catalogue data. Keep it in an environment variable, never commit it, and don't ship it to a browser.
:::

If your account belongs to more than one store, add `x-smartcut-org: <slug-or-id>` to say which. Without it, ambiguous requests return `409` and list your options rather than guessing.

## Creating a product line

A material needs a `code` and a `name`. Everything else is optional and inherited by its stock.

```bash
curl -X POST https://api.smartcut.dev/ecommerce/api/materials \
  -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{ "code": "OAK-18", "name": "18mm Oak MFC", "t": [18], "cost": 42.50 }'
```

Then add stock beneath it. Set `ecommerce: true` for anything you sell. Those rows are validated more strictly and require a positive `cost`.

```bash
curl -X POST https://api.smartcut.dev/ecommerce/api/materials/{id}/stock \
  -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{ "l": 2440, "w": 1220, "t": 18, "q": 40, "cost": 42.50, "ecommerce": true }'
```

Send an array to create a batch: `{ "materials": [ … ] }` or `{ "stock": [ … ] }`. Batches are **all or nothing**: if any row fails, nothing is written and the response tells you which row index was at fault.

## Inheritance

Stock inherits `cost`, `grain`, `category`, `finish`, edge banding and the other shared fields from its material. **Set only what differs.** Reads always return the values actually in effect, so you never have to resolve the hierarchy yourself.

Two rules worth knowing:

- Setting an inherited field on a stock item pins it. That sheet keeps your value, and later edits to the material no longer move it. This is automatic, and there is no flag to manage.
- Setting it back to `null` un-pins it, and the item resumes following its material.

```bash
# this 3050mm sheet costs more than the material default
curl -X PATCH .../stock/{id} -d '{ "cost": 49.99 }'

# changed our minds — follow the material again
curl -X PATCH .../stock/{id} -d '{ "cost": null }'
```

## Changing quantities

Use **adjust**, not `PATCH`, for stock movements:

```bash
curl -X POST https://api.smartcut.dev/ecommerce/api/stock/{id}/adjust \
  -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{ "delta": -5, "reason": "goods out" }'
```

`delta` is relative: negative removes, positive adds. It's a single atomic operation, so two systems adjusting the same item at the same moment can't oversell it. A `PATCH` of `q` reads and writes separately and can lose a concurrent update.

Two behaviours to rely on:

- The row is never deleted at zero. It stays at `0`, so your next sync still finds it.
- Going below zero is refused with `409`, and the response reports how many are actually available rather than silently clamping. If you see this, your stock model and SmartCut's have diverged.

Items marked `unlimitedQuantity` return `200` with `adjusted: false`, because their quantity isn't tracked.

## Syncing from an ERP

Use `PUT /ecommerce/api/materials/by-code/{code}`. It creates the material if it's absent and updates it if it's present, keyed on **your own product code**. The same request can be replayed safely, so a nightly job needs no state and never has to check existence first.

```bash
curl -X PUT https://api.smartcut.dev/ecommerce/api/materials/by-code/OAK-18 \
  -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{ "name": "18mm Oak MFC", "t": [18], "cost": 44.95 }'
```

It responds `201` when it created and `200` when it updated. The `created` flag tells you which. URL-encode codes containing spaces or slashes.

To find stock without tracking SmartCut ids, filter the flat list by material code: `GET /ecommerce/api/stock?code=OAK-18`.

## When something is wrong

Errors carry a machine-readable `code` and name the field. **Unrecognised fields are rejected, not ignored**. A misspelled key fails loudly instead of returning success without changing anything.

```jsonc
{
  "error": "Validation failed",
  "code": "VALIDATION_FAILED",
  "errors": [
    { "field": "quantiy", "code": "UNKNOWN_FIELD",
      "message": "Unknown field \"quantiy\" for stock. Accepted fields: cost, discount, …" }
  ]
}
```

| `code` | Meaning |
|---|---|
| `UNKNOWN_FIELD` | Not a field on this resource. The message lists the accepted set. |
| `READONLY_FIELD` | Real, but managed by SmartCut: `id`, `area`, and a stock item's `material` name. |
| `FORBIDDEN_FIELD` | Internal. Most often `db_materialId`. Create stock under its material instead. |
| `REQUIRED_FIELD` / `INVALID_VALUE` | Missing or out of range. The message names the value. |
| `DUPLICATE_CODE` | Another material already uses this code. In a batch, reported against the row index. |
| `INSUFFICIENT_QUANTITY` | An adjust would go below zero. Carries `available`. |

Branch on `code`. The message text is for people and may be reworded.

A few things live on the material rather than on stock, and the error will say so: product `code`, the thickness **list**, and the form (`sheet` / `linear` / `roll`). A bonded board is one material thickness written `"18,36"`, and creating it produces a stock item for each half.

### Status codes

| Status | When |
|---|---|
| `400` | Validation failed. See the `errors` array above. |
| `401` | Missing or unrecognised API key. |
| `403` | Your account has no e-commerce access, or is blocked. |
| `404` | No such material or stock **in your store**. |
| `409` | An adjust would take quantity below zero. |
| `429` | Rate limited. Wait for `Retry-After` seconds. |

`404` also covers ids that exist in a **different** store. You'll never get a `403` for those, so the response can't be used to work out whether an id exists somewhere else. If you're sure an id is right and still get `404`, check you're using the key for the store that owns it.

### Warnings

A `PATCH` can succeed and still return a `warnings` array. Those are pre-existing problems on fields you **didn't** touch, such as a row that predates a validation rule. Your change was applied. The warnings tell you the record has other issues without blocking you from fixing them one at a time.

## Rate limits

Inventory calls get their own budget, well above general read traffic, so a catalogue sync of a few hundred rows is fine. Exceeding it returns `429` with a `Retry-After` header. Wait that many seconds and continue.

## See also

- [Endpoint reference](/api-docs/ecommerce) documents the same endpoints as this page, one at a time: every parameter, schema and response, with a console to try them in. It also covers the order-workflow endpoints, which this guide doesn't. Read this page to understand the model, then go there for the exact shape of a call.
- [Store config MCP](/docs/ecommerce-mcp) does the same operations from an LLM client, if you'd rather ask than integrate.
- [Hosted store](/docs/ecommerce) covers the storefront, analytics and webhooks.

---

# 3D model analysis

URL: https://smartcut.dev/docs/model-analysis

> Upload a STEP, STL, OBJ, PLY or glTF model to the SmartCut API and get back a parts list ready to submit to /v3/calculate, with checks on shaped parts.

Upload a 3D model. Get back a parts list.

`POST /v3/model/analysis` reads a CAD file, works out which solids in it are panels, measures them, and returns them in exactly the shape [`/v3/calculate`](/api-docs/v3) wants. The `parts` array it gives you **is** that endpoint's `parts` array. No field mapping, no conversion.

```text
POST https://api.smartcut.dev/v3/model/analysis
```

## The request is the file

The body is the model file itself, as raw bytes. Not a multipart form, not base64 inside JSON. There is exactly one file and nothing else to send, so everything else is a query parameter.

```bash
curl -X POST \
  "https://api.smartcut.dev/v3/model/analysis?filename=kitchen.step&units=mm" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @kitchen.step
```

| Parameter | Default | What it does |
|---|---|---|
| `filename` | none | The file's name. Used to work out the format when the bytes carry no magic. |
| `format` | none | Force the format instead of inferring it. Magic bytes still win where the file has them. |
| `units` | `mm` | The unit every number in the response is in. One of `mm`, `cm`, `m`, `in`, `ft`. |
| `sourceUnits` | none | The unit the model was **drawn** in. Overrides whatever the file declares. |
| `dedupe` | `true` | Collapse identical parts into one row with a quantity, which is what a cut list wants. |
| `mirrorDedupe` | `false` | Treat a part and its mirror image as the same part. |
| `bladeWidth` | none | Your saw's kerf, in `units`. Enables the units sanity check below. |

## Formats

The format is decided by the file's **magic bytes**, with the extension as a tiebreak. People rename files, and a `.stl` that is really a zip should fail with something better than a parser crash. OBJ and ASCII STL carry no magic at all, so for those you must send `filename` or `format`. Without one the request is refused rather than guessed at.

| Format | Extensions | Supported | Notes |
|---|---|---|---|
| STEP | `.step`, `.stp` | Yes | **The best input.** Exact B-rep solids, tessellated server-side, and the file declares its own unit, so `sourceUnits` is not needed and cannot be got wrong. |
| STL | `.stl` | Yes | Binary and ASCII. Carries no part names and no materials, so parts are separated by geometry alone. |
| OBJ | `.obj` | Yes | Keeps object names and `usemtl` material names. |
| PLY | `.ply` | Yes | Geometry only. |
| glTF / GLB | `.gltf`, `.glb` | Yes | Embedded-buffer GLB works. External `.bin` or texture files are not fetched, so geometry only. |
| Collada | `.dae` | **No, `415`** | Needs a browser DOM to parse. Convert to STEP or STL. |
| 3MF | `.3mf` | **No, `415`** | Same reason. Convert to STEP or STL. |

A `415` is not a dead end. It names what would have worked:

```json
{
  "error": "The DAE format cannot be read here. Supported formats: obj, stl, ply, gltf, step.",
  "details": {
    "format": "dae",
    "supported": [ "obj", "stl", "ply", "gltf", "step" ],
    "help": "Re-export the model as STEP (best: exact solids and real units) or STL. Collada and 3MF can only be read in the browser."
  },
  "version": "3"
}
```

## Units

Only STEP declares a unit the server can act on. Every mesh format (STL, OBJ, PLY, glTF) carries **nothing**, so if you do not say what the model was drawn in, the numbers are taken to be already in `units`.

Getting this wrong is silent. Every part stays consistent with every other, so a cabinet exported from a tool set to metres and read as millimetres imports as a set of perfectly self-consistent, thousand-times-too-small parts. It is worth being explicit:

```text
?filename=cabinet.obj&sourceUnits=m&units=mm
```

The response always tells you what it did:

```json
"model": {
  "format": "obj",
  "units": "mm",
  "sourceUnits": "m",
  "declaredUnits": null
}
```

Send `bladeWidth` and the server can also catch the mistake for you. A kerf is a fraction of a percent of anything worth cutting, so a blade that is an appreciable slice of the whole model means the model is not small. The unit is wrong. When that happens, `model.suggestedUnits` names the `sourceUnits` that would make sense of it. Without a `bladeWidth` there is nothing to measure against and no suggestion is made.

## The response

```json
{
  "version": "3",
  "model": {
    "format": "step",
    "units": "mm",
    "sourceUnits": "mm",
    "declaredUnits": "mm",
    "stats": {
      "parts": 3, "rectangular": 2, "irregular": 1, "unrecognised": 0,
      "fixtures": 0, "merged": 2, "triangles": 4820,
      "components": 5, "debris": 0,
      "modelDiagonal": 1523.4,
      "modelSize": { "x": 1200, "y": 600, "z": 720 }
    }
  },
  "parts": [
    { "name": "SIDE", "l": 720, "w": 560, "t": 18, "q": 2, "material": "MDF", "role": "rect" },
    { "name": "SHELF", "l": 564, "w": 540, "t": 18, "q": 1, "material": "MDF", "role": "rect",
      "machining": { "holes": [ { "x": 32, "y": 40, "diameter": 8, "face": 0, "type": "regular" } ] } },
    { "name": "CURVED TOP", "l": 600, "w": 300, "t": 18, "q": 1, "material": "OAK", "role": "nesting",
      "outline": [ { "x": 0, "y": 0 }, { "x": 600, "y": 0 } ] }
  ],
  "advice": [
    { "code": "squared-off-waste", "severity": "info", "partIndex": 2, "wastePct": 0.21,
      "message": "Squaring \"CURVED TOP\" off to a rectangle wastes 21.0% of its area. Send its outline to a nesting model to keep it." }
  ],
  "warnings": []
}
```

### Parts

Every field on a part except `role` is a `/v3/calculate` part field. `role` is not, and `/v3/calculate` **ignores fields it does not recognise** rather than rejecting them, so you can post the array back exactly as it arrived. You do not have to strip anything:

```bash
# 1. analyse
curl -sS -X POST \
  "https://api.smartcut.dev/v3/model/analysis?filename=kitchen.step" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @kitchen.step > analysis.json

# 2. cut it. The parts array goes straight across
jq '{
  saw:   { cutType: "guillotine", cutPreference: "l", bladeWidth: 3.2, stockType: "sheet" },
  stock: [ { l: 2440, w: 1220, t: 18, material: "MDF", q: 20 } ],
  parts: .parts
}' analysis.json > calculate.json

curl -X POST https://api.smartcut.dev/v3/calculate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @calculate.json
```

`role` says what each part is **for**, and it is the one thing worth acting on before you cut:

| `role` | Meaning | What to do |
|---|---|---|
| `rect` | A plain rectangle. | Nothing. Cut it. |
| `nesting` | A shaped part. `outline` (and `holes`) carry its real geometry. | Submit it to a nesting model to keep the shape, or let a guillotine model square it off to `l` x `w` and accept the waste. `advice` tells you how much that costs. |
| `fixture` | A fitting such as a handle, a hinge or a knob, never cut from sheet at all. | **Filter these out** before cutting. A `fixture-detected` entry in `advice` names each one. |

### Holes

A hole in a part is either **drilling** or **shape**, and the analysis decides which:

| Where it comes back | What it is | Fields |
|---|---|---|
| `machining.holes` | A round hole, meaning drilling. Same structure `/v3/calculate` takes for machining operations. | `x`, `y` (the centre, from the left and bottom edges), `diameter`, `face`, `type`. `depth` is absent, which means a through hole. |
| `holes` | A ring that is not round, such as a slot or a cut-out. Real geometry the part has to be cut around, in `outline`'s own frame. | An array of polygon rings, same vertex convention as `outline`. |

A hole appears in exactly one of them, never both, so a part is never drilled **and** cut for the same hole. Round holes are also why a drilled shelf still comes back as `role: "rect"`: to a saw it is a plain panel, and the drilling rides along in `machining` rather than turning it into a shaped part.

Which form you want depends on the machine, not on the part, so `?holes=` switches between them:

```bash
# default: round holes come back as drilling operations
curl ... "https://api.smartcut.dev/v3/model/analysis?filename=kitchen.step"

# a router with no drill head: round holes come back as polygon rings to cut
curl ... "https://api.smartcut.dev/v3/model/analysis?filename=kitchen.step&holes=cut"
```

`holes=cut` is the form a **nesting** model reads. It packs polygons, and a part whose geometry it cannot see is packed as its bounding rectangle instead. A part returned this way carries its `outline` as well, so send it to a nesting job rather than a guillotine one. Holes that are not round are shape under either setting, because there is no drilled equivalent of a slot.

Measurements are in the response's `units`, so `diameter` follows the same unit as `l` and `w`, not millimetres.

```bash
# drop the fittings
jq '[ .parts[] | select( .role != "fixture" ) ]' analysis.json
```

### Advice

`advice` is everything the analysis knows that a calculation does not, as data rather than prose. Each entry has a stable `code`, a `severity` of `info`, `warning` or `error`, a human-readable `message`, and, where it is about a specific part, a `partIndex` into `parts`.

| Field | When |
|---|---|
| `partIndex` | The advice is about one part. Absent when it is about the file as a whole. |
| `otherPartIndex` | The advice is about a **pair**, currently only `parts-overlap`. |
| `penetrationFraction` | On `parts-overlap`: how deeply, as a fraction of the smaller part's smallest dimension. |
| `wastePct` | On `squared-off-waste`: the fraction of the bounding rectangle that is waste, 0..1. |
| `confidence` | On `fixture-detected` / `role-uncertain`: how sure the verdict was, 0..1. |

Codes worth handling:

| Code | Severity | Means |
|---|---|---|
| `fixture-detected` | `info` | This is a fitting, not sheet goods. Drop it. |
| `role-uncertain` | `info` | The fitting question was close. Worth a human look. |
| `squared-off-waste` | `info` | Squaring this shaped part off costs `wastePct` of its area. |
| `dimensions-approximate` | `warning` | The dimensions came from a fallback, not from measured flat faces. Check them. |
| `parts-overlap` | `warning` | Two parts share space. Often deliberate (a housing, a rebate, a biscuit), so this is never a blocker. |
| `not-flat-panel` | `warning` | Turned, curved, tapered or multi-body. The bounding box is the best available answer. |
| `open-mesh` / `non-manifold-edge` | `warning` | The mesh is not a closed solid. Dimensions may be unreliable. |
| `model-too-heavy` | `warning` | Very dense. It worked, but a coarser export would be faster. |
| `scanned-mesh-file` | `error` | This is a scan or a conversion, not a CAD model of parts. |

## Limits and cost

| | |
|---|---|
| **Maximum upload** | 32MB. Larger bodies get `413` without being buffered. |
| **Maximum complexity** | 2,000,000 triangles. Above that, `422`. Export with a coarser mesh setting, or decimate. |
| **Time budget** | 30 seconds. A model that does not finish returns `422` with the same advice. |
| **Rate limit** | The same per-minute budget as `/v3/calculate`. |
| **Billing** | The same compute-time meter as a calculation, and it counts against your monthly call allowance. |

A refused request is **not billed** and does not spend a call: an unsupported format, an over-size model, a timeout.

## Errors

Every error is `{ "error": "…", "details": { … }, "version": "3" }`.

| Status | Means |
|---|---|
| `400` | The body is not a file, the format could not be determined, or `units`/`sourceUnits` are not ones we convert. |
| `401` | Missing or unknown API key. |
| `403` | Over the monthly call limit, or the account is on hold. |
| `413` | Body larger than 32MB. |
| `415` | A format this server cannot read. `details.supported` lists the ones that work. |
| `422` | Too many triangles, or the analysis did not finish in its budget. |
| `429` | Rate limited. Wait and retry. |

## Related

- [API reference](/api-docs/v3): the generated schema for this endpoint and every other.
- [Guide](/docs/guide/): getting started with the optimisation API.
- [Result webhooks](/docs/webhooks/): how to receive the calculation you submit next.

---

# Result webhooks

URL: https://smartcut.dev/docs/webhooks

> Receive finished SmartCut results at your own URL instead of polling: registration, payload, signature verification and retry behaviour.

Webhooks are the recommended way to receive calculation results. Instead of polling [`/v3/result/ready`](/api-docs/v3) until a job finishes, SmartCut sends the finished result to a URL you control, as soon as it is ready.

:::note
This page covers the **optimisation API** webhook, which delivers calculation results and is configured per API user. It is **not** the e-commerce store webhook. That one delivers order and inventory events, is configured in your store settings, and is documented in the [Hosted store guide](/docs/ecommerce#webhooks).
:::

## Register a webhook

There are two ways to set one up, and they can be combined.

**Per-request.** Include a `webhook` field in your [`/v3/calculate`](/api-docs/v3) request body:

```json
{
  "saw": { "cutType": "guillotine", "bladeWidth": 3, "stockType": "sheet" },
  "stock": [ { "l": 2400, "w": 1200 } ],
  "parts": [ { "l": 400, "w": 300, "q": 5 } ],
  "webhook": "https://example.com/hooks/smartcut"
}
```

**Account default.** Set a default URL at [smartcut.dev/account](https://smartcut.dev/account). It is used for every job that does not carry a per-request URL.

A per-request `webhook` **wins** for that job. If you set neither, nothing is delivered and you must poll for the result.

## What gets delivered

When the job finishes, SmartCut sends an HTTP `POST` with a `Content-Type: application/json` body. For a successful calculation the body is **identical to the response from `GET /v3/result`**, the same `ResultResponse` schema, with `jobId` set. Use that id to correlate the delivery with the job you got back from `/v3/calculate`.

Every request carries these headers:

| Header | Description |
|--------|-------------|
| `X-SmartCut-Event` | The event name, either `job.completed` or `job.failed` |
| `X-SmartCut-Delivery` | Unique delivery ID. **Stable across retries**, so use it as an idempotency key |
| `X-SmartCut-Attempt` | Which attempt this is, starting at 1 |
| `X-SmartCut-Timestamp` | Unix timestamp (seconds) of this delivery attempt |
| `X-SmartCut-Signature` | HMAC signature. See [Verifying the signature](#verifying-the-signature) |

Respond with any `2xx` status within 10 seconds to acknowledge. Anything else counts as a failure and is retried.

## Events

Read `X-SmartCut-Event` to tell the two apart. The body shape differs.

| Event | Body |
|-------|------|
| `job.completed` | The full `ResultResponse`, exactly as `GET /v3/result` returns it |
| `job.failed` | `{ "statusCode": 422, "message": "<reason the job failed>" }` |

A failed job sends a notification and nothing else. There is no partial result to collect. Branch on the header before using the body:

```js
// `payload` is the parsed body, after verifying the signature against the raw
// bytes — see below.
function handle( event, payload ) {
  if ( event === 'job.failed' ) {
    console.error( `Job failed: ${ payload.message }` )
    return
  }
  console.log( `Job ${ payload.jobId } complete` ) // payload is a ResultResponse
}
```

## Verifying the signature

Every delivery is signed with a secret unique to your account. You can reveal or rotate it on your [account page](https://smartcut.dev/account). Verify the signature before trusting a payload. It is what proves the request came from SmartCut.

The `X-SmartCut-Signature` header looks like:

```text
X-SmartCut-Signature: t=1720000000,v1=5257a869e7b...
```

`v1` is an HMAC-SHA256, in hex, of the string `{timestamp}.{raw request body}`, using your signing secret as the key. Note the timestamp is **inside** the signed payload: that's what lets you reject replayed deliveries.

To verify: take `t` from the header, concatenate it with a `.` and the **raw** request body, HMAC that with your secret, and compare against `v1` using a constant-time comparison. Take the body before any JSON parsing, since re-serialising changes the bytes and breaks the signature. Reject the request if the timestamp is more than a few minutes old.

```js
import crypto from 'crypto'

function verifySmartCutWebhook( header, rawBody, secret, toleranceSeconds = 300 )
{
    const parts = Object.fromEntries( header.split( ',' ).map( p => p.trim().split( '=' ) ) )
    const timestamp = Number( parts.t )
    const provided = parts.v1

    // A malformed header can never be valid — bail before the replay check.
    if ( !Number.isFinite( timestamp ) || !provided ) return false

    // Reject replays: the signature is still valid, but the delivery is stale.
    if ( Math.abs( Math.floor( Date.now() / 1000 ) - timestamp ) > toleranceSeconds ) return false

    const expected = crypto
        .createHmac( 'sha256', secret )
        .update( `${ timestamp }.${ rawBody }`, 'utf8' )
        .digest( 'hex' )

    const a = Buffer.from( expected )
    const b = Buffer.from( provided )

    return a.length === b.length && crypto.timingSafeEqual( a, b )
}
```

Your framework must give you the raw body. In Express, use `express.raw({ type: 'application/json' })` on the webhook route and parse it yourself after verifying. Reaching for `express.json()` instead discards the exact bytes the signature covers:

```js
app.post( '/hooks/smartcut', express.raw( { type: 'application/json' } ), ( req, res ) => {
  const raw = req.body // a Buffer, not an object

  if ( !verifySmartCutWebhook( req.get( 'X-SmartCut-Signature' ), raw, process.env.SMARTCUT_WEBHOOK_SECRET ) ) {
    return res.sendStatus( 400 )
  }

  // Acknowledge first, then do the work — you have 10 seconds.
  res.sendStatus( 200 )
  handle( req.get( 'X-SmartCut-Event' ), JSON.parse( raw ) )
} )
```

## Retries and idempotency

If your endpoint does not return a `2xx`, the delivery is retried with an increasing backoff over roughly a day before being given up on. These responses are treated differently:

| Response | Retried? |
|----------|----------|
| `2xx` | Delivered, so no retry |
| `5xx` | Yes |
| `429` / `408` | Yes, and a `Retry-After` header is honoured |
| Other `4xx` | No. Resending an unchanged request cannot help |
| `3xx` | No. Redirects are **not** followed |
| Timeout (10s) or network error | Yes |

Retries reuse the same `X-SmartCut-Delivery` ID, so **treat that ID as an idempotency key** and ignore a delivery you have already processed. A retry is not a new result. It is the same one arriving again.

## Endpoints that keep failing

The two registration methods behave differently when your endpoint breaks, and the difference matters:

- **Account-default URLs are health-tracked.** After sustained failure with no successful delivery in between, the endpoint is **disabled** and we stop sending to it. You will be emailed before that happens. A disabled endpoint has to be re-enabled by hand on your account page, never automatically. Any successful delivery resets the clock.
- **Per-request URLs are not tracked.** They are signed and retried exactly the same way, but a URL that fails is never disabled and a broken one produces no warning. Nothing accumulates across jobs, because each job carries its own URL.

If you rely on webhooks for anything important, prefer the account default so that a silently broken endpoint is surfaced to you rather than failing quietly on every job.

## Falling back to polling

Webhooks require your service to accept inbound HTTP. If it cannot, poll [`/v3/result/ready`](/api-docs/v3) every 2-3 seconds, stop on `200` (then fetch `/v3/result`) or on `404`/`410`, and back off on `429`.