Use product groups to create custom sets of products based on filters. Group product groups together on the Shop tab on the merchant's Pinterest profile, and promote them together as part of an ad campaign.
Create a product group and include a name and description for the product group, plus filters to define the products to include.
If the product group is associated with a feed, you can also provide a feed ID.
When you update a group, provide all details and the product group ID.
Note: None of these operations affect the items themselves, just the product groups.
Use to list product groups. GET /v5/catalogs/product_groups?feed_id={feed_id}&page_size=30
This returns a list of no more than 30 product groups since no bookmark value is provided, the list will begin at the beginning.
GET /v5/catalogs/product_groups?feed_id={feed_id}&page_size=30&bookmark={bookmark}
This returns the next set of up to 30 product groups that are part of the indicated feed.
Feed ID is a nullable query parameter. When applicable, it identifies the feed for which you will get the list of product groups.
Page size is an optional parameter that allows you to control that number of product groups that will be returned for this specific request.
Bookmark is a query parameter that can be used with any request after the first, a bookmark is included in each response, and if you include it in the subsequent request, the response you receive will begin where the prior response left off.
If there are no further product groups, the value for bookmark will be null.
{
"items": [
{
"id": "2680059592705",
"name": "Refurbished furniture",
"description": "Refurbished furniture -- like new, for less!",
"filters": {
"all_of": [
{
"CONDITION": {
"condition": "refurbished",
"negated": false
}
},
{
"GOOGLE_PRODUCT_CATEGORY_0": [["furniture"]]
}
]
},
"type": "MERCHANT_CREATED",
"status": "ACTIVE",
"feed_id": "string",
"created_at": 1621350033000,
"updated_at": 1622742155000
}
],
"bookmark": "string"
}
bookmark: The value to include in your next request so that the response will begin with the next product group
created_at: The Unix timestamp in milliseconds for the creation of the product group
description: A brief description of the product group
feed_id: The unique identifier for the feed this product group is part of
filters: Item filters used to create the product group
id: The ID for this product group
name: The name of the product group
status: Is an enum and can be either ACTIVE or INACTIVE
type: Product groups you create have the type enum value MERCHANT_CREATED. Pinterest will automatically create these additional types of product groups:
The value given for one of the request parameters is missing or does not exist.
The operating user_account does not have the required permissions to view the product group lists.
Use to create a new product group with items specified by filter. The product group is created based on the filter you create.
The filter consists of nested objects at the top level of the filter object. This indicates whether to return products that meet any of the listed filter criteria, or only products that meet all of the listed criteria.
The filters object includes an array of individual filter objects such as AVAILABILITY or PRODUCT_TYPE.
Filters object types are any_of or all_of.
The filter first defines whether you are filtering to select on all of the criteria, using all_of or any of the criteria, using any_of. You can only use one or the other of these filter types.
Using any_of, red, blue, green returns products that:
are solid red or red and other colors
solid blue or blue and other colors
or solid green or green and other colors
Using all_of, red, blue, green returns only products:
that are red and blue and green
returns products that are red, blue, green, and other colors
it will not return products that do not have all three of the listed colors
The all_of and any_of objects are containers that hold an array of individual filter objects. A filter object will include the name of the object, as in BRAND or AVAILABILITY and the value or values to select for under that filter.
Each filter object will include the object name and one or more values. For example,
the AVAILABILITY object will include the value, or values, to filter on
whether the items returned should be those that fit this filter negated:false
or those that do not fit this filter negated:true
Here is what a filter might look like if you want to include items that:
{
...
"filters":{
"all_of":[
{
"BRAND":{
"values":[
"Penguin",
"Prentice-Hall"
],
"negated":false
}
},
{
"AVAILABILITY":{
"values":[
"unavailable"
],
"negated":true
}
}
]
}
}
Note: The brand names listed in the BRAND filter are treated as or. The BRAND filter and the AVAILABILITY filter are treated as and because the filter type is given as all_of.
The filter objects that can be used include the following:
Use to filter items on minimum price.
inclusion is a boolean value to indicate whether to return products that are less than the price given (false) or that are equal to or less than the price given (true)
values is a numeric field representing the cut-off for determining if an item's price matches this filter or not
negated is a boolean value that determines whether products should be returned if they do (false) or do not (true) match this criterion.
The MIN_PRICE filter can only be used with the CURRENCY filter. Without a CURRENCY filter, the MIN_PRICE filter will not work.
inclusion is a boolean value that determines whether the filter should return products that are greater than the price given (false) or that are equal to or greater than the price given (true)
values is a numeric field representing the cut-off for determining if an item's price matches this filter or not
negated is a boolean value that determines whether products should be returned if they do (false) or do not (true) match this criterion.
Can only be used with the CURRENCY filter. Without a CURRENCY filter, this filter will not work.
The CURRENCY filter is required if you are using a price-based filter. Any product group can have only a single currency. Therefore, the CURRENCY filter object must appear in the array of filters at the same level as the price-based filter object(s). If both MIN_PRICE and MAX_PRICE filters are used, the CURRENCY filter provided will apply to them both. Note that the value for the CURRENCY filter cannot be negated.
Use to filter products on availability: IN_STOCK, OUT_OF_STOCK, PREORDER, or Unavailable the AVAILABILITY filter is negated, the request will return all items that do not have the indicated availability.
Filter on product condition: new, used, or refurbished.
To return products that are either new or refurbished, specify the condition with negated: false, or specify condition as in, used with negated: true.
Filter on item group ID. Provide the item_group_id(s) as a string or list of strings, such as item_group_1, or item_group_1, black_friday_100. If the ITEM_GROUP_ID filter is negated, the request will return only items that are not part of the indicated Item group(s).
CUSTOM_LABEL_0
CUSTOM_LABEL_1
CUSTOM_LABEL_2
CUSTOM_LABEL_3
CUSTOM_LABEL_4
Use a filter based on your own custom labels as given in the feed for your catalog.
So you can filter based on labels you created. You can have up to five such labels: custom_label_0, custom_label_1, custom_label_2, custom_label_3, and custom_label_4.
You can use any or all of these labels to create filters. This allows you to label items in your feed or to group them as you like.
If the filter for a custom label is negated, the request returns only items that do not have the given value(s) for the indicated custom_label.
There are two types of product categorization, if either or both is included in the data source for your feed, create filters based on them:
product_type, which is a custom field you define,
and google_product_category, which is the product category designated in Google's product category taxonomy (as reflected in the data source you provide)
Product type filters allow you to filter based on your own custom product types, as given in the feed for your catalog.
You can have up to 5 product type filters: PRODUCT_TYPE_FILTER_0, PRODUCT_TYPE_FILTER_1, PRODUCT_TYPE_FILTER_2, PRODUCT_TYPE_FILTER_3, and PRODUCT_TYPE_FILTER_4.
{
...
"PRODUCT_TYPE_FILTER_0":{
"values":[
[
"Accent Chairs > Club Chairs"
],
[
"Accent Chairs > Slipper Chairs"
]
],
"negated":false
...
}
}
This filter will return all items that are categorized under Accent Chairs as either Club Chairs or Slipper Chairs.
Google product category filters
With Google product category filters you can filter based on Google product categories. You can have up to 7 Google product category filters, numbered 0 through 6. (e.g. GOOGLE_PRODUCT_CATEGORY_0, GOOGLE_PRODUCT_CATEGORY_1, etc.)
{
...
"GOOGLE_PRODUCT_CATEGORY_0":{
"values":[
[
"furniture" -> "benches" -> "kitchen & dining benches"
],
[
"furniture" -> "sofa"
]
],
"negated":false
...
}
}
See here and, all_of filters by MAX_PRICE and CUSTOM_LABEL_3.
Returns all products with price < $20 and has a custom label of Mother's Day. If inclusion is set to true, this would return products with a price . {
"filters": {
"all_of": [
{
"MAX_PRICE": {
"inclusion": false,
"values": 20,
"negated": false
}
},
{
"CURRENCY": {
"values": "usd"
}
},
{
"CUSTOM_LABEL_3": {
"values": ["Mother's Day"],
"negated": false
}
}
]
}
}
See here the or, any_of filter by ITEM_ID or ITEM_GROUP_ID.
Returns all products included in item groups 1 and 7, and the products with specified item IDs.
If this were an and filter all_of, then only products with specified item IDs and that were part of item groups 1 and 7 would be returned.
{
"filters": {
"any_of": [
{
"ITEM_GROUP_ID": {
"values": ["`item_group_1`", "`item_group_7`"],
"negated": false
}
},
{
"ITEM_ID": {
"item_id": ["`DS0294-M`", "`DS02949-S`", "`DS0241-L`"],
"negated": false
}
}
]
}
}
When you create a new product group, include a name and description for the product group and whatever filters define the members of the product group. If the product group is associated with a particular feed, you can also include that feed_id.
Use to update a product group. Include the updates with the attributes:
{
"feed_id": "2680059592705",
"name": "Values Under $15",
"description": "Items priced to move! Nothing over $15!",
"filters": {
"all_of": [
{
"MAX_PRICE": {
"inclusion": true,
"values": 15,
"negated": false
}
},
{
"CURRENCY": {
"values": "usd"
}
}
]
}
}
{
"id": "443727193917",
"name": "Values Under $15",
"description": "Items priced to move! Nothing over $15!",
"filters": {
"all_of": [
{
"MAX_PRICE": {
"inclusion": true,
"values": 15,
"negated": false
}
},
{
"CURRENCY": {
"values": "usd"
}
}
]
},
"type": "MERCHANT_CREATED",
"status": "ACTIVE",
"feed_id": "2680059592705",
"created_at": 1621350033000,
"updated_at": 1622742155000
}
Product group is not found where the product_group_id given in the request does not exist.
There's a problem with one or more of the parameters, such as the MAX_PRICE or MIN_PRICE is not paired with CURRENCY, or you're using a filter that uses an enum but the value shown is not one of the valid enums.
There's an authorization issue where your authentication is invalid or there's a scope required for this activity that you don't have.
Use delete product group to delete an existing product group. The items underlying the product group will not be deleted.
DELETE v5/catalogs/product_groups/443727193917
204 -- Catalog product group deleted successfully.
Product group not found.
There is a conflict that prevents the product group from being deleted. For example, if the product group is part of an active campaign, it cannot be deleted.
Your authentication is invalid or there's a scope required for this action that you don't have.