Skip to main content

Update Field Mappings

PUT 
/api/storefront/instances/:id/mappings

Replace this instance's custom field mappings wholesale. Whatever you send becomes the complete custom set; a mapping you leave out is gone, and the default for that target applies again.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Body — every rule:

  • mappings (required, array) — must be present and non-empty. An empty array is rejected, so this endpoint cannot be used to clear every mapping at once.
  • mappings[].listing_field (required, string) — the store-side source. Use a value from available_storefront_fields on Get Field Mappings.
  • mappings[].sku_field (required, string) — the SKU.io target. Use a value from available_sku_fields: a core or dimension field, price.{level name}.value, or attributes.{attribute name}. An id-suffixed target such as product_pricing_tier_3 is not a real target — it would be stored and then ignored at import.
  • mappings[].parsers (optional, nullable, array) — transforms applied to the source value in order. Send [] for none.

A custom mapping overrides the default that targets the same sku_field; targets no default covers are simply added. The response returns the stored set and the recomputed effective set.

Permission: integrations.update.

Authentication: Bearer token (session or PAT).

Request​

Responses​

OK

Response Headers
    Content-Type