openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses Variations API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
contact:
name: Elastic Path
url: https://www.elasticpath.com
email: support@elasticpath.com
license:
url: https://elasticpath.dev
name: MIT
servers:
- url: https://useast.api.elasticpath.com
description: US East
- url: https://euwest.api.elasticpath.com
description: EU West
security:
- BearerToken: []
tags:
- name: Variations
description: '```mdx-code-block
import VariationsOverview from ''/docs/partials/pxm/variations/variationsoverview.mdx'';
import VariationsReusability from ''/docs/partials/pxm/variations/variationsreusability.mdx'';
import ChildProducts from ''/docs/partials/pxm/variations/childproducts.mdx'';
import BuildChildren from ''/docs/partials/pxm/variations/buildchildproducts.mdx'';
import ProductModifiers from ''/docs/partials/pxm/variations/productmodifiers.mdx'';
import PriceModifiers from "/docs/partials/pxm/variations/pricemodifiers.mdx";
<VariationsOverview />
### Reusability
<VariationsReusability />
### Child Products
<ChildProducts />
### Building Child Products
<BuildChildren />
### Sorting the Order of Variations and Options
The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. The `variation_matrix` can then be added to your catalogs.
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. 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 variations and variation options in the order that you want.
Add the `sort_order` attribute to the body of your request and specify a `sort_order` value. A `sort_order` value must be a number. You can specify any numbers that you want.
- 1, 2, 3, or 100, 90, 80, and so on.
- 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.
:::caution
- Commerce does not sort variations and variation options. You must program your storefront to sort the variations and variation options in the order that you want.
- You must rebuild your products for the sort order changes to take effect. See [**Build Child Products**](#build-child-products).
:::
### Product Modifiers
<ProductModifiers />
### Price Modifiers
<PriceModifiers />
```
'
paths:
/pcm/products/{productID}/build:
post:
summary: Build child products
description: "With product variations in Product Experience Manager, you can create product variations and different options for each variation and use both to create child products for a product. Each child product is a unique combination of options associated with the product. \n\nChild products inherit attributes from their parent products. When you make changes to the attributes of the parent products, you can rebuild your child products, ensuring that changes to the parent products are propagated to the child products.\n\nAlternatively, you can modify a child product independently, without impacting its parent product. For example, you may prefer the status of your child product to be `live`, while keeping the parent product's status as `draft`. When you directly update a child product, it becomes independent of its parent product. In other words, any subsequent changes made to the parent product are not automatically reflected in the child product when you rebuild the parent product and its child products. Once a child product is independent of its parent, you cannot recreate the association between the child product and its parent. You must delete the child product and rebuild the parent to recreate the child product.\n\nFollowing on from that, if you add the same flow to both a parent and child product, the child flow values are not affected by changes to the parent flow values in a rebuild.\n\n### Using Build Rules\n\nWhen building your child products, you can build all products related to a product. \n\nAlternatively, 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. You can do this using `build_rules`. `build_rules` are combinations of variation option IDs that you wish to include or exclude when building your child products.\n\n:::note\n\nYou do not need to configure any `build_rules` in the following scenarios:\n\n- Child products must be built with all variation options. Simply, use the `Create a product` or `Update a product` endpoints with no `build_rules` specified.\n- Child products must be built apart from all options for a specific variation. In this case, you must remove the variation and use the `Create a product` or `Update a product` endpoints with no `build_rules` specified. In other words, using our example, if none of the `size` options should be included, then remove the `size` variation.\n\n:::\n\nThe `build_rules` contain:\n\n- (Required) `default`: specifies the default behavior.\n- (Optional) `include`: specifies the option IDs to include when the 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. See [**Invalid Build Rules**](#invalid-build-rules).\n- (Optional) `exclude`: specifies the option IDs to exclude when the 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. See [**Invalid build rules**](#invalid-build-rules).\n\nWhen building child products, Commerce compares each combination of option IDs to these rules to determine how your child products should be built, depending on how you have configured the `build_rules`. It depends on your requirements how you configure your `build_rules`.\n\n#### Invalid Build Rules\n\nThe `build_rules` are invalid if both the option IDs come from the same variation. Combinations of option IDs in the nested arrays must come from different variations.\n\nIf Commerce cannot resolve the `build_rules` a `could not determine whether to include or exclude a child product due to ambiguous rules` error is returned. This error can occur, for example, if you have the same number of variation option IDs in both the `include` and `exclude` arrays and the variation option IDs match.\n\n### Building Child Products\n\nBuilding child products is an asynchronous operation. When you build child products, a job is created. The jobId of the job is displayed in the response. When the job is complete, the build child products operation is also complete. You can use the jobId to see the status of your job using the `Get a Job` endpoint.\n\nJobs are processed one at a time. You can continue to send build child product requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See Jobs.\n\nRe-building child products after adding or removing a new variation changes the total number of child products that you can generate from a parent product. When you rebuild the child products after updating variations associated with the parent product, all existing child products that belong to a parent product are deleted. New child products are created with new product IDs.\n\nIf you have any bundles that reference child products directly, then you must update the bundles with the new child product IDs.\n\nHowever, re-building child products after adding or removing an option does not change the existing product IDs.\n"
operationId: buildChildProducts
tags:
- Variations
requestBody:
content:
application/json:
schema:
type: object
responses:
'201':
description: Successfully started building child products
content:
application/json:
schema:
$ref: '#/components/schemas/single'
examples:
build-child-products:
$ref: '#/components/examples/build-child-products_created'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
parameters:
- $ref: '#/components/parameters/product_id'
/pcm/products/{productID}/children:
get:
summary: Get child products
operationId: getChildProducts
tags:
- Variations
responses:
'200':
description: Returns a list of child products for the specified parent product ID.
content:
application/json:
schema:
$ref: '#/components/schemas/multi_product_response'
examples:
list-products:
$ref: '#/components/examples/multi_get_child_response'
'400':
$ref: '#/components/responses/bad_request'
'500':
$ref: '#/components/responses/internal'
parameters:
- $ref: '#/components/parameters/product_id'
/pcm/products/{productID}/relationships/variations:
post:
summary: Create a product variation relationship
operationId: createProductVariationRelationships
tags:
- Variations
parameters:
- $ref: '#/components/parameters/product_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/product_variations_request'
examples:
create-product-variation-relationship:
$ref: '#/components/examples/product_variations_relationship_request'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/bad_request'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/write_conflict'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
get:
summary: Get all product variation relationships
operationId: getProductVariationRelationships
tags:
- Variations
parameters:
- $ref: '#/components/parameters/product_id'
responses:
'200':
description: Returns all product variation relationships.
content:
application/json:
schema:
$ref: '#/components/schemas/variations_response'
examples:
product-variation-relationships:
$ref: '#/components/examples/variations_response'
'400':
$ref: '#/components/responses/bad_request'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/write_conflict'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
put:
summary: Replace a product variation relationship
operationId: updateProductVariationRelationships
tags:
- Variations
parameters:
- $ref: '#/components/parameters/product_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/product_variations_request'
examples:
replace-product-variation-relationship:
$ref: '#/components/examples/product_variations_relationship_request'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/bad_request'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/write_conflict'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
delete:
summary: Delete a product variation relationships
operationId: deleteProductVariationRelationships
tags:
- Variations
parameters:
- $ref: '#/components/parameters/product_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/product_variations_request'
examples:
delete-product-variation-relationships:
$ref: '#/components/examples/product_variations_relationship_request'
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/bad_request'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/write_conflict'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
/pcm/variations:
post:
summary: Create a variation
operationId: createVariation
tags:
- Variations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_variation'
examples:
create-variation:
summary: Create a variation
$ref: '#/components/examples/create_variation'
responses:
'201':
description: Returns a created variation with the following attributes.
content:
application/json:
schema:
$ref: '#/components/schemas/created_variation'
examples:
created-variation:
$ref: '#/components/examples/created_variation'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
get:
summary: Get all variations
operationId: getAllVariations
parameters:
- $ref: '#/components/parameters/page_offset'
- $ref: '#/components/parameters/page_limit'
tags:
- Variations
responses:
'200':
description: Returns all variations.
content:
application/json:
schema:
$ref: '#/components/schemas/multi_variations'
examples:
list-variations:
$ref: '#/components/examples/multi_variations'
'400':
$ref: '#/components/responses/bad_request'
'500':
$ref: '#/components/responses/internal'
/pcm/variations/{variationID}:
get:
summary: Get a variation
operationId: getVariation
parameters:
- $ref: '#/components/parameters/variation_id'
tags:
- Variations
responses:
'200':
description: Returns the specified variation.
content:
application/json:
schema:
$ref: '#/components/schemas/single_variation'
examples:
get-variation:
$ref: '#/components/examples/single_variation'
'400':
$ref: '#/components/responses/bad_request'
'404':
$ref: '#/components/responses/not_found'
'500':
$ref: '#/components/responses/internal'
put:
summary: Update a variation
description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the variation is not updated.
operationId: updateVariation
parameters:
- $ref: '#/components/parameters/variation_id'
tags:
- Variations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_variation'
examples:
update-variation:
$ref: '#/components/examples/update_variation'
responses:
'200':
description: Returns an updated variation with the following attributes.
content:
application/json:
schema:
$ref: '#/components/schemas/single_variation'
examples:
update-variation:
$ref: '#/components/examples/single_variation'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/write_conflict'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
delete:
summary: Delete a variation and all it's associated options.
operationId: deleteVariation
parameters:
- $ref: '#/components/parameters/variation_id'
tags:
- Variations
responses:
'204':
description: No Content
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
/pcm/variations/{variationID}/options:
post:
summary: Create a variation option
operationId: createVariationOption
parameters:
- $ref: '#/components/parameters/variation_id'
tags:
- Variations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_option'
examples:
create-variation-option:
$ref: '#/components/examples/create_option'
responses:
'201':
description: Successfully returns the created variation option.
content:
application/json:
schema:
$ref: '#/components/schemas/created_option'
examples:
created-variation-option:
$ref: '#/components/examples/created_option'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
get:
summary: Get all variation options
operationId: getAllVariationOptions
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/page_offset'
- $ref: '#/components/parameters/page_limit'
tags:
- Variations
responses:
'200':
description: Successfully returns all variation options.
content:
application/json:
schema:
$ref: '#/components/schemas/multi_options'
examples:
list-variations:
$ref: '#/components/examples/multi_options'
'400':
$ref: '#/components/responses/bad_request'
'500':
$ref: '#/components/responses/internal'
/pcm/variations/{variationID}/options/{optionID}:
get:
summary: Get a variation option
operationId: getVariationOption
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
tags:
- Variations
responses:
'200':
description: Successfully returns the variation option.
content:
application/json:
schema:
$ref: '#/components/schemas/single_option'
examples:
get-variation-option:
$ref: '#/components/examples/single_option'
'400':
$ref: '#/components/responses/bad_request'
'404':
$ref: '#/components/responses/not_found'
'500':
$ref: '#/components/responses/internal'
put:
summary: Update a variation option
operationId: updateVariationOption
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
tags:
- Variations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_option'
examples:
update-variation-option:
$ref: '#/components/examples/update_option'
responses:
'200':
description: Successfully returns the updated variation option
content:
application/json:
schema:
$ref: '#/components/schemas/single_option'
examples:
updated-variation-option:
$ref: '#/components/examples/single_option'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/write_conflict'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
delete:
summary: Delete a variation option
operationId: deleteVariationOption
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
tags:
- Variations
responses:
'204':
description: No Content
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
/pcm/variations/{variationID}/options/{optionID}/modifiers:
post:
summary: Create a modifier
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.\n \nThe 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"
operationId: createModifier
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
tags:
- Variations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_modifier'
examples:
create-variation-modifier:
$ref: '#/components/examples/create_modifier'
responses:
'201':
description: Successfully returns the created modifier
content:
application/json:
schema:
$ref: '#/components/schemas/created_modifier'
examples:
created-variation-modifier:
$ref: '#/components/examples/created_modifier'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
get:
summary: Get all modifiers
operationId: getAllModifiers
tags:
- Variations
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
- $ref: '#/components/parameters/page_offset'
- $ref: '#/components/parameters/page_limit'
responses:
'200':
description: Successfully returns all variation modifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/multi_modifiers'
examples:
list-variations:
$ref: '#/components/examples/multi_modifiers'
'400':
$ref: '#/components/responses/bad_request'
'500':
$ref: '#/components/responses/internal'
/pcm/variations/{variationID}/options/{optionID}/modifiers/{modifierID}:
get:
summary: Get a modifier
operationId: getModifier
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
- $ref: '#/components/parameters/modifier_id'
tags:
- Variations
responses:
'200':
description: Returns the specified modifier.
content:
application/json:
schema:
$ref: '#/components/schemas/single_modifier'
examples:
get-variation-modifier:
$ref: '#/components/examples/single_modifier'
'400':
$ref: '#/components/responses/bad_request'
'404':
$ref: '#/components/responses/not_found'
'500':
$ref: '#/components/responses/internal'
put:
summary: Update a modifier
description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the modifier is not updated.
operationId: updateModifier
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
- $ref: '#/components/parameters/modifier_id'
tags:
- Variations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_modifier'
examples:
update-variation-modifier:
$ref: '#/components/examples/update_modifier'
responses:
'200':
description: Successfully returns the updated modifier.
content:
application/json:
schema:
$ref: '#/components/schemas/single_modifier'
examples:
updated-variation-modifier:
$ref: '#/components/examples/single_modifier'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/write_conflict'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
delete:
summary: Delete a modifier
description: You cannot delete a modifier if it is in use. Deleting a modifier in us returns a `422 Failed Validation` error.
operationId: deleteModifier
parameters:
- $ref: '#/components/parameters/variation_id'
- $ref: '#/components/parameters/option_id'
- $ref: '#/components/parameters/modifier_id'
tags:
- Variations
responses:
'204':
description: No Content
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal'
components:
examples:
create_variation:
value:
data:
type: product-variation
attributes:
name: Paint Color
sort_order: 10
created_modifier:
value:
data:
type: product-variation-modifier
id: a510cddc-e946-4c22-9541-54626a7cf0ec
attributes:
seek: '{color}'
set: red
type: slug_builder
meta:
owner: store
variations_response:
value:
data:
- id: 43903bfa-5352-4a3d-9496-c9ab1229a175
type: product-variation
- id: 50f56ce9-9381-43f6-8a52-5369a8b42e52
type: product-variation
multi_get_child_response:
value:
data:
- type: product
id: 4d32b816-4397-4a71-b875-4e4ea3ce6745
attributes:
commodity_type: physical
name: Jeans
sku: jeansRed
slug: jeansRed
status: live
relationships:
base_product:
data:
type: product
id: 571e366f-17e6-4e51-8239-b3cc8ee1144d
children:
data: []
component_products:
data: []
li
# --- truncated at 32 KB (140 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-variations-api-openapi.yml