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

# Custom Commerce Integration

> Connect any e-commerce platform to Sequenzy with the Commerce API - products, orders, revenue, and abandoned checkouts

Sequenzy has native integrations for Shopify and WooCommerce. The **Commerce API** gives every other platform the same experience: custom checkouts, headless storefronts, CheckoutChamp, Sticky.io, marketplaces, or your own backend.

You push normalized products and orders over HTTPS, and Sequenzy treats them exactly like a native integration:

| Capability              | How it works                                                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Product catalog**     | Products appear in your dashboard and power product blocks in emails                                                    |
| **Order events**        | `ecommerce.order_placed`, `order_cancelled`, `order_fulfilled`, `order_refunded` trigger automations and build segments |
| **Revenue attributes**  | `ltv`, `totalSpent`, `ordersCount`, and `aov` are maintained on every customer for segmentation (e.g. "LTV over \$500") |
| **Customer profiles**   | Names, external IDs, and custom attributes sync to the subscriber profile                                               |
| **Abandoned checkouts** | `ecommerce.checkout_started` powers abandoned checkout sequences                                                        |
| **Replenishment**       | Orders schedule replenishment reminders for products with replenishment enabled                                         |
| **Back in stock**       | Stock transitions on product upserts notify waiting subscribers                                                         |

## How it fits together

```
Your platform                      Sequenzy
─────────────                      ────────
Catalog sync       ──────────▶     PUT products into the catalog
Order placed       ──────────▶     POST /api/v1/orders        ──▶  events, LTV, automations
Checkout started   ──────────▶     POST /api/v1/checkouts     ──▶  abandoned checkout flows
Notify-me clicked  ──────────▶     POST /api/v1/back-in-stock ──▶  back-in-stock alerts
```

All endpoints use your standard [API key](/authentication). There is nothing to install on Sequenzy's side.

## Step 1: Push your product catalog

Sync your products once, then keep them updated whenever they change (a daily sync is fine for most stores). Products are upserted by your `productId`, so repeated pushes are safe.

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "productId": "SKU-PROTEIN-1KG",
        "title": "Protein Powder",
        "imageUrl": "https://cdn.example.com/protein.jpg",
        "url": "https://store.example.com/products/protein",
        "priceCents": 8850,
        "currency": "USD",
        "inStock": true
      }
    ]
  }'
```

See the [upsert products reference](/api-reference/products/upsert) for variants, inventory quantities, and stock handling.

You can also manage the catalog without writing code: `sequenzy products upsert` / `sequenzy products delete` in the [CLI](/concepts/cli), or the `upsert_products` / `delete_product` [MCP tools](/concepts/mcp). Both support attaching a deliverable file for [digital product delivery](/concepts/digital-products).

## Step 2: Push orders

Call the [orders endpoint](/api-reference/orders/create) whenever an order is placed (and optionally when it is cancelled, fulfilled, or refunded). This single call updates the customer profile, revenue attributes, triggers events, and schedules replenishment.

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-1001",
    "totalCents": 8850,
    "currency": "USD",
    "customer": {
      "email": "buyer@example.com",
      "firstName": "Jane",
      "attributes": { "acquisitionChannel": "tiktok" }
    },
    "items": [
      {
        "productId": "SKU-PROTEIN-1KG",
        "title": "Protein Powder",
        "quantity": 2,
        "priceCents": 4425
      }
    ]
  }'
```

Pushing the same `orderId` twice never double counts revenue, so retries are safe.

<Note>
  If your platform tracks lifetime customer totals, pass them in
  `customerTotals` (`ordersCount`, `totalSpentCents`). Sequenzy then uses your
  platform as the source of truth instead of adding orders up itself - useful
  when backfilling history.
</Note>

## Step 3 (optional): Track started checkouts

Send [checkout started](/api-reference/orders/checkout-started) events to power abandoned checkout sequences. Create a sequence triggered by `ecommerce.checkout_started` with a delay, and add a stop condition on `ecommerce.order_placed`.

## Step 4 (optional): Back-in-stock alerts

When a customer asks to be notified about a sold-out product, call the [back-in-stock endpoint](/api-reference/products/back-in-stock). When a later product upsert marks the product in stock again, waiting subscribers get the `ecommerce.back_in_stock` event.

## What you get in the dashboard

* Customers appear as subscribers with `ltv`, `totalSpent`, `ordersCount`, and `aov` attributes you can segment on
* Order history shows up in each subscriber's activity feed
* Products are available in the email editor's product blocks
* Automations can trigger on any `ecommerce.*` event, with order data available as `{{event.*}}` merge tags

## Example: CheckoutChamp

CheckoutChamp (Konnektive) can notify your backend on order events via postbacks. Point a postback at a small relay that maps the payload onto the Commerce API:

```typescript theme={null}
// POST /checkoutchamp-relay - receives a CheckoutChamp postback
export async function handlePostback(postback: CheckoutChampOrder) {
  await fetch("https://api.sequenzy.com/api/v1/orders", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SEQUENZY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      orderId: postback.orderId,
      totalCents: Math.round(parseFloat(postback.totalAmount) * 100),
      currency: postback.currencySymbol ?? "USD",
      orderedAt: postback.dateCreated,
      customer: {
        email: postback.emailAddress,
        firstName: postback.firstName,
        lastName: postback.lastName,
        attributes: { campaignId: postback.campaignId },
      },
      items: (postback.items ?? []).map((item) => ({
        productId: String(item.productId),
        title: item.name,
        quantity: item.qty,
        priceCents: Math.round(parseFloat(item.price) * 100),
      })),
    }),
  });
}
```

The same pattern works for any platform that can call a webhook or run a small sync script.

## Event reference

| Event                               | Triggered by                                                   |
| ----------------------------------- | -------------------------------------------------------------- |
| `ecommerce.order_placed`            | `POST /orders` with `status: "placed"` (default)               |
| `ecommerce.order_cancelled`         | `POST /orders` with `status: "cancelled"`                      |
| `ecommerce.order_fulfilled`         | `POST /orders` with `status: "fulfilled"`                      |
| `ecommerce.order_refunded`          | `POST /orders` with `status: "refunded"`                       |
| `ecommerce.checkout_started`        | `POST /checkouts`                                              |
| `ecommerce.back_in_stock_requested` | `POST /back-in-stock`                                          |
| `ecommerce.back_in_stock`           | Product upsert marking a product back in stock                 |
| `ecommerce.replenishment_due`       | Scheduled after orders for products with replenishment enabled |

## Limits

* Up to 100 products per upsert request
* Order processing is asynchronous (typically under a few seconds)
* Products pushed via the API are owned by the `api` provider: they don't conflict with Shopify or WooCommerce synced products