Create and Manage Product Variations
Buy with Prime API is now available for early access
Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.
Products within your Buy with Prime catalog can have multiple variations. You can manage these variations by creating a VariationGroup. A VariationGroup consists of a representativeProduct that defines the base product and VariationGroupMember products for each variation. For example, if the representativeProduct is a shirt, the small, medium, and large sizes of the shirt might each be a VariationGroupMember.
The VariationSelection defines the difference between the VariationGroupMember and the representativeProduct using the dimension and value fields. For example, for a shirt a dimension might be size and the value might be medium. A VariationGroup can have multiple dimensions, for example the VariationSelection might also define a dimension of color with a value of red.
A product can only belong to one VariationGroup at a time and each VariationGroup can have a maximum of 200 VariationGroupMember products.
For details on creating and managing products, see Create and Manage Products in a Catalog.
Create a VariationGroupMember
Use the createProduct mutation to create a variation of a product by including variationGroupMembership in the mutation's input fields.
You create a VariationGroup when you assign the first VariationGroupMember under a representativeProduct. There is no separate action required for you to create the VariationGroup.
The following example creates a product within a VariationGroup with a VariationSelection that specifies that the size is large and the color is red.
Request
mutation CreateProduct {
createProduct(
input: {
externalId: "example-variation-externalId"
amazonSku: {
value: "example-product-amazon-sku"
}
sku: "example-product-sku"
offerPrime: true
productDetailPageUrl: "https://example.com/products/my-product"
image: {
sourceUrl: "https://example.com/products/my-product.jpg"
}
variationGroupMembership: {
representativeProductId: {
externalId: "t-shirt-model-42"
}
variationSelections: [
{
dimension: "color",
value: "red"
},
{
dimension: "size",
value: "large"
}
]
}
}
) {
id
}
}
Response
{
"data": {
"createProduct": {
"id": "abcdef01234567"
}
}
}
Add an existing product to a VariationGroup
Use the updateProduct mutation to add an existing product to a VariationGroup as a VariationGroupMember. As with creating a new product, if you add an existing product as a VariationGroupMember under a representativeProduct and a VariationGroup does not exist, adding the VariationGroupMember creates a new VariationGroup.
The following example adds an existing product to a VariationGroup with t-shirt-model-42 as the representativeProduct. As with the example shown in create a VariationGroupMember, the following example defines the VariationGroupMember with a VariationSelection that specifies that the size is large and the color is red.
Request
mutation UpdateProduct {
updateProduct(
identifier: {
externalId: "example-product-externalId"
}
input: {
variationGroupMembership: {
representativeProductId: {
externalId: "t-shirt-model-42"
}
variationSelections: [
{
dimension: "color",
value: "red"
},
{
dimension: "size",
value: "large"
}
]
}
}
) {
id
}
}
Response
{
"data": {
"updateProduct": {
"id": "abcdef01234567"
}
}
}
Update VariationSelection for an existing VariationGroupMember
Use the updateProduct mutation to update the VariationSelection for a VariationGroupMember. You can overwrite a dimension in the VariationSelection, add a new dimension, or both. The following example overwrites the color with green and adds a new dimension of type with the value big and tall.
Request
mutation UpdateProduct {
updateProduct(
identifier: {
externalId: "example-product-externalId"
}
input: {
variationGroupMembership: {
representativeProductId: {
externalId: "t-shirt-model-42"
}
variationSelections: [
{
dimension: "color",
value: "green"
},
{
dimension: "type",
value: "big and tall"
}
]
}
}
) {
id
}
}
Response
{
"data": {
"updateProduct": {
"id": "abcdef01234567"
}
}
}
Query products with VariationGroup values
The following examples show how you can query VariationGroup related products.
Query a product that is not in a VariationGroup, but that contains VariationGroup values
Request
query product {
product(identifier: { productId: "productId123" }) {
id
variationGroupMembership {
variationSelections {
dimension
value
}
productGroup {
representativeProduct {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
representativeOfVariationGroup {
members {
edges {
node {
variationSelections {
dimension
value
}
product {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
}
}
}
}
Response
{
"data": {
"product": {
"id": "productId123",
"variationGroupMembership": null,
"representativeOfVariationGroup": null
}
}
}
Query a representativeProduct
Request
query product {
product(identifier: { productId: "representativeProduct123" }) {
id
variationGroupMembership {
variationSelections {
dimension
value
}
productGroup {
representativeProduct {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
representativeOfVariationGroup {
members {
edges {
node {
variationSelections {
dimension
value
}
product {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
}
}
}
}
Response
{
"data": {
"product": {
"id": "representativeProduct123",
"variationGroupMembership": null,
"representativeOfVariationGroup": {
"members": {
"edges": [
{
"node": {
"variationSelections": [
{
"dimension": "Color",
"value": "Red"
}
],
"product": {
"id": "memberProduct123",
"externalId": {
"value": "member-1"
},
"sku": {
"value": "member-1"
},
"amazonSku": {
"marketplaceId": null,
"value": "member-1"
},
"externalVersion": null
}
}
}
]
}
}
}
}
}
Query a VariationGroupMember
Request
query product {
product(identifier: { productId: "memberProductId123" }) {
id
variationGroupMembership {
variationSelections {
dimension
value
}
productGroup {
representativeProduct {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
representativeOfVariationGroup {
members {
edges {
node {
variationSelections {
dimension
value
}
product {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
}
}
}
}
Response
{
"data": {
"product": {
"id": "memberProductId123",
"variationGroupMembership": {
"variationSelections": [
{
"dimension": "Color",
"value": "Red"
}
],
"productGroup": {
"representativeProduct": {
"id": "representativeProduct123",
"externalId": {
"value": "representative-1"
},
"sku": {
"value": "representative-1"
},
"amazonSku": {
"marketplaceId": null,
"value": "representative-1"
},
"externalVersion": null
}
}
},
"representativeOfVariationGroup": null
}
}
}
Remove a product from a VariationGroup
Use the updateProduct mutation to remove a product from a VariationGroup. Set the variationGroupMembership field to an empty object rather than setting the variationGroupMembership to null, which doesn't remove the product from the group.
The following example shows removing a product from a VariationGroup.
Request
mutation UpdateProduct {
updateProduct(
identifier: {
externalId: "example-member-externalId"
}
input: {
variationGroupMembership: {}
}
) {
id
}
}
Response
{
"data": {
"updateProduct": {
"id": "abcdef01234567"
}
}
}
Related topics
Updated 5 months ago