---
name: unified-ecommerce
description: >-
  Build e-commerce and product-catalog features against many commerce platforms
  (Shopify, WooCommerce, Amazon Seller Central, Walmart, and more) through the
  single Unified.to Commerce API. Use when a coding task involves syncing
  products, variants, collections, inventory levels, locations, or sales
  channels across one or more storefronts.
license: MIT
metadata:
  category: commerce
  api_base: https://api.unified.to
  docs: https://docs.unified.to/commerce/overview
---

# Build an e-commerce product integration with the Unified.to Commerce API

Unified.to normalizes many commerce platforms behind one REST API, so you write
your catalog/inventory integration once and it works across every supported
storefront. This skill teaches an agent how to build against the Unified
Commerce API.

## When to use this skill

Use this skill when the task is to:

- Sync a product catalog (items and their variants)
- Read or update inventory levels across locations
- Manage collections and sales channels
- Support more than one storefront without platform-specific code

## Prerequisites

1. A Unified.to workspace with an **API key** and **Workspace ID**.
2. An activated commerce integration (e.g. Shopify) — use the Sandbox first.
3. A **connection ID** from the embedded Authorization component
   (https://docs.unified.to/concepts/embedded-components).

Keep the API key server-side only.

## Core request pattern

```
https://api.unified.to/commerce/{connection_id}/{object}
```

Authenticate every request:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Regional base URLs: `api.unified.to` (NA), `api-eu.unified.to` (EU),
`api-au.unified.to` (AU).

## Data objects

| Object         | Purpose                                              |
| -------------- | ---------------------------------------------------- |
| `item`         | A product                                            |
| `itemvariant`  | A variant (size/color/SKU) of a product              |
| `collection`   | A grouping of products                               |
| `inventory`    | Inventory levels for an item/variant at a location   |
| `location`     | A store/warehouse location                           |
| `saleschannel` | A sales channel                                      |
| `reservation`  | An inventory reservation                             |
| `review`       | A product review                                     |
| `availability` | Product availability (read-only)                     |

### Supported operations (item shown; others follow the same shape)

| Method   | Path                                | Description          |
| -------- | ----------------------------------- | -------------------- |
| `GET`    | `/commerce/{cid}/item`              | List products        |
| `GET`    | `/commerce/{cid}/item/{id}`         | Get one product      |
| `POST`   | `/commerce/{cid}/item`              | Create a product     |
| `PATCH`  | `/commerce/{cid}/item/{id}`         | Update a product     |
| `DELETE` | `/commerce/{cid}/item/{id}`         | Delete a product     |

The same `GET / POST / PATCH / DELETE` verbs apply to `itemvariant`,
`collection`, `inventory`, `location`, `saleschannel`, `reservation`, and
`review`. `availability` is read-only.

Not every provider supports every object or field — check the **Feature
Support** tab on the integration page in `app.unified.to`. A `501` response
means the operation is unsupported for that provider.

## Pagination, filtering & sorting

- `limit` (max 100) and `offset` (zero-based) for paging.
- `updated_gte=YYYY-MM-DDTHH:MM:SSZ` for incremental sync.
- `sort` (`created_at`, `updated_at`, `name`) + `order` (`asc` / `desc`).

Returned count `< limit` means you are on the last page.

## Example: sync a product catalog (fetch)

```javascript
const BASE = 'https://api.unified.to';
const headers = {
    Authorization: `Bearer ${process.env.UNIFIED_API_KEY}`,
    'Content-Type': 'application/json',
};

// Page through all products, newest first
async function* allItems(connectionId) {
    let offset = 0;
    const limit = 100;
    while (true) {
        const res = await fetch(
            `${BASE}/commerce/${connectionId}/item?limit=${limit}&offset=${offset}`,
            { headers }
        );
        const page = await res.json();
        yield* page;
        if (page.length < limit) break;
        offset += limit;
    }
}

// Create a product
await fetch(`${BASE}/commerce/${connectionId}/item`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        name: 'Classic Tee',
        description: '100% cotton',
        is_active: true,
    }),
});
```

## Example: with the official SDK

```bash
npm install @unified-api/typescript-sdk
```

```typescript
import { UnifiedTo } from '@unified-api/typescript-sdk';

const unified = new UnifiedTo({ security: { jwt: process.env.UNIFIED_API_KEY! } });

const { commerceItems } = await unified.commerce.listCommerceItems({
    connectionId,
    limit: 100,
});
```

SDKs for Python, PHP, Java, Go, C#, and Ruby: https://docs.unified.to/reference/sdks.

## Keeping data in sync (recommended)

For catalog and inventory data, sync into your own database rather than polling:

- Register **webhooks** for `item`, `itemvariant`, and `inventory` events.
  See https://docs.unified.to/reference/webhooks.
- Upsert by `id` on each event.

This makes local queries fast, consistent, and provider-independent.

## Error handling

| Code | Meaning & action                                                 |
| ---- | ---------------------------------------------------------------- |
| 401  | Connection broken — re-authorize the end-user.                   |
| 403  | Missing scopes — fix provider app + Unified.to scopes.           |
| 429  | Provider rate limit — back off; prefer webhook sync.             |
| 501  | Operation unsupported by provider — check Feature Support.       |

## References

- Commerce API overview & data model: https://docs.unified.to/commerce/overview
- REST basics: https://docs.unified.to/reference/rest
- Pagination & filtering: https://docs.unified.to/reference/pagination
- Source guide: https://docs.unified.to/guides/how_to_build_an_e_commerce_product_integration_with_unified