Skip to main content

Update Channel Attribute Mappings

PUT 
/api/integration-instances/:integrationInstance/channel-attribute-mappings

Replace the instance's channel attribute mappings. The payload is authoritative: any code not present in mappings is unmapped, so send the full set you want kept, not just the changes.

Required scope: integrations:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

mappings: required array (send an empty array to clear every mapping on the instance). mappings[].code: required. The channel-native attribute code, exactly as returned by the candidates endpoint (manufacturer, custom.care_instructions). mappings[].label: optional human-readable label to remember the code by. Each mapping needs exactly one target, given one of three ways — attribute_id, attribute_name or sku_field. A mapping with none of the three is rejected with 422. mappings[].attribute_id: the existing catalog attribute this code maps onto. mappings[].attribute_name: name of a catalog attribute to map onto, provisioned if it does not exist yet. Matching is by exact name, so re-sending the same name re-uses the same attribute instead of creating a duplicate. mappings[].sku_field: any other product field target, taken from the targets list returned by the candidates endpoint — brand, mpn, weight, unit_cost, default_supplier, price.Retail.value, supplier_pricing.Standard Cost.value. The attributes.{id} form is also accepted and is stored as attribute_id, so a catalog attribute may be sent either way. A sku_field outside the published target list is ignored rather than errored, and because the payload is authoritative that leaves the code unmapped — read the response back to confirm what was stored. mappings[].enabled: optional, defaults to true. A disabled mapping is kept but stops being applied, which is the way to pause a mapping without losing the selection.

Only enabled mappings are applied on sync. Targets content sync governs (name, brand, barcode, mpn, weight, dimensions and catalog attributes) also feed drift detection, routed by the ownership configured in the content-sync settings. Pricing, supplier pricing, unit cost and default supplier targets are written on every sync but never compared. Requires Bearer token.

Request​

Responses​

OK

Response Headers
    Content-Type