Elastic Path · Schema
Product Experience Manager Introduction
CommerceHeadless CommerceComposable CommerceeCommerceB2BProductsCatalogsOrdersPromotionsSubscriptionsPayments
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/elastic-path/main/json-schema/pim.json",
"title": "Product Experience Manager Introduction",
"description": "",
"version": "26.0612.7739142",
"$defs": {
"multi_links": {
"type": "object",
"description": "Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes \u2014 on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud",
"properties": {
"current": {
"description": "A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n",
"type": "string",
"example": "/pcm/hierarchies?page[offset]=10&page[limit]=10"
},
"first": {
"description": "A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n",
"type": "string",
"example": "/pcm/hierarchies?page[offset]=0&page[limit]=10"
},
"last": {
"description": "A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n",
"type": "string",
"example": "/pcm/hierarchies?page[offset]=20&page[limit]=10"
},
"next": {
"description": "A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n",
"type": "string",
"example": "/pcm/hierarchies?page[offset]=10&page[limit]=10"
},
"prev": {
"description": "A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n",
"type": "string",
"example": "/pcm/hierarchies?page[offset]=8&page[limit]=10"
}
}
},
"job": {
"type": "object",
"required": [
"id",
"type",
"attributes",
"meta"
],
"properties": {
"id": {
"description": "A unique identifier generated when a job is created.",
"type": "string"
},
"type": {
"description": "This represents the type of resource object being returned. Always `pim-job`.",
"type": "string",
"enum": [
"pim-job"
]
},
"attributes": {
"type": "object",
"required": [
"started_at",
"completed_at",
"created_at",
"updated_at",
"type",
"status"
],
"properties": {
"started_at": {
"description": "The date and time a job is started.",
"type": "string",
"example": "2020-09-22T09:00:00.000Z",
"format": "date-time",
"nullable": true
},
"completed_at": {
"type": "string",
"example": "2020-09-22T09:00:00.000Z",
"format": "date-time",
"nullable": true,
"description": "The date and time a job is completed."
},
"created_at": {
"type": "string",
"description": "The date and time a job is created.",
"example": "2020-09-22T09:00:00.000Z",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "The date and time a job is updated.",
"example": "2020-09-22T09:00:00.000Z",
"format": "date-time"
},
"type": {
"type": "string",
"description": "The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n",
"enum": [
"child-products",
"product-import",
"product-export",
"hierarchy-duplicate",
"pricebook-import",
"pricebook-delete",
"hierarchy-delete",
"indexing-job"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"cancelled",
"cancelling",
"started",
"success",
"failed"
]
}
}
},
"meta": {
"type": "object",
"required": [
"x_request_id"
],
"properties": {
"x_request_id": {
"type": "string",
"description": "Applies to all job types. A unique request ID is generated when a job is created."
},
"copied_from": {
"type": "string",
"description": "Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."
},
"hierarchy_id": {
"type": "string",
"description": "Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."
},
"file_locations": {
"type": "array",
"nullable": true,
"description": "If the job type is `product_export`, a link to the file is created when running a job.",
"items": {
"type": "string"
}
},
"filter": {
"type": "string",
"nullable": true,
"description": "The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."
}
}
}
}
},
"multi": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"links": {
"$ref": "#/components/schemas/multi_links"
},
"data": {
"description": "An array of jobs.",
"type": "array",
"items": {
"$ref": "#/components/schemas/job"
}
},
"meta": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"description": "Contains the results for the entire collection.",
"type": "object",
"required": [
"total"
],
"properties": {
"total": {
"description": "Total number of results for the entire collection.",
"type": "integer",
"example": 2
}
}
}
}
}
}
},
"error": {
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"items": {
"required": [
"status",
"title"
],
"properties": {
"status": {
"type": "string",
"description": "The HTTP response code of the error.",
"example": "500"
},
"title": {
"type": "string",
"description": "A brief summary of the error.",
"example": "Internal server error"
},
"detail": {
"type": "string",
"description": "Optional additional detail about the error.",
"example": "An internal error has occurred."
},
"request_id": {
"type": "string",
"description": "Internal request ID.",
"example": "00000000-0000-0000-0000-000000000000"
},
"meta": {
"type": "object",
"description": "Additional supporting meta data for the error.",
"example": {
"missing_ids": [
"e7d50bd5-1833-43c0-9848-f9d325b08be8"
]
}
}
}
}
}
}
},
"single": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"$ref": "#/components/schemas/job"
}
}
},
"errors": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"links": {
"$ref": "#/components/schemas/multi_links"
},
"meta": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "object",
"required": [
"total"
],
"properties": {
"total": {
"type": "integer",
"description": "Total number of job errors for this job."
}
}
}
}
},
"data": {
"type": "array",
"description": "An array of job errors.",
"items": {
"type": "object",
"properties": {
"type": {
"description": "This represents the type of resource object being returned. Always `pim-job-error`.",
"type": "string",
"example": "pim-job-error",
"enum": [
"pim-job-error"
]
},
"id": {
"description": "A unique identifier for a job error generated when a job error is created.",
"type": "string"
},
"attributes": {
"type": "object",
"properties": {
"message": {
"description": "A description of an error message.",
"type": "string",
"example": "data.attributes.sku: Must be unique amongst products."
}
}
}
}
}
}
}
},
"product_locales": {
"type": "object",
"description": "Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.",
"additionalProperties": {
"description": "A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "A localized name for the product."
},
"description": {
"type": "string",
"description": "A localized description for the product."
}
}
}
},
"shopper_attributes": {
"type": "object",
"description": "`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both",
"example": {
"cost_of_goods": "42.0",
"charge_type": "credit card"
},
"additionalProperties": {
"nullable": true,
"type": "string"
}
},
"admin_attributes": {
"type": "object",
"description": "`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values",
"example": {
"cost_of_goods": "42.0",
"charge_type": "credit card"
},
"additionalProperties": {
"nullable": true,
"type": "string"
}
},
"product_custom_inputs": {
"type": "object",
"description": "You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers persona",
"additionalProperties": {
"description": "A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "A name for the custom text field."
},
"validation_rules": {
"type": "array",
"description": "The validation rules for the custom text.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of validation rule. For example, `string`."
},
"options": {
"type": "object",
"description": "The options for the validation rule.",
"properties": {
"max_length": {
"type": "integer",
"description": "The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."
}
}
}
}
}
},
"required": {
"type": "boolean",
"description": "`true` or `false` depending on whether the custom text is required."
}
}
}
},
"product_build_rules": {
"type": "object",
"description": "You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm",
"properties": {
"default": {
"description": "Specifies the default behaviour, either `include` or `exclude`.",
"type": "string",
"enum": [
"include",
"exclude"
]
},
"include": {
"description": "An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.",
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
}
},
"exclude": {
"description": "An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.",
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"product_bundle_components": {
"type": "object",
"description": "With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a produc",
"additionalProperties": {
"description": "The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The component name. The component name is the name that is displayed in your storefront."
},
"options": {
"type": "array",
"description": "The product options included in a component. This can be the ID of another bundle.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of the product you want to add to a component."
},
"type": {
"type": "string",
"description": "This represents the type of object being returned. Always `product`."
},
"quantity": {
"type": "integer",
"minimum": 1,
"description": "The number of this product option that a shopper must purchase."
},
"min": {
"type": "integer",
"minimum": 1,
"description": "The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."
},
"max": {
"type": "integer",
"minimum": 1,
"description": "The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."
},
"sort_order": {
"type": "integer",
"description": "The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."
},
"default": {
"description": "Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).",
"type": "boolean"
},
"product_should_be_substituted_with_child": {
"description": "Whether the product option should be substituted with a child product.",
"type": "boolean"
},
"excluded_children": {
"description": "The IDs of child products that are excluded from the bundle option.",
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"min": {
"type": "integer",
"description": "The minimum number of product options a shopper can select from this component."
},
"max": {
"type": "integer",
"description": "The maximum number of product options a shopper can select from this component."
},
"sort_order": {
"type": "integer",
"description": "The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."
}
}
}
},
"product_response": {
"type": "object",
"properties": {
"id": {
"description": "A unique product ID that is generated when you create the product.",
"type": "string"
},
"type": {
"description": "This represents the type of resource object being returned. Always `product`.",
"type": "string",
"enum": [
"product"
]
},
"attributes": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"description": "A name for the product.",
"type": "string"
},
"description": {
"description": "A description for the product.",
"type": "string"
},
"slug": {
"description": "A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.",
"type": "string"
},
"sku": {
"description": "The unique stock keeping unit of the product.",
"type": "string"
},
"status": {
"description": "The status for the product, either `draft` or `live`.",
"type": "string",
"enum": [
"live",
"draft"
]
},
"commodity_type": {
"description": "The commodity type, either `physical` or `digital`.",
"type": "string",
"enum": [
"physical",
"digital"
]
},
"upc_ean": {
"description": "The universal product code or european article number of the product.",
"type": "string"
},
"mpn": {
"description": "The manufacturer part number of the product.",
"type": "string"
},
"external_ref": {
"description": "The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.",
"type": "string"
},
"locales": {
"$ref": "#/components/schemas/product_locales"
},
"tags": {
"description": "You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.",
"type": "array",
"items": {
"type": "string"
}
},
"shopper_attributes": {
"$ref": "#/components/schemas/shopper_attributes"
},
"admin_attributes": {
"$ref": "#/components/schemas/admin_attributes"
},
"extensions": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"nullable": true
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
}
},
"custom_inputs": {
"$ref": "#/components/schemas/product_custom_inputs"
},
"build_rules": {
"$ref": "#/components/schemas/product_build_rules"
},
"components": {
"$ref": "#/components/schemas/product_bundle_components"
}
}
},
"meta": {
"type": "object",
"properties": {
"created_at": {
"description": "The date and time a product is created.",
"type": "string",
"example": "2020-09-22T09:00:00.000Z",
"format": "date-time"
},
"updated_at": {
"description": "The date and time a product is updated.",
"type": "string",
"example": "2020-09-22T09:00:00.000Z",
"format": "date-time"
},
"owner": {
"description": "The resource owner, either `organization` or `store`.",
"type": "string",
"enum": [
"organization",
"store"
]
},
"variations": {
"description": "A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "A unique ID generated when a variation is created."
},
"name": {
"type": "string",
"description": "The name of a variation."
},
"sort_order": {
"type": "integer",
"description": "The sort order of the variation."
},
"options": {
"type": "array",
"items": {
"type": "object",
"description": "The options available for this variation.",
"properties": {
"id": {
"type": "string",
"description": "A unique ID that is generated an option is created."
},
"name": {
"type": "string",
"description": "The name of an option."
},
"description": {
"type": "string",
"description": "A description of an option."
},
"sort_order": {
"type": "integer",
"description": "The sort order of the option."
}
}
}
}
}
}
},
"custom_relationships": {
"description": "Custom relationship slugs that are attached to the product.",
"type": "array"
},
"child_variations": {
"description": "A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.",
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "A unique ID generated when a variation is created."
},
"name": {
"type": "string",
"description": "The name of a variation."
},
"sort_order": {
"description": "The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.",
"type": "integer"
},
"options": {
"type": "array",
"nullable": true,
"description": "This will be unset for child product variations.",
"items": {
"type": "object",
"description": "The options available for this variation.",
"properties": {
"id": {
"type": "string",
"description": "A unique ID that is generated an option is created."
},
"name": {
"type": "string",
"description": "The name of an option."
},
"description": {
"type": "string",
"description": "A description of an option."
},
"sort_order": {
"type": "integer",
"description": "The sort order of the option."
}
}
}
},
"option": {
"type": "object",
"description": "The options available for this variation.",
"properties": {
"id": {
"type": "string",
"description": "A unique ID that is generated an option is created."
},
"name": {
"type": "string",
"description": "The name of an option."
},
"description": {
"type": "string",
"description": "A description of an option."
},
"sort_order": {
"type": "integer",
"description": "The sort order of the option."
}
}
}
}
}
},
"product_types": {
"description": "One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n",
"type": "array",
"items": {
"type": "string",
"enum": [
"parent",
"child",
"bundle",
"standard"
]
}
},
"variation_matrix": {
"description": "The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in th
# --- truncated at 32 KB (170 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/json-schema/pim.json