> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraldraft.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce

> Products, variants, categories, orders, Stripe Connect onboarding, Stripe Checkout sessions, and drop-in storefront widgets.

The Commerce pillar is a Shopify-alternative for AI-built sites. Stripe
Connect is wired in from day one, so payouts go straight to the project
owner — never through Neural Draft. Cart lives in the buyer's browser; we
take a cart payload and create a Stripe Checkout Session on the connected
account.

## What this gives you

* **Products** with variants, categories, inventory tracking, image galleries,
  multi-language translations.
* **Stripe Connect** — Express onboarding flow, status checks, charges /
  payouts gating.
* **Checkout sessions** — pass a cart, get a Stripe-hosted checkout URL.
  Direct charges on the connected account.
* **Orders** with full state machine (`pending → paid → processing → shipped →
  delivered`), refunds, partial refunds.
* **Storefront widgets** — product card, buy button, cart drawer, all CDN-cached.
* **Manual orders** — for offline / cash sales that bypass payment.

## Quick example

A typical e-commerce flow: list products publicly, accept a cart, create a
Stripe Checkout Session, redirect the customer.

<CodeGroup>
  ```bash cURL theme={null}
  # 1. Public product listing (no auth)
  curl "https://api.neuraldraft.io/v1/public/products?project_id=$PROJECT_ID"

  # 2. Create a checkout session
  curl -X POST https://api.neuraldraft.io/v1/checkout-sessions \
    -H "Content-Type: application/json" \
    -d '{
      "items": [{ "product_id": 42, "variant_id": 88, "quantity": 1 }],
      "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
    }'

  # => { "order_id": 902, "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_..." }
  ```

  ```ts SDK theme={null}
  import { NeuralDraftClient } from "@neuraldraft/sdk";

  const nd = new NeuralDraftClient({ apiKey: process.env.NEURALDRAFT_API_KEY! });

  // List + read products through the SDK
  const { data: products } = await nd.products.list({
    status: "active",
    page_size: 50,
  });
  const hoodie = await nd.products.get("nd-hoodie");

  // Create / update / delete (admin-side)
  const created = await nd.products.create({
    name: "Neural Draft hoodie",
    slug: "nd-hoodie",
    price: 4500, // minor units (cents)
    currency: "gbp",
    type: "physical",
    status: "active",
    track_inventory: true,
    stock_quantity: 200,
    images: ["https://cdn.example.com/hoodie.jpg"],
  });

  await nd.products.update(created.id, { stock_quantity: 195 });

  // Checkout sessions are not yet covered by the v0.3.0 SDK — call the REST
  // endpoint directly until they ship in a future release.
  ```
</CodeGroup>

## Common workflows

### 1. Onboard Stripe Connect for the project

Required for any paid product or paid booking. The project owner clicks a
button, lands on Stripe-hosted onboarding, and returns when complete.

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/connect/onboarding \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://example.com/admin/connected",
    "refresh_url": "https://example.com/admin/connect"
  }'
```

```json theme={null}
{
  "url": "https://connect.stripe.com/express/onboarding/...",
  "existing_account": false
}
```

Surface the URL to the user. Once they finish, the
`connect.account_updated` webhook fires and `GET /v1/connect/status` reports
`charges_enabled: true`.

Cost: 250 credits per Connect account, per month — billed at month-end.

### 2. Create a product

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/products \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neural Draft hoodie",
    "slug": "nd-hoodie",
    "description": "A purple hoodie. Heavy gauge, soft inside.",
    "price": 4500,
    "currency": "gbp",
    "type": "physical",
    "status": "active",
    "track_inventory": true,
    "stock_quantity": 200,
    "images": ["https://cdn.example.com/hoodie.jpg"]
  }'
```

`price` is integer cents. Currency follows the project's Stripe Connect
currency.

### 3. Add variants

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/products/42/variants \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medium / Purple",
    "sku": "ND-HOODIE-M-PURPLE",
    "options": { "size": "M", "color": "Purple" },
    "stock_quantity": 50,
    "is_active": true
  }'
```

### 4. Drop a buy-button widget into a page

```html theme={null}
<div data-nd-widget="buy-button" data-product-id="42" data-variant-id="88"></div>
<script src="https://widgets.neuraldraft.io/v1/buy-button.js" defer></script>
```

The widget reads your brand colors, opens Stripe Checkout, redirects on
success. Works on any HTML page, any framework.

### 5. Listen for paid orders

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/webhook-endpoints \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/neural-draft",
    "events": ["order.created", "order.paid", "order.refunded", "order.shipped"]
  }'
```

When a customer completes Stripe Checkout, we receive Stripe's webhook,
update the `Order` to `paid`, decrement stock, and fire `order.paid` to your
endpoint. Use it to send a fulfilment email, kick off a warehouse pick, or
tag the customer in your CRM.

### 6. Refund an order

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/orders/902/refund \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":1500}'
```

`amount` (cents) is optional. Omit for a full refund. Partial refunds
update `payment_status` to `partially_refunded`.

### 7. Manual / cash orders

Useful for in-person and over-the-phone sales that bypass Stripe Checkout.

```bash theme={null}
curl -X POST https://api.neuraldraft.io/v1/orders/manual \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "product_id": 42, "quantity": 2 }],
    "customer": { "name": "Walk-in", "email": "" },
    "payment_method": "manual"
  }'
```

The order is created with `payment_status: unpaid`. Flip it to `paid` (via
`PATCH /v1/orders/{id}/status`) once cash is in hand.

## Reference

| Endpoint                          | Tag                                     |
| --------------------------------- | --------------------------------------- |
| `GET /v1/products`                | [Commerce](/api-reference#tag/Commerce) |
| `POST /v1/products`               | [Commerce](/api-reference#tag/Commerce) |
| `GET /v1/products/{id}`           | [Commerce](/api-reference#tag/Commerce) |
| `PATCH /v1/products/{id}`         | [Commerce](/api-reference#tag/Commerce) |
| `POST /v1/products/{id}/variants` | [Commerce](/api-reference#tag/Commerce) |
| `GET /v1/product-categories`      | [Commerce](/api-reference#tag/Commerce) |
| `GET /v1/orders`                  | [Commerce](/api-reference#tag/Commerce) |
| `PATCH /v1/orders/{id}/status`    | [Commerce](/api-reference#tag/Commerce) |
| `POST /v1/orders/{id}/refund`     | [Commerce](/api-reference#tag/Commerce) |
| `POST /v1/checkout-sessions`      | [Commerce](/api-reference#tag/Commerce) |
| `POST /v1/orders/manual`          | [Commerce](/api-reference#tag/Commerce) |
| `GET /v1/connect/status`          | [Commerce](/api-reference#tag/Commerce) |
| `POST /v1/connect/onboarding`     | [Commerce](/api-reference#tag/Commerce) |
| `GET /v1/public/products`         | [Commerce](/api-reference#tag/Commerce) |