Initial sync

The initial sync sends your products and your historical orders in one go, so CrossUp starts out knowing what you sell and what already sells together. You do it once, with one snapshot per entity: open it, send pages, close it.

What you sync

The minimum: products and stock

Products (item) and their availability (availability). With that, CrossUp already recommends in all five moments.

To recommend better

Categories and your last year of orders, both optional. From the orders, CrossUp learns what sells with what from day one.

You need the connection_id and the cct_… key from the three steps. The examples use cn_4Kq9Xz and cct_your_key: swap in your own.

The three steps

Open the run

One run per entity type. The response carries its run_id (snp_…).

Send the pages

Up to 500 entities per page, all with upsert.

Close it

On close, whatever of that type didn’t come is removed. On the initial sync there’s nothing to remove.

# 1 · Open the product run
curl -X POST https://salespilot.crossup.ai/internal/v1/connections/cn_4Kq9Xz/snapshots \
  -H "Authorization: Bearer cct_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "entity": "item" }'
# → 201 { "run_id": "snp_7Tn2Wd" }

# 2 · Send a page of products (up to 500)
curl -X POST https://salespilot.crossup.ai/internal/v1/connections/cn_4Kq9Xz/snapshots/snp_7Tn2Wd/pages \
  -H "Authorization: Bearer cct_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      { "entity": "item", "external_id": "1001", "operation": "upsert",
        "document": { "title": { "en": "Black T-shirt" }, "published": true } },
      { "entity": "item", "external_id": "1002", "operation": "upsert",
        "document": { "title": { "en": "Blue cap" }, "published": true } }
    ]
  }'
# → 200 { "results": [ { "index": 0, "status": "accepted" }, { "index": 1, "status": "accepted" } ] }

# 3 · Close the run
curl -X POST https://salespilot.crossup.ai/internal/v1/connections/cn_4Kq9Xz/snapshots/snp_7Tn2Wd/close \
  -H "Authorization: Bearer cct_your_key"
# → 200 { "received": 2, "deleted": 0, "quarantined": 0 }

# The same 1 · 2 · 3 for every entity, in this order:
# taxonomy_node, item, variant, availability and, last, order.

const BASE = "https://salespilot.crossup.ai";
const CONNECTION_ID = "cn_4Kq9Xz"; // your connection
const runs = `${BASE}/internal/v1/connections/${CONNECTION_ID}/snapshots`;
const headers = {
  Authorization: `Bearer ${process.env.CCT_KEY}`, // secret: only on your server
  "Content-Type": "application/json",
};
const post = (url: string, body?: unknown) =>
  fetch(url, { method: "POST", headers, body: body === undefined ? undefined : JSON.stringify(body) });

// Catalog first; historical orders last
for (const entity of ["taxonomy_node", "item", "variant", "availability", "order"]) {
  const { run_id } = await (await post(runs, { entity })).json();
  for (const page of chunk(data[entity], 500)) { // data: what you exported; chunk: splits by 500
    const { results } = await (await post(`${runs}/${run_id}/pages`, { observations: page })).json();
    review(results);                             // one per position: see below
  }
  await post(`${runs}/${run_id}/close`);
}

If the load breaks halfway, don’t close the run: it would remove what you haven’t sent yet. An unclosed run expires on its own after 24 hours, deleting nothing.

Read the response

Every page returns one result per position, in the same order you sent the entities.

{
  "results": [
    { "index": 0, "status": "accepted", "observation_id": "obs_…" },
    { "index": 1, "status": "unchanged" },
    { "index": 2, "status": "stale" },
    { "index": 3, "status": "quarantined", "reason": "document.quantity: required" }
  ]
}

`status`	What happened	What you do
`accepted`	It was written; it carries its `observation_id`	Nothing
`unchanged`	It’s identical to the last one applied	Nothing: it was a resend
`stale`	Its revision was already superseded	Nothing: a newer one is applied
`quarantined`	It didn’t validate; `reason` names the field	Fix it and resend just that one

A quarantined entity doesn’t hold up the rest: the rest of the batch goes in. What a revision is, and why resending is safe, is in Daily updates.

Catalog first, history last

One run per entity, in this order: categories (taxonomy_node), products (item), variants (variant), availability (availability) and, last, your historical orders (order). If a product names a category that hasn’t arrived yet, it doesn’t fail: it resolves when the category arrives. There’s a single open run per connection and entity. With two, closing the first would remove what the second brought.

What you’ll see

The close returns received, deleted and quarantined. On a clean initial sync, deleted and quarantined are zero. After that, your store can read a product by your own id with GET /v1/catalog/items/by-external/{external_id} and its storefront key.

If you don’t see it

What happens	What to do
`409` with `snapshot_open` on open	There’s already an open run for that entity. Close it if it’s complete; if not, wait for it to expire
`404` on a page or on close	The run doesn’t exist or belongs to another connection. Check the `run_id`
`409` with `snapshot_closed` or `snapshot_expired`	The run was already closed or expired after 24 hours. Open a new one
`413`	The page carries more than 500 entities and was rejected whole. Split it
`quarantined` over a price	`amount` goes as decimal text (`"12.90"`), never as a number
`quarantined` on an availability	With `stock_mode: "tracked"` send `quantity`; with the other two, don’t

Daily updates

Every change after the initial sync.

The canonical model

The fields of each entity.

Connectors

Protocol reference

Initial sync

What you sync

The minimum: products and stock

To recommend better

The three steps

Read the response

Catalog first, history last

What you’ll see

If you don’t see it

Daily updates

The canonical model

​What you sync

The minimum: products and stock

To recommend better

​The three steps

​Read the response

​Catalog first, history last

​What you’ll see

​If you don’t see it

Daily updates

The canonical model

What you sync

The three steps

Read the response

Catalog first, history last

What you’ll see

If you don’t see it