Create and Manage Purchase Groups
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.
A PurchaseGroup allows you to bundle products from your Buy with Prime catalog under a representativeProduct. When a shopper purchases the representativeProduct, the shopper receives a quantity of each PurchaseGroupMember.
The memberAmount of a PurchaseGroupMember defines the amount of the product a shopper receives using the unit and value fields. For example, you might assign a pair of socks as a PurchaseGroupMember with pair as the unit and three as the value. In this example, when the shopper purchases the representativeProduct, the shopper also receives three pairs of socks.
The price for a product purchased as part of a PurchaseGroup can differ from the price when purchased as an individual product. Set the price for a bundled product by updating price within the product's purchaseGroupMemberships. A product's price contains the currentPrice object, which includes the currencyCode and amount. The currencyCode value specifies the currency and the amount value sets the cost in that currency.
For details on creating and managing products, see Create and Manage Products in a Catalog.
Create a PurchaseGroup
Use the createPurchaseGroup mutation to create a new PurchaseGroup. You can choose an existing product as the representativeProduct, or create a new product by providing the details outlined in Create and Manage Products in a Catalog.
Create a PurchaseGroup with a new product as the representativeProduct
The following example creates a PurchaseGroup and a new product with an externalId of new-representative-product-external-id to be the representativeProduct.
Request
mutation createPurchaseGroup {
createPurchaseGroup(
input: {
representativeProduct:{
representativeProduct: {
amazonSku: {
value: "new-representative-product-amazon-sku"
}
sku:"new-representative-product-sku",
offerPrime: true,
externalId: "new-representative-product-external-id"
image: {
sourceUrl: "https://example.com/image-12345.jpg"
}
productDetailPageUrl: "https://www.amazon.com/dp/1234567"
}
},
members:[
{
product: {
sku: "purchase-group-member-1-sku"
},
memberAmount: {
value: 1,
unit: "UNIT"
}
},
{
product: {
sku: "purchase-group-member-2-sku"
},
memberAmount: {
value: 1,
unit: "UNIT"
}
}
]
}
) {
id
}
}
Response
{
"data": {
"createPurchaseGroup": {
"id": "01234567abcdef"
}
}
}
Create a PurchaseGroup with an existing product as the representativeProduct
The following example creates a new PurchaseGroup under an existing product with the ID existing-representative-product-sku. The new PurchaseGroup includes PurchaseGroupMember products with the IDs of purchase-group-member-1-sku and purchase-group-member-2-sku.
Request
mutation createPurchaseGroup {
createPurchaseGroup(
input: {
representativeProduct:{
representativeProductId: {
sku: "existing-representative-product-sku"
}
},
members:[
{
product: {
sku: "purchase-group-member-1-sku"
},
memberAmount: {
value: 1,
unit: "UNIT"
}
},
{
product: {
sku: "purchase-group-member-2-sku"
},
memberAmount: {
value: 1,
unit: "UNIT"
}
}
]
}
) {
id
}
}
Response
{
"data": {
"createPurchaseGroup": {
"id": "01234567abcdef"
}
}
}
Create a PurchaseGroupMember
Include purchaseGroupMemberships fields when using the createProduct mutation to add the new product to a PurchaseGroup. The following example creates a new product with an external ID of example-product-externalId that belongs to a PurchaseGroup with example-representative-externalId as the representativeProduct.
Request
mutation CreateProduct {
createProduct(
input: {
externalId: "example-product-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"
}
purchaseGroupMemberships: [
{
representativeProductId: {
externalId: "example-representative-externalId"
},
memberAmount: {
unit: "UNIT",
value: 3
}
}
]
}
) {
id
}
}
Response
{
"data": {
"createProduct": {
"id": "abcdef01234567"
}
}
}
Update the memberAmount of an existing PurchaseGroupMember
Use the updateProduct mutation to change the value field of memberAmount for a PurchaseGroupMember. The value dictates the amount of the PurchaseGroupMember product that a shopper receives when purchasing the group's representativeProduct.
When you update a product's purchaseGroupMemberships, you overwrite the previous purchaseGroupMemberships data. Include the representativeProduct of each PurchaseGroup in a product's current purchaseGroupMemberships when updating to avoid accidental removal from any PurchaseGroup.
The following example updates the product identified by purchase-group-member-sku with a new memberAmount of 10 units.
Request
mutation updateProduct {
updateProduct(
identifier: {
sku: "purchase-group-member-sku"
}
input: {
purchaseGroupMemberships: [
{
representativeProductId: {
sku: "representative-product-sku"
},
memberAmount: {
value: 10, // new value
unit: "UNIT"
}
}
]
}
) {
id
}
}
Response
{
"data": {
"updateProduct": {
"id": "abcdef01234567"
}
}
}
Update the price of an existing PurchaseGroupMember
Use the updateProduct mutation to update the price for a PurchaseGroupMember. You can't include a price in the purchaseGroupMemberships of a representativeProduct.
When you update a product's purchaseGroupMemberships, you overwrite the previous purchaseGroupMemberships data. Include the representativeProduct of each PurchaseGroup in a product's current purchaseGroupMemberships when updating to avoid accidental removal from any PurchaseGroup.
The following example updates the product identified by purchase-group-member-sku with a new price of 12.0 USD.
Request
mutation updateProduct {
updateProduct(
identifier: {
sku: "purchase-group-member-sku"
}
input: {
purchaseGroupMemberships: [
{
representativeProductId: {
sku: "representative-product-sku"
},
memberAmount: {
value: 10,
unit: "UNIT"
}
price: {
currentPrice: {
currencyCode: "USD"
amount: "12.0"
}
}
}
]
}
) {
id
}
}
Response
{
"data": {
"updateProduct": {
"id": "abcdef01234567"
}
}
}
Query products with PurchaseGroup values
The following examples show how you can query PurchaseGroup related products.
Query a product that is not in a PurchaseGroup, but that contains PurchaseGroup related values
PurchaseGroup, but that contains PurchaseGroup related valuesRequest
query product {
product(identifier: { productId: "product123" }) {
id
purchaseGroupMemberships {
memberAmount {
unit
value
}
productGroup {
representativeProduct {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
representativeOfPurchaseGroup {
members {
edges {
node {
memberAmount {
unit
value
}
product {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
}
}
}
}
Response
{
"data": {
"product": {
"id": "product123",
"purchaseGroupMemberships": null,
"representativeOfPurchaseGroup": null
}
}
}
Query a representativeProduct
Request
query product {
product(identifier: { productId: "representativeProduct123" }) {
id
purchaseGroupMemberships {
memberAmount {
unit
value
}
productGroup {
representativeProduct {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
representativeOfPurchaseGroup {
members {
edges {
node {
memberAmount {
unit
value
}
product {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
}
}
}
}
Response
{
"data": {
"product": {
"id": "representativeProduct123",
"purchaseGroupMemberships": null,
"representativeOfPurchaseGroup": {
"members": {
"edges": [
{
"node": {
"memberAmount": {
"unit": null,
"value": 2
},
"product": {
"id": "memberProduct123",
"externalId": {
"value": "123456"
},
"sku": {
"value": "sku 123456"
},
"amazonSku": {
"marketplaceId": null,
"value": "amazon sku 123456"
},
"externalVersion": null
}
}
}
]
}
}
}
}
}
Query a PurchaseGroupMember
Request
query product {
product(identifier: { productId: "memberProduct123" }) {
id
purchaseGroupMemberships {
memberAmount {
unit
value
}
productGroup {
representativeProduct {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
representativeOfPurchaseGroup {
members {
edges {
node {
memberAmount {
unit
value
}
product {
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
externalVersion
}
}
}
}
}
}
}
}
Response
{
"data": {
"product": {
"id": "memberProduct123",
"purchaseGroupMemberships": [
{
"memberAmount": {
"unit": null,
"value": 2
},
"productGroup": {
"representativeProduct": {
"id": "representativeProduct123",
"externalId": {
"value": "12345"
},
"sku": {
"value": "sku 12345"
},
"amazonSku": {
"marketplaceId": null,
"value": "amazon sku 12345"
},
"externalVersion": null
}
}
}
],
"representativeOfPurchaseGroup": null
}
}
}
Remove a product from a PurchaseGroup
Use the updateProduct mutation to remove a product from a PurchaseGroup. Set the purchaseGroupMembership field to an empty object rather than setting the purchaseGroupMembership to null, which doesn't remove the product from the group.
The following example shows removing a product from a PurchaseGroup.
Request
mutation updateProduct {
updateProduct(
identifier: {
sku: "purchase-group-member-sku"
}
input: {
purchaseGroupMemberships: []
}
) {
id
}
}
Response
{
"data": {
"updateProduct": {
"id": "abcdef01234567"
}
}
}
Related topics
Updated 12 days ago