Entity metadata and attribute management

The Catalog REST API can describe an entity's attributes and manage their definitions. An integration can discover the fields a tenant has configured, inspect where an attribute appears on a form, and create or change custom attributes through REST requests. This supports tenant-specific integrations that discover their schema and manage attribute definitions programmatically.

Beta scope: The attribute-management operations under the four /Metadata/.../attributes route families below are Beta. Their public contract can change while they remain in Beta, including incompatible changes identified in the changelog. Other Catalog operations retain their documented Stable status. See the REST API Evolution and Compatibility Policy.

The existing JSON Schema endpoints such as GET /catalog/$metadata and GET /catalog/Products/$metadata describe resource fields and relationships. Their names alone do not make them part of this Beta attribute-management surface. Use the Catalog endpoint reference for each operation's full request and response contract.

Each route family supports listing attributes (GET), reading one (GET .../attributes('{attributeId}')), creating one (POST), changing one (PATCH), and deleting one (DELETE).

Send X-API-KEY on every request. Write operations require an API key permitted to make the change. The examples below use Product attribute set 7 and illustrative identifiers; replace them with values from your tenant.

List the custom attributes and request a page of up to 20. attributeSetId selects the form used to report placement; it does not limit the attributes in the Product definition.

curl --get 'https://api2.saleslayer.com/catalog/Metadata/Products/attributes' \
  --data-urlencode 'attributeSetId=7' \
  --data-urlencode "\$filter=kind eq 'custom'" \
  --data-urlencode '$top=20' \
  -H 'X-API-KEY: YOUR_API_KEY'

The response contains an attribute summary array in value, a total in @count, and @nextLink while another page exists. Follow the returned @nextLink to continue. A list item includes placement and editability; read an individual attribute when you need type-specific details such as checklist options or table templates.

curl -X GET "https://api2.saleslayer.com/catalog/Metadata/Products/attributes('prod_boxmaterial')?attributeSetId=7" \
  -H 'X-API-KEY: YOUR_API_KEY'

The single-attribute response returns the attribute under value. Its placement is null when the selected form does not show it. These read operations also support Categories, Variants, and Custom Entities through the paths above. List operations support $filter, $top from 1 to 100, and $skip of 0 or greater.

Create a short-text attribute on the form for Product attribute set 7. The API derives its identifier from the title and returns the created attribute under value with 201 Created.

curl -X POST 'https://api2.saleslayer.com/catalog/Metadata/Products/attributes' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "shortText",
    "title": "Box material",
    "pageTitle": "Logistics",
    "fieldSize": "half",
    "attributeSet": { "id": 7 }
  }'

Use the returned value.identifier for later reads or changes. Products and Variants accept attributeSet in a create or update body to choose a form. Categories and Custom Entities have no attribute sets. The endpoint reference describes the supported attribute types and their type-specific fields.

Read the attribute first, then send a PATCH with its current type and the fields to change. This example renames an existing Product short-text attribute; omitted fields, or fields sent as null, keep their existing values. A successful update returns the current attribute under value with 200 OK.

curl -X PATCH "https://api2.saleslayer.com/catalog/Metadata/Products/attributes('prod_boxmaterial')" \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "shortText", "title": "Case material" }'

Check the type-specific update rules before changing an options or templates list: a supplied list replaces the whole existing list. The deleteExistingValues field empties existing item values, so leave it out for a metadata-only change.

For Products and Variants, onlyFromForm=true with attributeSetId removes an attribute from that attribute set's form while keeping the definition and existing item values. This request returns 204 No Content when applied.

curl -X DELETE "https://api2.saleslayer.com/catalog/Metadata/Products/attributes('prod_boxmaterial')?onlyFromForm=true&attributeSetId=7" \
  -H 'X-API-KEY: YOUR_API_KEY'

Without onlyFromForm=true, DELETE removes the custom attribute from the definition and every Product form, and every Product loses its value. Review the delete operation before using that mode.

Supply the Custom Entity denominator to inspect the tenant's attributes for that entity. For example, to list custom attributes of a Stores entity:

curl --get "https://api2.saleslayer.com/catalog/Metadata/CustomEntities('Stores')/attributes" \
  --data-urlencode "\$filter=kind eq 'custom'" \
  --data-urlencode '$top=20' \
  -H 'X-API-KEY: YOUR_API_KEY'

Use each returned identifier to read its full definition at /Metadata/CustomEntities('Stores')/attributes('{attributeId}'). This route family has no attributeSetId parameter.

• Catalog REST API overview
• Catalog endpoint reference
• Pagination and filtering
• REST API Evolution and Compatibility Policy