Skip to main content

Custom Attributes

Custom attributes in Product Experience Manager (PXM) offer a powerful way to store additional metadata for products, hierarchies, nodes, and prices. These attributes, structured as key-value pairs, enhance flexibility by enabling businesses to tailor data for both internal operations and customer-facing catalogs.

To ensure clear data management and visibility control, custom attributes are divided into two types: admin_attributes and shopper_attributes. Each serves a distinct purpose, providing businesses with the ability to separate internal data from information intended for shoppers. Understanding the differences between these types of attributes is key to leveraging their full potential.

note

Products also support custom data through extension templates, which use flows to attach structured, typed fields. Custom attributes (admin_attributes and shopper_attributes) are a simpler, more scalable alternative that gives you complete freedom to add any key-value string data to your products without predefined schemas. See Adding Custom Data to Products for a comparison of both approaches.

Overview of Shopper and Admin Attributes​

Here’s what you need to know about shopper and admin attributes:

Shopper Attributes​

Shopper attributes are designed for data that is visible in catalogs and accessible to both shoppers and administrators. These attributes allow businesses to present meaningful, customer-facing information that enhances the shopping experience. Common use cases include:

  • Promotional Tags: Label products with promotions, such as "promotion": "Black Friday".
  • Product Metadata: Include filterable attributes like "color": "red" or "material": "cotton" to improve search and filtering functionality.
  • Category Labels: Add context-specific tags, such as "category_label": "Electronics", to improve product categorization.

Shopper attributes are included in catalogs and can be used dynamically by storefronts to improve personalization and discoverability.

Admin Attributes​

Admin attributes are private and intended exclusively for internal use. They are not visible in catalogs or accessible to shoppers, making them ideal for operational data. Common use cases include:

  • Cost Tracking: Track internal costs with attributes like "production_cost": "50.00".
  • Workflow Management: Monitor internal workflows, such as "approval_status": "pending".
  • System Integrations: Store keys for integrations with enterprise systems like ERPs, such as "supplier_code": "A123".

These characteristics make shopper and admin attributes essential tools for tailoring catalogs, streamlining internal operations, and managing data visibility effectively.

Limits of Custom Attributes​

Custom attributes in Product Experience Manager (PXM) have the following limits:

  • Each group, shopper_attributes or admin_attributes, can contain up to 100 custom attributes.
  • Attribute names must be no longer than 64 characters and can only contain alphanumeric characters, underscores (_), and hyphens (-).
  • Values must be stored as strings.
  • Values must be no longer than 512 characters.

Using Custom Attributes​

Custom attributes can be created, updated or deleted using a single request payload. The API performs a partial update, meaning only the attributes explicitly included in the request will be modified or deleted. Any attributes not mentioned in the request will remain unchanged.

  • Creating/Updating Custom Attributes:
    Include the attributes you want to create/update in the request payload. You can add new attributes or update the values of existing ones.

  • Deleting Custom Attributes:
    Set its value to null in the request payload. This removes the attribute from the entity.

Example:

{
  "data": {
    "type": "hierarchy",
    "id": "hierarchy-id",
    "attributes": {
      "shopper_attributes": {
        "promotion": "Holiday Sale", 
        "category_label": "Gadgets",
        "seasonal_discount": null
      },
      "admin_attributes": {
        "approval_status": "approved",
        "workflow_stage": null
      }
    }
  }
}

What Happens:

  • In shopper_attributes:
    • promotion is added or updated to "Holiday Sale".
    • category_label is added or updated to "Gadgets".
    • seasonal_discount is deleted because its value is set to null.
  • In admin_attributes:
    • approval_status is added or updated to "approved".
    • workflow_stage is deleted because its value is set to null.
  • Any other attributes not included in the payload remain unchanged.

Custom Attributes on Products​

Custom attributes on products work the same way as on hierarchies, nodes, and prices, with a few additional capabilities.

Filtering​

You can filter products by custom attribute values using the eq, like, and in operators with dot notation. For example:

  • eq(shopper_attributes.color,red) — find products where the color shopper attribute is red.
  • like(shopper_attributes.material,*cotton*) — find products where the material shopper attribute contains cotton.
  • in(admin_attributes.warehouse,US-EAST,US-WEST) — find products where the warehouse admin attribute is one of the specified values.

CSV Import and Export​

When importing or exporting products via CSV, custom attributes use dot-notation column headers:

  • Column format: shopper_attributes.color, admin_attributes.cost_of_goods — one column per attribute.
  • Export column selection: You can request specific attributes (e.g., admin_attributes.cost_of_goods) or use a wildcard (admin_attributes.*) to export all attributes. You cannot mix wildcards with specific attributes for the same group.
  • Partial updates on import: Just like API, only columns present in the CSV affect those attributes. Attributes not included in the CSV remain unchanged.
  • Removing attributes on import: Use the sentinel value __REMOVE_ATTRIBUTE__ as the column value to delete a specific attribute. This is distinct from an empty string, which is a valid value.

Child Product Inheritance​

When products have variations, child (variant) products inherit custom attributes from their parent product:

  • When a child product is first created, it receives a copy of the parent's shopper_attributes and admin_attributes.
  • When variations are rebuilt, the parent's attributes are merged onto the child's existing attributes. The parent's values take precedence on overlapping attributes, but any attributes unique to the child are preserved.

Catalog Visibility​

When a product is published to a catalog:

  • shopper_attributes are visible in the catalog and accessible to both shoppers and administrators.
  • admin_attributes are not visible in the catalog. They are only accessible via the PXM API.

If a product and its associated pricebook both define shopper_attributes, the attributes are merged in the catalog. The product's shopper_attributes serve as the base layer, and the pricebook's shopper_attributes override on any conflicting attributes.

For example, if a product has { "color": "red", "material": "cotton" } and the pricebook has { "color": "blue", "promotion": "sale" }, the merged result in the catalog will be { "color": "blue", "material": "cotton", "promotion": "sale" }.

Both shopper_attributes and admin_attributes are included in catalog delta files.

Supported Endpoints​

Manage custom attributes across products, hierarchies, nodes, and pricebook prices with these endpoints:

Ask External AI