Mappings

Every vendor names its columns its own way: Item #, Vendor SKU, W (in), Dealer Cost. A mapping (map_…) says which canonical field each column fills and how its values are read.

• A mapping belongs to one source and one set of headers. A file whose headers change gets a new mapping; a source keeps one per header set it has seen.
• For a new header set FurniOps proposes a mapping, and the run stops as needs_mapping until a person confirms it. That happens once: every later file with the same headers imports without asking.
• Shopify feeds and Coaster use FurniOps' built-in mapping and never wait for one.

How FurniOps proposesCopy Anchor Link

Each column is placed from the most specific evidence there is. The column's tier says which:

Units and currency are read from the header (W (in), Price (EUR)), and the decimal style from the column's own values. Columns FurniOps could not place are listed in unmapped with the reason, and are not imported unless you map them. With AI agents in your plan, the column repair agent can propose fields for them.

Review and confirmCopy Anchor Link

GET /v1/sources/{id}/mappings lists the source's mappings, newest first; a waiting run waits for the one whose status is proposed. Each shows the headers in file order, the first 5 rows as samples, the mapped columns and the unmapped ones.

POST /v1/mappings/{id}/confirm confirms it. Send no body to confirm the proposal as it is, or send the final columns: every column you want imported, since columns left out are not.

// A run stopped as needs_mapping waits for the source's proposed mapping.
const mappings = await furniops.sources.listMappings("src_034XqBaL2mRLTZPXyRbaUc");
const proposed = mappings.data.find((m) => m.status === "proposed");
if (proposed !== undefined) {
  console.log(proposed.columns, proposed.unmapped);
  // Confirm it as proposed, or send the final columns: those left out are not imported.
  const confirmed = await furniops.mappings.confirm(proposed.id, {
    columns: [
      ...proposed.columns.map(({ column, prefix, field, settings }) => ({
        column,
        field,
        settings,
        ...(prefix === undefined ? {} : { prefix }),
      })),
      { column: "Seat Ht (in)", field: "seat_height", settings: { unit: "in" } },
    ],
  });
  console.log(confirmed.run?.id); // the waiting file resumes
}

Confirming applies the mapping at once: the file waiting in needs_mapping resumes, or, for a mapping confirmed again with changes, the source's current snapshot is replayed. The answer holds the mapping and that run.

It answers 422 when a column is not one of the headers, a column is mapped twice, a field that takes one column is given two, or a setting does not fit its field; and 409 while the source has a run under way or is paused or disabled. Then nothing is confirmed.

A columnCopy Anchor Link

{
  "column": "Seat Ht (in)",
  "field": "seat_height",
  "settings": { "unit": "in" },
  "tier": "person"
}

SettingsCopy Anchor Link

FieldsCopy Anchor Link

Every field a column can fill, with the level it belongs to and the kind of value it holds. A repeatable field takes several columns: each adds to the list, or names its own axis.

A variant's shipping boxes go in cartons: several boxes in one cell, each with its size, weight and count. Cartons describes how to write them.

When a cell cannot be readCopy Anchor Link

A cell FurniOps cannot use does not stop the run: the rest of its row is imported, and the run records the cell as a problem, with its line, column, field and why.