The canonical model

Whether it comes from VTEX, a headless store or an ERP, your catalog reaches CrossUp as five entities. Everything is optional except what identifies, and a field your system doesn’t have is left out: not empty, not zero.

The five entities

`entity`	What it is
`taxonomy_node`	A category. `parent_id` is the parent’s `external_id`; a root leaves it out
`item`	A product: title, description, media, brand, tags, categories
`variant`	A variant: SKU, attributes, prices. `item_id` is its product’s `external_id`
`availability`	The stock of a variant
`order`	An order with lines, payments, shipments and statuses

All of them are identified by their external_id, the id they have in your system. item, variant and availability end up in the same product, and can be sent separately. Availability carries its variant’s external_id, with no suffixes. A variant has a single availability: if you send two warehouses for the same one, the second overwrites the first.

The fields

item

Field	Type	Note
`title`, `description`, `handles`	text per language	`{ "en": "…", "es": "…" }`; a language you don’t have is left out
`urls`	object per language	The product’s public URL
`media[]`	`{ url, alt }`	`alt` per language
`published`	boolean	Whether it’s visible in the store
`brand`	string
`tags[]`	string
`free_shipping`	boolean
`taxonomy_ids[]`	string	The `external_id` of its categories

variant

Field	Type	Note
`item_id`	string	Its product’s `external_id`
`sku`	string
`title`	text per language
`attributes[]`	`{ name, value }`	Both per language: size, color
`price`, `promotional_price`, `cost`	money	`{ "amount": "12.90", "currency": "USD" }`
`published`	boolean
`media[]`	`{ url, alt }`
`shipping`	dimensions	Weight and measurements, as decimal text

availability

Field	Type	Note
`variant_id` (required)	string	The variant’s `external_id`. It’s also the observation’s `external_id`
`stock_mode` (required)	`unlimited` · `tracked` · `unknown`	“Always sells”, “has this quantity”, “doesn’t say”. Treating `unknown` as zero switches off products that are on sale
`quantity`	decimal as string	Only with `tracked`, and then it’s required
`sellability` (required)	`sellable` · `unsellable` · `unknown`	Whether it can be bought, according to your system
`location_metadata` (required)	`resolved` · `unresolved`	With `location_id`, send `resolved`
`location_id`, `external_location_id`	string	Informational: which warehouse the number comes from. Not part of the identity

taxonomy_node

Field	Type	Note
`name`, `description`, `handles`	text per language
`parent_id`	string	The parent’s `external_id`; a root leaves it out
`visible`	boolean

order

Field	Type	Note
`number`, `origin`, `language`, `currency`	string
`lines[]`	lines	Each with `line_id`, `name`, `quantity`, `unit_price` and `subtotal`; `variant_external_id` so the sale is measured
`subtotal`, `total`	money
`discounts[]`, `payments[]`, `fulfillments[]`
`statuses`	statuses	If present, it carries all six: payment, shipping and order, normalized and as your system sends them
`contact`, `shopper`, `billing`, `shipping`	shopper data	Optional. Never written to any log
`created_at`, `updated_at`	RFC 3339
`external_references`	object	Other ids from your system

// No price, no field; never send a zero.
const variant = {
  item_id: "1001",                      // the parent product, with your id
  sku: "TSH-BLK-M",
  title: { en: "Black T-shirt M" },     // per language
  ...(price ? { price: { amount: price, currency: "USD" } } : {}), // text, never a number
};

variant := map[string]any{
    "item_id": "1001",
    "sku":     "TSH-BLK-M",
    "title":   map[string]string{"en": "Black T-shirt M"},
}
if price, ok := priceOf(v); ok {
    variant["price"] = map[string]string{"amount": price, "currency": "USD"} // the amount is text
}

Three types that aren’t what they seem

Money is a string. amount is a decimal as text: a binary float shifts the price and shows up as a missing cent at checkout.
Text is per language. A language you don’t have is left out: don’t copy English into Spanish.
Stock has three states. unlimited, tracked and unknown, and unknown isn’t zero.

Orders

There’s no customer entity: the shopper’s data travels inside the order, and all of it is optional. Whatever you send there, don’t write it to any log. For the sale to be measured, the order has to match the recommendation:

The order’s external_id is the same cart_id your store sends when it requests recommendations.
Every line carries variant_external_id. A line counts as sold if its variant is in the order.

When the order changes (the payment, the total), send it again: the match is redone and comes out the same, without duplicates.

How it reaches your store

CrossUp keeps your external_id values and assigns its own ids (itm_…, var_…). Your store can request a product by your id with GET /v1/catalog/items/by-external/{external_id}.

What you’ll see

Every accepted entity shows up in the catalog with the fields you sent, and no others. A quarantined names the exact field that didn’t validate.

If you don’t see it

What happens	What to do
`quarantined` on a variant	Almost always `price.amount` as a number
`quarantined` on an availability	`stock_mode` or `sellability` is missing, there’s `quantity` without `tracked`, or its `external_id` isn’t the variant’s
Products without a price in recommendations (`missing_price`)	The variant arrived without `price`. That’s correct if your system doesn’t have it, but without a price CrossUp doesn’t decide
Sales that aren’t measured	The order has no `variant_external_id` on its lines, or its `external_id` isn’t the store’s `cart_id`

Connector SDK and protocol

The contract for these entities, in OpenAPI.

What CrossUp decides

What goes in, what comes out and what stays on your side.

Connectors

Protocol reference

The canonical model

The five entities

The fields

Three types that aren’t what they seem

Orders

How it reaches your store

What you’ll see

If you don’t see it

Connector SDK and protocol

What CrossUp decides

​The five entities

​The fields

​Three types that aren’t what they seem

​Orders

​How it reaches your store

​What you’ll see

​If you don’t see it

Connector SDK and protocol

What CrossUp decides

The five entities

The fields

Three types that aren’t what they seem

Orders

How it reaches your store

What you’ll see

If you don’t see it