---
title: "Create Catalog Mapping"
method: POST
path: "/supplier_provider/{supplier_provider_uid}/catalog_map"
---

# Create Catalog Mapping

`POST /supplier_provider/{supplier_provider_uid}/catalog_map`

## Request

- Base URL: `https://dc-region.zuperpro.com/api`
- URL: `https://dc-region.zuperpro.com/api/supplier_provider/{supplier_provider_uid}/catalog_map`
- Auth: API key in header `x-api-key`

Links Zuper products to a supplier's products: each entry pairs a Zuper product (and option) with a supplier product variant and unit of measure, and creates a vendor catalog row holding the supplier SKU, unit and cost so the product can be ordered from that supplier. Rows for the saved branch in `vendor_uid` are created immediately; the same entries are then applied to every other saved branch of this provider in the background. A row is created only where the branch stocks the item according to the branch stocking data Zuper syncs from the supplier, and its cost is the supplier's price at that branch, so entries the branch does not stock are returned in `skipped_entries` (if the supplier's price request fails for this branch, they are retried in the background). Zuper may reuse a supplier price answer for up to 15 minutes, so a price can be that old. A Zuper product can be linked to only one supplier product per supplier and each Zuper option to one supplier option; if any entry fails a check the whole request is rejected and nothing is saved. Each linked or skipped row is also recorded in the Zuper product's activity. Save the branch first with Create Supplier Branch. Instead of an option UID, an entry can name the Zuper option in `zuper_product_option_name`: Zuper reuses the product option with that name or creates it, and reports the outcome in `data.zuper_option_resolutions`. Admin only: the API key must belong to an admin user; other roles receive 405 Access Denied.

## Path parameters

- `supplier_provider_uid` string, required

## Request body

- object
  - `vendor_uid` string, required: Required. UID of a saved branch (Zuper vendor) of this supplier provider. Its rows are created during the request; other saved branches are filled in the background.
  - `vendor_catalog` object[], required: Required. One entry per Zuper product option to link. A supplier option can appear only once per request, and at most one entry per supplier option may omit both `zuper_product_option_uid` and `zuper_product_option_name`.
    - `zuper_product_uid` string, required: Required. The Zuper product to link.
    - `zuper_product_option_uid` string, nullable: The Zuper product option (`option_uid`) this row stands for. Required when the Zuper product has options, unless you send `zuper_product_option_name` instead; omit or send `null` only for a product without options. The same Zuper option may appear only once per request.
    - `zuper_product_option_name` string, nullable: Name of the Zuper product option this row stands for, used instead of `zuper_product_option_uid`. Zuper reuses the product option with this name (matched ignoring case and extra spaces; disabled options count) or creates it when none exists, labelling a product without options "Option" and using the supplier variant image. Ignored when `zuper_product_option_uid` is sent. Must not be blank or "N/A"; a product can hold at most 50 options.
    - `supplier_product_uid` string, required: Required. The supplier product, from Get Supplier Products. It must be stocked at one or more of your saved branches for this provider. For ABC Supply cut-to-length (dimensional) items, each length is a separate supplier product.
    - `supplier_product_option_uid` string, required: Required. The `option_uid` of one of the supplier product's `supplier_product_variants`.
    - `vendor_sku` string, required: Required. Must equal the `variant_code` of the selected supplier variant (the supplier's item number).
    - `vendor_uom` string, required: Required. Must exactly match one of the supplier product's `uoms[].code` values (for example `BD`); unit aliases are not accepted here. Rows created in the background for your other branches use the first entry's unit for every product, falling back to the supplier's equivalent code (for example `SQFT` becomes `SF` for SRS and ABC Supply, `SQF` for QXO), then the Zuper product's unit, then the supplier's smallest unit (SRS, ABC Supply) or first listed unit (QXO).
    - `vendor_cost` number, required: Required. 0 or more; a numeric string such as `"38.50"` is also accepted. The saved cost always comes from the supplier's price at each branch (0 when the supplier returns no numeric price), so this value is validated but not stored.
    - `remarks` string: Optional note stored on each created row (up to 2,000 characters).

## Response `200`

200

- object
  - `type` 'success'
  - `title` string
  - `message` string
  - `count` integer: Catalog rows created for the branch in `vendor_uid`. Can be 0 when every entry was skipped.
  - `catalog_uids` string[]: `vendor_catalog_uid` of each row created for the branch in `vendor_uid`; use these with Update Catalog Mapping.
  - `skipped_count` integer
  - `skipped_entries` object[]: Entries not created for the branch in `vendor_uid` because the branch does not stock the item according to Zuper's synced stock data, or the supplier returned no price for it there.
    - `zuper_product_uid` string
    - `supplier_product_uid` string
    - `supplier_product_option_uid` string
    - `vendor_uid` string
    - `vendor_sku` string
    - `vendor_uom` string
    - `message` string: Why the entry was skipped: "Not stocked at this branch", or the supplier's own message for the item. May be empty.
  - `data` object: How each row that sent `zuper_product_option_name` was resolved; empty when no row sent one.
    - `zuper_option_resolutions` object[]
      - `zuper_product_uid` string
      - `supplier_product_option_uid` string
      - `option_uid` string: The Zuper option the row now uses.
      - `option_value` string
      - `is_available` boolean
      - `created` boolean: `true` when Zuper created the option for this request; `false` when an existing option matched the name.

## Other responses

- `400`: 400
- `403`: 403
- `404`: 404
- `405`: 405
- `409`: 409

## Changes

- **2026-11-03** `3c21bc232e16`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zuper/apis/zuper-pro-api/changes/supplier_provider/:supplier_provider_uid/catalog_map/post.md)

---

[API](https://skmtc.dev/zuper/apis/zuper-pro-api.md) - [All operations](https://skmtc.dev/zuper/apis/zuper-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zuper/apis/zuper-pro-api/revisions/3c21bc232e16?raw)