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. You need the connection_id and the cct_… key from the three steps. $BASE is the URL of the CrossUp ingestion API.

What you sync

Your catalog

Categories, products, variants and stock. It’s what CrossUp can recommend.

Your historical orders

Your last year of sales. From them CrossUp learns what sells with what from day one.

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.

RUNS="$BASE/internal/v1/connections/$CONNECTION_ID/snapshots"

# 1 · Open the product run → 201 { "run_id": "snp_…" }
curl -X POST "$RUNS" -H "Authorization: Bearer $CCT_KEY" \
  -H "Content-Type: application/json" -d '{ "entity": "item" }'

# 2 · Send a page → 200 { "results": [ … ] }
curl -X POST "$RUNS/$RUN_ID/pages" -H "Authorization: Bearer $CCT_KEY" \
  -H "Content-Type: application/json" -d '{
  "observations": [
    { "entity": "item", "external_id": "1001", "operation": "upsert",
      "document": { "title": { "en": "Black T-shirt" }, "published": true } }
  ]
}'

# 3 · Close → 200 { "received": …, "deleted": 0, "quarantined": 0 }
curl -X POST "$RUNS/$RUN_ID/close" -H "Authorization: Bearer $CCT_KEY"
# Same for every entity; historical orders go last: { "entity": "order" }

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 Staying up to date.

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 expired, was already closed or belongs to another connection. 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

Staying up to date

Every change after the initial sync.

The canonical model

The fields of each entity.

Connectors

Protocol reference

Initial sync

What you sync

Your catalog

Your historical orders

The three steps

Read the response

Catalog first, history last

What you’ll see

If you don’t see it

Staying up to date

The canonical model

​What you sync

Your catalog

Your historical orders

​The three steps

​Read the response

​Catalog first, history last

​What you’ll see

​If you don’t see it

Staying up to date

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