{ "$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 the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.", "type": "object", "additionalProperties": true } } }, "relationships": { "description": "Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.", "type": "object", "additionalProperties": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier for a resource.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned.", "type": "string" } } } }, { "type": "object", "nullable": true, "properties": { "id": { "description": "A unique identifier for a resource.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned.", "type": "string" } } } ] }, "links": { "description": "Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n", "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "elastic_path_file": { "type": "object", "title": "ElasticPathFile", "properties": { "id": { "type": "string", "description": "The unique identifier for this file.", "format": "uuid" }, "type": { "description": "The type represents the object being returned.", "type": "string", "example": "file" }, "file_name": { "description": "The name of the file.", "type": "string", "example": "file_name.jpg" }, "mime_type": { "description": "The mime type of the file.", "type": "string", "example": "image/jpeg" }, "file_size": { "description": "The size of the file. Required when uploading files.", "type": "integer", "example": 36000 }, "public": { "description": "DEPRECATED Whether the file public or not. Required when uploading files.", "type": "boolean", "example": true }, "meta": { "properties": { "timestamps": { "type": "object", "description": "The date and time the file was created.", "properties": { "created_at": { "description": "The date and time the file was created.", "type": "string", "example": "2023-10-11T13:02:25.293Z" } } }, "dimensions": { "description": "The file dimensions.", "type": "object", "properties": { "width": { "description": "The width of the file.", "type": "integer", "example": 1800 }, "height": { "description": "The height of the file.", "type": "integer", "example": 1000 } } } } }, "links": { "description": "Links are used to allow you to move between requests.", "type": "object", "properties": { "self": { "description": "Single entities use a self parameter with a link to that specific resource.", "type": "string", "example": "https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52" } } }, "link": { "type": "object", "description": "The publicly available URL for this file.", "properties": { "href": { "description": "The publicly available URL for this file.", "type": "string", "example": "https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png" }, "meta": { "type": "object", "properties": { "results": { "description": "Contains the results for the entire collection.", "type": "object", "properties": { "total": { "description": "Total number of results for the entire collection.", "type": "integer", "example": 2 } } } } } } } } }, "included_response": { "type": "object", "description": "Included is an array of resources that are included in the response.", "properties": { "main_images": { "description": "The main images associated with a product.", "type": "array", "items": { "$ref": "#/components/schemas/elastic_path_file" } }, "component_products": { "description": "Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.", "type": "array", "items": { "$ref": "#/components/schemas/product_response" } }, "files": { "description": "The files associated with a product.", "type": "array", "items": { "$ref": "#/components/schemas/elastic_path_file" } } } }, "multi_product_response": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/product_response" } }, "included": { "$ref": "#/components/schemas/included_response" }, "links": { "$ref": "#/components/schemas/multi_links" }, "meta": { "type": "object", "properties": { "results": { "description": "Contains the results for the entire collection.", "type": "object", "properties": { "total": { "description": "Total number of results for the entire collection.", "type": "integer", "example": 2 } } } } } } }, "product_attributes": { "type": "object", "additionalProperties": false, "properties": { "external_ref": { "type": "string", "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." }, "name": { "type": "string", "description": "The product name to display to customers." }, "description": { "description": "A description for the product.", "type": "string" }, "slug": { "type": "string", "description": "The unique slug of the product. 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." }, "sku": { "type": "string", "description": "The unique stock keeping unit of the product." }, "status": { "type": "string", "enum": [ "live", "draft" ], "description": "The status for the product, either `draft` or `live`. Default is `draft`. For a product to appear in a catalog it must be in a `live` status." }, "commodity_type": { "description": "The commodity type, either `physical` or `digital`.", "type": "string", "enum": [ "physical", "digital" ] }, "upc_ean": { "type": "string", "description": "The universal product code or european article number of the product." }, "mpn": { "type": "string", "description": "The manufacturer part number of the product." }, "tags": { "type": "array", "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. See [Product Tags](/docs/api/pxm/products/product-tags).", "items": { "type": "string" } }, "build_rules": { "$ref": "#/components/schemas/product_build_rules" }, "locales": { "$ref": "#/components/schemas/product_locales" }, "custom_inputs": { "$ref": "#/components/schemas/product_custom_inputs" }, "components": { "$ref": "#/components/schemas/product_bundle_components" } } }, "create_product_request": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "description": "This represents the type of resource being returned. Always `product`.", "type": "string", "enum": [ "product" ], "example": "product" }, "attributes": { "$ref": "#/components/schemas/product_attributes" }, "relationships": { "description": "Relationships are established between different product entities.", "type": "object", "properties": { "variations": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier for a resource.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned.", "type": "string" } } } } } } } } } } } }, "single_product_response": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/product_response" }, "included": { "$ref": "#/components/schemas/included_response" } } }, "update_product_request": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes", "id" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `product`.", "type": "string", "enum": [ "product" ], "example": "product" }, "id": { "type": "string", "description": "The unique identifier of the product. Must match the product ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" }, "attributes": { "$ref": "#/components/schemas/product_attributes" } } } } }, "attributes": { "type": "object", "properties": { "name": { "description": "The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.", "type": "string" }, "description": { "description": "A description for a node.", "type": "string" }, "slug": { "description": "A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.", "type": "string" }, "curated_products": { "description": "You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.", "type": "array", "items": { "description": "A list of product IDs whose products you want to curate.", "type": "string" } }, "admin_attributes": { "$ref": "#/components/schemas/admin_attributes" }, "shopper_attributes": { "$ref": "#/components/schemas/shopper_attributes" }, "locales": { "description": "Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.", "type": "object", "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", "additionalProperties": false, "properties": { "name": { "description": "A localized hierarchy or node name.", "type": "string" }, "description": { "description": "A localized hierarchy or node description.", "type": "string" } } } } } }, "relationships": { "type": "object", "description": "Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.", "properties": { "children": { "description": "The child nodes related to the resource.", "type": "object", "properties": { "data": { "description": "An array of child nodes.", "type": "array", "items": {} }, "links": { "description": "Links allow you to move between requests.", "type": "object", "properties": { "related": { "description": "A link to a related resource.", "type": "string" } } } } }, "parent": { "description": "The parent node related to the resource", "type": "object", "properties": { "data": { "description": "The parent node", "type": "object", "required": [ "id", "type" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `node`.", "type": "string", "enum": [ "node" ] }, "id": { "description": "The unique identifier of a node.", "type": "string" } } } } }, "products": { "type": "object", "description": "The products related to the resource.", "properties": { "data": { "description": "An array of products.", "type": "array", "items": {} }, "links": { "type": "object", "description": "Links allow you to move between requests.", "properties": { "related": { "description": "A link to a related resource.", "type": "string" } } } } } } }, "node": { "type": "object", "required": [ "id", "type", "attributes", "relationships", "meta" ], "properties": { "id": { "description": "The unique identifier of a node.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `node`.", "type": "string", "enum": [ "node" ] }, "attributes": { "$ref": "#/components/schemas/attributes" }, "relationships": { "$ref": "#/components/schemas/relationships" }, "meta": { "type": "object", "properties": { "sort_order": { "description": "The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).", "type": "integer" }, "created_at": { "description": "The date and time a node is created.", "type": "string", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "description": "The date and time a node was updated.", "type": "string", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "parent_name": { "description": "The name of the parent of the node if one exists.", "type": "string" }, "owner": { "description": "The node owner, either `organization` or `store`.", "type": "string", "enum": [ "store", "organization" ] }, "has_children": { "description": "Whether the node has child nodes.", "type": "boolean" }, "hierarchy_id": { "description": "The unique identifier of hierarchy", "type": "string" }, "breadcrumbs": { "type": "array", "description": "Breadcrumbs", "items": { "type": "object", "properties": { "id": { "description": "The unique identifier of a hierarchy/node.", "type": "string" }, "name": { "description": "The name of the hierarchy/node.", "type": "string" }, "slug": { "description": "A slug for the hierarchy/node.", "type": "string" }, "locales": { "description": "Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.", "type": "object", "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", "additionalProperties": false, "properties": { "name": { "description": "A localized hierarchy or node name.", "type": "string" } } } } } } } } } } }, "multi_meta": { "type": "object", "properties": { "results": { "description": "Contains the results for the entire collection.", "type": "object", "properties": { "total": { "description": "Total number of results for the entire collection.", "type": "integer", "example": 30, "minimum": 0 } } } } }, "multi_nodes": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "An array of nodes.", "type": "array", "items": { "$ref": "#/components/schemas/node" } }, "meta": { "$ref": "#/components/schemas/multi_meta" }, "links": { "$ref": "#/components/schemas/multi_links" } } }, "template_response": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier for a template generated when a template is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `template`.", "type": "string", "enum": [ "template" ] } } } } } }, "product_templates_request": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of a template." }, "type": { "type": "string", "enum": [ "template" ], "description": "This represents the type of resource object being returned. Always `template`." } } } } } }, "component_products_response": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of a product component generated when a product is created." }, "type": { "type": "string", "enum": [ "product" ], "description": "This represents the type of resource object being returned. Always `product`." } } } } } }, "file_response": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the file." }, "type": { "type": "string", "description": "This represents the type of resource object being returned. Always `file`.", "enum": [ "file" ] }, "meta": { "type": "object", "properties": { "created_at": { "type": "string", "description": "The date and time the file relationship was created.", "format": "date-time", "nullable": true }, "tags": { "type": "array", "description": "The file tags.", "items": { "type": "string" } } } } } } } } }, "product_files_request": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier for a file generated when a file is created.", "type": "string" }, "type": { "description": "This represents the type of resource being returned. Always `file`.", "type": "string", "enum": [ "file" ] }, "meta": { "type": "object", "properties": { "tags": { "description": "The files associated with a product.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } } } }, "variations_response": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier generated when a variation is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation`.", "type": "string", "enum": [ "product-variation" ] }, "meta": { "type": "object", "properties": { "created_at": { "description": "The date and time a resource is created.", "type": "string", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" } } } } } } } }, "product_variations_request": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the product variation." }, "type": { "type": "string", "enum": [ "product-variation" ], "description": "This represents the type of resource being returned. Always `product-variation`." } } } } } }, "main_image_response": { "type": "object", "properties": { "data": { "description": "A file object representing the main image, or null if no main image is set.", "type": "object", "nullable": true, "properties": { "id": { "description": "A unique identifier for the image file generated automatically when a file is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `file`.", "type": "string", "enum": [ "file" ] } } } } }, "replace_main_image_request": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the new image file.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "type": "string", "enum": [ "file" ] } } } } }, "main_image_request": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the image file.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "description": "This represents the type of resource being returned. Always `file`.", "type": "string", "enum": [ "file" ] } } } } }, "attach_custom_relationship_request": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "slug", "type" ], "properties": { "slug": { "type": "string", "description": "The slug of the custom relationship." }, "type": { "type": "string", "enum": [ "custom-relationship" ], "description": "This represents the type of resource. Always `custom-relationship`." } } } } } }, "req_attributes_custom_relationship": { "type": "object", "additionalProperties": false, "required": [ "name", "slug" ], "properties": { "name": { "description": "The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.", "type": "string", "example": "Related Products" }, "description": { "description": "A description of the custom relationship.", "type": "string", "example": "A list of related products shown on the PDP." }, "slug": { "description": "A unique slug for the custom relationship. Must match the slug specified in the request path. 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.", "type": "string", "example": "CRP_related_products", "pattern": "^[A-Za-z0-9._-]+$" }, "sort_order": { "description": "The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.", "nullable": true, "type": "integer", "example": 5 }, "external_name": { "description": "The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.", "nullable": true, "type": "string", "example": "Similar items to consider" }, "external_description": { "description": "The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.", "nullable": true, "type": "string", "example": "Check out these similar products that may also meet your needs or match your preferences." }, "bi_directional": { "type": "boolean", "description": "Is this relationship one way or bi-directional `true` or `false`. Default is false", "default": false } } }, "custom_relationship": { "type": "object", "required": [ "id", "type", "attributes", "meta" ], "properties": { "id": { "description": "A unique identifier generated when a custom relationship is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `custom-relationship`.", "type": "string", "enum": [ "custom-relationship" ] }, "attributes": { "$ref": "#/components/schemas/req_attributes_custom_relationship" }, "meta": { "type": "object", "required": [ "owner", "timestamps" ], "properties": { "owner": { "description": "The owner of the resource.", "type": "string", "example": "store" }, "timestamps": { "type": "object", "required": [ "created_at", "updated_at" ], "properties": { "created_at": { "description": "The date and time the resource is created.", "type": "string", "example": "2024-01-10T20:16:35.343Z", "format": "date-time" }, "updated_at": { "description": "The date and time the resource is updated.", "type": "string", "example": "2024-01-10T20:16:35.343Z", "format": "date-time" } } } } } } }, "multi_links_cr": { "type": "object", "description": "Links are used to allow you to move between requests.", "properties": { "first": { "description": "Always the first page.", "type": "string", "example": "/pcm/custom_relationships?page[offset]=0&page[limit]=10" }, "last": { "description": "This is `null` if there is only one page.", "type": "string", "example": "/pcm/custom_relationships?page[offset]=20&page[limit]=10" }, "next": { "description": "This is `null` if there is only one page.", "type": "string", "example": "/pcm/custom_relationships?page[offset]=10&page[limit]=10" }, "prev": { "description": "This is `null` if you on the first page.", "type": "string", "example": "/pcm/custom_relationships?page[offset]=8&page[limit]=10" } } }, "multi_custom_relationships": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/custom_relationship" } }, "links": { "$ref": "#/components/schemas/multi_links_cr" }, "meta": { "$ref": "#/components/schemas/multi_meta" } } }, "product_association_list_product_ids_response": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "description": "A unique identifier generated when a product relationship is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product`.", "type": "string", "enum": [ "product" ] }, "attributes": { "type": "object", "properties": { "sort_order": { "description": "The order in which the product to product should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.", "nullable": true, "type": "integer", "example": 5 } } } } } } } }, "product_association_request": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the product you want to relate." }, "type": { "type": "string", "enum": [ "product" ], "description": "This represents the type of resource being returned. Always `product`." }, "attributes": { "type": "object", "properties": { "sort_order": { "description": "The order in which the product to product should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.", "nullable": true, "type": "integer", "example": 5 } } } } } } } }, "product_association_response": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "associated_products": { "description": "A list of product IDs that have been successfully associated with this custom relationship.", "type": "array", "items": { "type": "string" }, "example": [ "68c48149-0e94-4ef2-93d5-8d5f3774980a", "ab4826d1-4a5a-4951-a2a5-98058899f891" ] }, "products_not_associated": { "description": "A list of products that could not be associated, including the reasons why.", "type": "array", "items": { "type": "object", "properties": { "ID": { "description": "The ID of the product that could not be associated.", "type": "string", "example": "97b7fac2-91dd-4755-81b0-bdffe8e7eabd" }, "Details": { "description": "Details about why the product could not be associated.", "type": "string", "example": "could not find product" } } }, "example": [ { "ID": "97b7fac2-91dd-4755-81b0-bdffe8e7eabd", "Details": "could not find product" }, { "ID": "a0ef3291-2ec1-4d7d-9d6d-1705ae01bb99", "Details": "product already has 5 custom relationships, cannot associate more as it has reached the limit of 5 custom relationships" }, { "ID": "bde79675-4783-40b7-8a7e-ac6df41459c6", "Details": "product already has 5 custom relationships, cannot associate more as it has reached the limit of 5 custom relationships" }, { "ID": "aaddd5f4-a5f8-42e8-be9a-097986f22e58", "Details": "exceeded maximum allowed associations (2000). Please review and try again" } ] }, "owner": { "description": "The owner of the resource.", "type": "string", "example": "store" }, "timestamps": { "type": "object", "properties": { "created_at": { "description": "The date and time the resource was created.", "type": "string", "example": "2024-08-08T09:29:08.295Z", "format": "date-time" }, "updated_at": { "description": "The date and time the resource was last updated.", "type": "string", "example": "2024-08-08T09:29:08.295Z", "format": "date-time" } } } } } } }, "product_association_delete_request": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the product you want to relate." }, "type": { "type": "string", "enum": [ "product" ], "description": "This represents the type of resource being returned. Always `product`." } } } } } }, "multi_variations": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier for a variation.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation`.", "type": "string", "enum": [ "product-variation" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The name of a variation.", "type": "string" }, "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" } } }, "meta": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "description": "The options available for this variation.", "properties": { "id": { "type": "string", "description": "A unique ID that is generated when an option is created." }, "name": { "type": "string", "description": "A human recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed." }, "description": { "type": "string", "description": "A human recognizable description of the option." }, "created_at": { "type": "string", "description": "The date and time an option is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time an option is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "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" }, "modifiers": { "type": "array", "description": "The modifiers associated with this option.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier generated when a modifier is created." }, "type": { "type": "string", "description": "The type of modifier.", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "type": "string", "nullable": true, "description": "Required for non-builder modifiers. The value of the modifier type." }, "seek": { "type": "string", "nullable": true, "description": "Required for builder modifiers. The sub-string to find and replace." }, "set": { "type": "string", "nullable": true, "description": "Required for builder modifiers. The value to replace matches of the seek string." }, "owner": { "type": "string", "nullable": true, "description": "The owner of the modifier, either `organization` or `store`.", "enum": [ "organization", "store" ] } } } } } } }, "owner": { "type": "string", "description": "The owner of the resource, either `organization` or `store`.", "enum": [ "organization", "store" ] }, "created_at": { "type": "string", "description": "The date and time a variation is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time a variation is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" } } } } } }, "links": { "$ref": "#/components/schemas/multi_links" }, "meta": { "type": "object", "properties": { "results": { "description": "Contains the results for the entire collection.", "type": "object", "properties": { "total": { "description": "Total number of results for the entire collection.", "type": "integer", "example": 3 } } } } } } }, "create_variation": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `product-variation`.", "type": "string", "enum": [ "product-variation" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The variation name.", "type": "string" }, "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. \n \n 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. \n \n 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.\n \n You must rebuild your products for the sort order changes to take effect.\n", "type": "integer" } } } } } } }, "created_variation": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "meta" ], "properties": { "id": { "description": "A unique identifier generated when a variation is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation`.", "type": "string", "enum": [ "product-variation" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "A human-recognizable identifier for a variation.", "type": "string" }, "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" } } }, "meta": { "type": "object", "properties": { "owner": { "description": "The owner of the resource, either `organization` or `store`.", "type": "string", "enum": [ "organization", "store" ] }, "created_at": { "type": "string", "description": "The date and time a variation is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time a variation is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" } } } } } } }, "single_variation": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "meta" ], "properties": { "id": { "description": "A unique identifier for a variation.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation`.", "type": "string", "enum": [ "product-variation" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The name for a variation.", "type": "string" }, "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" } } }, "meta": { "type": "object", "properties": { "options": { "description": "A variation option represents an option for selection for a single product-variation. For example, if your variation is `color`, you might have three possible options; red, green, and blue.", "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": "A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed." }, "description": { "type": "string", "description": "A description for an option." }, "created_at": { "type": "string", "description": "The date and time an option is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time an option is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "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" }, "modifiers": { "type": "array", "description": "The modifiers associated with this option.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier generated when a modifier is created." }, "type": { "type": "string", "description": "The type of modifier.", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "type": "string", "nullable": true, "description": "Required for non-builder modifiers. The value of the modifier type." }, "seek": { "type": "string", "nullable": true, "description": "Required for builder modifiers. The sub-string to find and replace." }, "set": { "type": "string", "nullable": true, "description": "Required for builder modifiers. The value to replace matches of the seek string." }, "owner": { "type": "string", "nullable": true, "description": "The owner of the modifier, either `organization` or `store`.", "enum": [ "organization", "store" ] } } } } } } }, "owner": { "description": "The owner of the resource, either `organization` or `store`.", "type": "string", "enum": [ "organization", "store" ] }, "created_at": { "type": "string", "description": "The date and time a variation is created." }, "updated_at": { "type": "string", "description": "The date and time a variation is updated." } } } } } } }, "update_variation": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes", "id" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `product-variation`.", "type": "string", "enum": [ "product-variation" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The variation name.", "type": "string" }, "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. \n \n 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. \n \n 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.\n \n You must rebuild your products for the sort order changes to take effect.\n", "type": "integer" } } }, "id": { "type": "string", "description": "The unique identifier of the variation. Must match the variation ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" } } } } }, "multi_options": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier generated when an option is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation-option`.", "type": "string", "enum": [ "product-variation-option" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.", "type": "string" }, "description": { "description": "A human-recognizable description for the option.", "type": "string" }, "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" } } }, "meta": { "type": "object", "properties": { "owner": { "description": "The owner of a resource, either `organization` or `store`.", "type": "string", "enum": [ "organization", "store" ] }, "created_at": { "type": "string", "description": "The date and time an option is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time an option is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" } } } } } }, "links": { "$ref": "#/components/schemas/multi_links" }, "meta": { "type": "object", "properties": { "results": { "description": "Contains the results for the entire collection.", "type": "object", "properties": { "total": { "description": "Total number of results for the entire collection.", "type": "integer", "example": 3 } } } } } } }, "create_option": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `product-variation-option`.", "type": "string", "enum": [ "product-variation-option" ] }, "attributes": { "type": "object", "additionalProperties": false, "required": [ "name", "description" ], "properties": { "name": { "description": "A human recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.", "type": "string" }, "sort_order": { "description": "By default, variations and variation options are sorted alphabetically. You can use the `sort_order` attribute to sort the order of your variation and variation options in the `variation_matrix`. \n \n 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. \n \n The variation option with the highest value of `sort_order` is displayed first. For example, a variation option with a `sort_order` value of `3` appears before a variation option 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, and so on, zero or negative numbers. \n \n 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.\n \n You must rebuild your products for the sort order changes to take effect.\n", "type": "integer" }, "description": { "description": "A description of a product variation option.", "type": "string" } } } } } } }, "created_option": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "description": "A unique identifier that is generated when an option is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation-option`.", "type": "string", "enum": [ "product-variation-option" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.", "type": "string" }, "description": { "description": "A human-recognizable description for the option.", "type": "string" }, "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" } } }, "meta": { "type": "object", "properties": { "owner": { "description": "The owner of a resource, either `organization` or `store`.", "type": "string", "enum": [ "organization", "store" ] }, "created_at": { "type": "string", "description": "The date and time an option is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time an option is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" } } } } } } }, "single_option": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "meta" ], "properties": { "id": { "description": "The unique identifier generated when an option is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation-option`.", "type": "string", "enum": [ "product-variation-option" ] }, "attributes": { "type": "object", "description": "A variation option represents an option for selection for a single product-variation. For example, if your variation is `color`, you might have three possible options; red, green, and blue.", "additionalProperties": false, "properties": { "name": { "description": "A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.", "type": "string" }, "description": { "description": "A human-recognizable description for the option.", "type": "string" }, "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" } } }, "meta": { "type": "object", "properties": { "owner": { "description": "The owner of a resource, either `organization` or `store`.", "type": "string", "enum": [ "organization", "store" ] }, "created_at": { "type": "string", "description": "The date and time an option is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time an option is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "modifiers": { "type": "array", "description": "The modifiers associated with this option.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier generated when a modifier is created." }, "type": { "type": "string", "description": "The type of modifier.", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "type": "string", "nullable": true, "description": "Required for non-builder modifiers. The value of the modifier type." }, "seek": { "type": "string", "nullable": true, "description": "Required for builder modifiers. The sub-string to find and replace." }, "set": { "type": "string", "nullable": true, "description": "Required for builder modifiers. The value to replace matches of the seek string." }, "owner": { "type": "string", "nullable": true, "description": "The owner of the modifier, either `organization` or `store`.", "enum": [ "organization", "store" ] } } } } } } } } } }, "update_option": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes", "id" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `product-variation-option`.", "type": "string", "enum": [ "product-variation-option" ] }, "attributes": { "type": "object", "additionalProperties": false, "required": [ "name", "description" ], "properties": { "name": { "description": "A human recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.", "type": "string" }, "description": { "description": "The description of the option.", "type": "string" }, "sort_order": { "description": "By default, variations and variation options are sorted alphabetically. You can use the `sort_order` attribute to sort the order of your variation and variation options in the `variation_matrix`. 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. \n\nThe variation option with the highest value of `sort_order` is displayed first. For example, a variation option with a `sort_order` value of `3` appears before a variation option with a `sort_order` value of `2`. \n\nYou can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, and so on, zero or negative numbers. \n\nYou can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.\n\nYou must rebuild your products for the sort order changes to take effect.\n", "type": "integer" } } }, "id": { "type": "string", "description": "The unique identifier of the option. Must match the option ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" } } } } }, "multi_modifiers": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier for a modifier that is generated automatically when a modifier is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation-modifier`.", "type": "string", "enum": [ "product-variation-modifier" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "type": { "description": "You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n", "type": "string", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "description": "Required for non-builder modifiers. The value of the modifier type.", "type": "string" }, "seek": { "description": "Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.", "type": "string" }, "set": { "description": "Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.", "type": "string" }, "reference_name": { "description": "The name of the modifier.", "type": "string" } } }, "meta": { "type": "object", "properties": { "owner": { "description": "The owner of a resource, either `organization` or `store`.", "type": "string", "enum": [ "store", "organization" ] } } } } } }, "links": { "$ref": "#/components/schemas/multi_links" }, "meta": { "type": "object", "properties": { "results": { "type": "object", "description": "Contains the results for the entire collection.", "properties": { "total": { "description": "Total number of results for the entire collection.", "type": "integer", "example": 3 } } } } } } }, "create_modifier": { "type": "object", "description": "Use modifiers to change the properties of child products that are inherited from a parent product. With modifiers, you only need to have one parent product with a variation attached to the product.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `product-variation-modifier`.", "type": "string", "enum": [ "product-variation-modifier" ] }, "attributes": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "type": "string", "description": "You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. See [Create a Modifier](/docs/api/pxm/products/create-modifier).\n", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "description": "Required for non-builder modifiers. The value of the modifier type.", "type": "string" }, "seek": { "description": "Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.", "type": "string" }, "set": { "description": "Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.", "type": "string" }, "reference_name": { "description": "A name for the modifier.", "type": "string" } } } } } } }, "created_modifier": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "description": "A unique identifier for a modifier that is generated automatically when a modifier is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation-modifier`.", "type": "string", "enum": [ "product-variation-modifier" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "type": { "description": "You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n", "type": "string", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "description": "Required for non-builder modifiers. The value of the modifier type.", "type": "string" }, "seek": { "description": "Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.", "type": "string" }, "set": { "description": "Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.", "type": "string" }, "reference_name": { "description": "The name of the modifier.", "type": "string" } } }, "meta": { "type": "object", "properties": { "owner": { "description": "The owner of the resource, either `organization` or `store`.", "type": "string", "enum": [ "organization", "store" ] } } } } } } }, "single_modifier": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "description": "A unique identifier for a modifier that is generated automatically when a modifier is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `product-variation-modifier`.", "type": "string", "enum": [ "product-variation-modifier" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "type": { "description": "You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n", "type": "string", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "description": "Required for non-builder modifiers. The value of the modifier type.", "type": "string" }, "seek": { "description": "Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.", "type": "string" }, "set": { "description": "Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.", "type": "string" }, "reference_name": { "description": "The name of the modifier.", "type": "string" } } }, "meta": { "type": "object", "description": "The owner of the resource, either `organization` or `store`.", "properties": { "owner": { "type": "string", "enum": [ "organization", "store" ] } } } } } } }, "update_modifier": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes", "id" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `product-variation-modifier`.", "type": "string", "enum": [ "product-variation-modifier" ] }, "attributes": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "description": "You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n", "type": "string", "enum": [ "commodity_type", "status", "price", "name_append", "name_prepend", "name_equals", "sku_append", "sku_prepend", "sku_equals", "sku_builder", "slug_append", "slug_prepend", "slug_equals", "slug_builder", "description_append", "description_prepend", "description_equals", "custom_inputs_equals", "build_rules_equals", "locales_equals", "upc_ean_equals", "mpn_equals", "external_ref_equals" ] }, "value": { "description": "Required for non-builder modifiers. The value of the modifier type.", "type": "string" }, "seek": { "description": "Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.", "type": "string" }, "set": { "description": "Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.", "type": "string" }, "reference_name": { "description": "The name of the modifier.", "type": "string" } } }, "id": { "type": "string", "description": "The unique identifier of the modifier. Must match the modifier ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" } } } } }, "attributes_hierarchy": { "type": "object", "properties": { "name": { "description": "The name of a hierarchy, such as `Major Appliances`.", "type": "string" }, "description": { "description": "A description for a hierarchy.", "type": "string" }, "slug": { "description": "A unique slug for a hierarchy.", "type": "string" }, "admin_attributes": { "$ref": "#/components/schemas/admin_attributes" }, "shopper_attributes": { "$ref": "#/components/schemas/shopper_attributes" }, "locales": { "description": "Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.", "type": "object", "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", "additionalProperties": false, "properties": { "name": { "description": "A localized hierarchy or node name.", "type": "string" }, "description": { "description": "A localized hierarchy or node description.", "type": "string" } } } } } }, "relationships_hierarchy": { "type": "object", "properties": { "children": { "description": "The child nodes related to the hierarchy.", "type": "object", "properties": { "data": { "description": "An array of child nodes.", "type": "array", "items": {} }, "links": { "description": "Links allow you to move between requests.", "type": "object", "properties": { "related": { "description": "A link to a related resource.", "type": "string" } } } } } } }, "hierarchy": { "type": "object", "required": [ "id", "type", "meta", "relationships", "attributes" ], "properties": { "id": { "description": "A unique identifier generated when a hierarchy is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `hierarchy`.", "type": "string", "enum": [ "hierarchy" ] }, "attributes": { "$ref": "#/components/schemas/attributes_hierarchy" }, "relationships": { "$ref": "#/components/schemas/relationships_hierarchy" }, "meta": { "type": "object", "properties": { "created_at": { "description": "The date and time a hierarchy is created.", "type": "string", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "description": "The date and time a hierarchy is updated.", "type": "string", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "owner": { "description": "The owner of a resource, either `organization` or `store`.", "type": "string", "enum": [ "store", "organization" ] }, "has_children": { "description": "Whether the hierarchy has child nodes.", "type": "boolean" }, "breadcrumbs": { "type": "array", "description": "Breadcrumbs", "items": { "type": "object", "properties": { "id": { "description": "A unique identifier generated when a hierarchy is created.", "type": "string" }, "name": { "description": "The name of a hierarchy, such as `Major Appliances`.", "type": "string" }, "slug": { "description": "A unique slug for a hierarchy.", "type": "string" }, "locales": { "description": "Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.", "type": "object", "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", "additionalProperties": false, "properties": { "name": { "description": "A localized hierarchy or node name.", "type": "string" } } } } } } } } } } }, "multi_hierarchy": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/hierarchy" } }, "links": { "$ref": "#/components/schemas/multi_links" }, "meta": { "$ref": "#/components/schemas/multi_meta" } } }, "req_attributes_hierarchy": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The name of the hierarchy, such as `Major Appliances`.", "type": "string" }, "description": { "description": "A description of the hierarchy.", "type": "string" }, "slug": { "description": "A unique slug for the hierarchy.", "type": "string" }, "admin_attributes": { "$ref": "#/components/schemas/admin_attributes" }, "shopper_attributes": { "$ref": "#/components/schemas/shopper_attributes" }, "locales": { "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.", "type": "object", "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", "additionalProperties": false, "properties": { "name": { "description": "A localized name for the hierarchy.", "type": "string" }, "description": { "description": "A localized description for the hierarchy.", "type": "string" } } } } } }, "create_hierarchy": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `hierarchy`.", "type": "string", "enum": [ "hierarchy" ] }, "attributes": { "$ref": "#/components/schemas/req_attributes_hierarchy" } } } } }, "single_hierarchy": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/hierarchy" } } }, "nodes_or_hierarchies": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "An array of nodes or hierarchies.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/node" }, { "$ref": "#/components/schemas/hierarchy" } ], "discriminator": { "propertyName": "type" } } }, "meta": { "$ref": "#/components/schemas/multi_meta" }, "links": { "$ref": "#/components/schemas/multi_links" } } }, "update_hierarchy": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the hierarchy. Must match the hierarchy ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "description": "This represents the type of resource object being returned. Always `hierarchy`.", "type": "string", "enum": [ "hierarchy" ], "example": "hierarchy" }, "attributes": { "$ref": "#/components/schemas/req_attributes_hierarchy" } } } } }, "attributes_nodes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.", "type": "string" }, "description": { "description": "A description of the node.", "type": "string" }, "slug": { "description": "A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.", "type": "string" }, "curated_products": { "description": "You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront. See [Curating Products in a Node](/docs/api/pxm/products/create-node#curating-products-in-a-node).", "type": "array", "items": { "description": "A list of product IDs for the products that you want to curate in a node.", "type": "string" } }, "admin_attributes": { "$ref": "#/components/schemas/admin_attributes" }, "shopper_attributes": { "$ref": "#/components/schemas/shopper_attributes" }, "locales": { "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.", "type": "object", "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", "additionalProperties": false, "properties": { "name": { "description": "A localized name for the node.", "type": "string" }, "description": { "description": "A localized description for the node.", "type": "string" } } } } } }, "create_node": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `node`.", "type": "string", "enum": [ "node" ] }, "attributes": { "$ref": "#/components/schemas/attributes_nodes" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "sort_order": { "description": "You can sort the order of your nodes, regardless of where the nodes are in the hierarchy. The `sort_order` for each node. This value determines the order of nodes in the response for the `Get a Node\u2019s Children` request. The node with the highest value of sort_order is displayed first. For example, a node with a sort_order value of 3 appears before a node with a sort_order value of 2.\n\n- If you don\u2019t provide `sort_order` when creating nodes, all child nodes in the response for `Get a Node\u2019s Children` request are ordered by the `updated_at` time in descending order, with the most recently updated child node first.\n- If you set `sort_order` for only a few child nodes or not all, the child nodes with a `sort_order` value appear first and then other child nodes appear in the order of `updated_at` time. See [Sorting Nodes in a hierarchy]().\n", "type": "integer" } } } } } } }, "single_node": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/node" } } }, "update_node": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the node. Must match the node ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "description": "This represents the type of resource object being returned. Always `node`.", "type": "string", "enum": [ "node" ] }, "attributes": { "$ref": "#/components/schemas/attributes_nodes" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "sort_order": { "description": "You can sort the order of your nodes, regardless of where the nodes are in the hierarchy. The `sort_order` for each node. This value determines the order of nodes in the response for the `Get a Node\u2019s Children` request. The node with the highest value of sort_order is displayed first. For example, a node with a sort_order value of 3 appears before a node with a sort_order value of 2.\n \n- If you don\u2019t provide `sort_order` when creating nodes, all child nodes in the response for `Get a Node\u2019s Children` request are ordered by the `updated_at` time in descending order, with the most recently updated child node first.\n- If you set `sort_order` for only a few child nodes or not all, the child nodes with a `sort_order` value appear first and then other child nodes appear in the order of `updated_at` time.\n", "type": "integer" } } } } } } }, "node_children": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the child node. Must not match the node ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "description": "This represents the type of resource object being returned. Always `node`.", "type": "string", "enum": [ "node" ] } } } } } }, "node_parent": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the new parent node. Must not match the node ID specified in the request path.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "description": "This represents the type of resource object being returned. Always `node`.", "type": "string", "enum": [ "node" ] } } } } }, "node_products": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the product to be attached to the node.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "description": "This represents the type of resource object being returned. Always `product`.", "type": "string", "enum": [ "product" ] } } } } } }, "duplicate_job": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "type": { "description": "This represents the type of resource object being returned. Always `hierarchy`.", "type": "string", "enum": [ "hierarchy" ] }, "attributes": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The name of the duplicate hierarchy. The maximum length is 1000 characters.", "type": "string" }, "description": { "description": "A description of the duplicate hierarchy.", "type": "string" }, "slug": { "description": "The slug of the duplicate hierarchy. Must be lower case and use dashes instead of spaces.", "type": "string" }, "include_products": { "description": "Specify `true` if you want the product relationships in the existing nodes associated in your duplicated hierarchy. If not, specify `false`.", "type": "boolean" } } } } } } }, "tag": { "type": "object", "properties": { "id": { "description": "A unique identifier generated when a tag is created.", "type": "string" }, "type": { "description": "This represents the type of resource object being returned. Always `tag`.", "type": "string", "enum": [ "tag" ] }, "attributes": { "type": "object", "properties": { "value": { "type": "string", "description": "The text value of the tag." } } }, "meta": { "type": "object", "properties": { "x_request_id": { "type": "string", "description": "A unique request ID is generated when a tag is created." }, "created_at": { "type": "string", "description": "The date and time a tag is created.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The date and time a tag is updated.", "example": "2020-09-22T09:00:00.000Z", "format": "date-time" }, "owner": { "description": "The owner of a resource, either `organization` or `store`.", "type": "string", "enum": [ "store", "organization" ] } } } } }, "multi_tag": { "type": "object", "properties": { "data": { "description": "An array of tags.", "type": "array", "items": { "$ref": "#/components/schemas/tag" } }, "meta": { "type": "object", "properties": { "results": { "description": "Contains the results for the entire collection.", "type": "object", "properties": { "total": { "description": "Total number of results for the entire collection.", "type": "integer", "example": 2 } } } } } } }, "single_tag": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/tag" } } }, "create_custom_relationship": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `custom-relationship`.", "type": "string", "enum": [ "custom-relationship" ] }, "attributes": { "$ref": "#/components/schemas/req_attributes_custom_relationship" } } } } }, "single_custom_relationship": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/custom_relationship" } } }, "update_custom_relationship": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the custom relationship.", "example": "00000000-0000-0000-0000-000000000000" }, "type": { "description": "This represents the type of resource object being returned. Always `custom-relationship`.", "type": "string", "enum": [ "custom-relationship" ], "example": "custom-relationship" }, "attributes": { "$ref": "#/components/schemas/req_attributes_custom_relationship" } } } } } } }