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.
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.
If the product you are updating is a member of another PurchaseGroup, you must include the representativeProduct of that PurchaseGroup in the purchaseGroupMemberships field of UpdateProductInput. If you exclude a representativeProduct when updating purchaseGroupMemberships, the update removes the product from the PurchaseGroup associated with that representativeProduct.
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"
}
}
}
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 16 days ago