Pinterest Product API
The Product API from Pinterest — 10 operation(s) for product.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Product API
description: This is the description of your API.
contact:
name: Pinterest, Inc.
url: https://developers.pinterest.com/
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Product
paths:
/ad_accounts/{ad_account_id}/product_group_promotions:
post:
description: Add one or more product groups from your catalog to an existing ad group. (Product groups added to an ad group are a 'product group promotion.')
operationId: product_group_promotions/create
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionCreateRequest'
description: List of Product Group Promotions to create, size limit [1, 30].
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Create product group promotions
tags:
- Product
patch:
description: Update multiple existing Product Group Promotions (by product_group_id)
operationId: product_group_promotions/update
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionUpdateRequest'
description: Parameters to update Product group promotions
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Update product group promotions
tags:
- Product
get:
description: 'List existing product group promotions associated with an ad account.
Include either ad_group_id or product_group_promotion_ids in your request.
<b>Note:</b> ad_group_ids and product_group_promotion_ids are mutually exclusive parameters.
Only provide one. If multiple options are provided, product_group_promotion_ids takes precedence over ad_group_ids. If none are provided, the endpoint returns an error.'
operationId: product_group_promotions/list
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_product_group_promotion_ids'
- $ref: '#/components/parameters/query_entity_statuses'
- $ref: '#/components/parameters/query_ad_group_id'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_order'
- $ref: '#/components/parameters/query_bookmark'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ProductGroupPromotionResponseItem'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Get product group promotions
tags:
- Product
/ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id}:
get:
description: Get a product group promotion by id
operationId: product_group_promotions/get
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/path_product_group_promotion_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Get a product group promotion by id
tags:
- Product
/ad_accounts/{ad_account_id}/product_groups/analytics:
get:
summary: Get product group analytics
description: 'Get analytics for the specified product groups in the specified <code>ad_account_id</code>, filtered by the specified options.
- The token''s user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a>: Admin, Analyst, Campaign Manager.
- If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days.
- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.'
operationId: product_groups/analytics
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_analytics
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_start_date'
- $ref: '#/components/parameters/query_end_date'
- $ref: '#/components/parameters/query_product_group_ids_required'
- $ref: '#/components/parameters/query_columns'
- $ref: '#/components/parameters/query_granularity'
- $ref: '#/components/parameters/query_conversion_attribution_click_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_view_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupAnalyticsResponse'
description: Success
'400':
description: Invalid ad account ads analytics parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad account ads analytics parameters.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Product
/ad_accounts/{ad_account_id}/product_groups/catalogs:
get:
deprecated: true
description: This endpoint is completely deprecated. Please use <a href='/docs/api/v5/#operation/catalogs_product_groups/list'>List product groups</a> from Catalogs API instead.
operationId: ad_accounts_catalogs_product_groups/list
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_feed_profile_id'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CatalogProductGroup'
description: Success
'400':
description: Invalid ad account ads parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad account ads parameters.
'401':
description: Access Denied. This can happen if account is not yet approved to operate as Merchant on Pinterest.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Merchant data not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
summary: Get catalog product groups
tags:
- Product
/catalogs/product_groups/multiple:
delete:
x-ratelimit-category: catalogs_write
summary: Delete multiple product groups
description: 'Delete product groups owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>'
operationId: catalogs_product_groups/delete_many
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_catalogs_product_group_ids_required'
- $ref: '#/components/parameters/query_ad_account_id'
security:
- pinterest_oauth2:
- catalogs:write
responses:
'204':
description: Catalogs Product Groups deleted successfully.
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
'403':
description: Forbidden. Account not approved for catalog product group mutations yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
MerchantUnderReview:
value:
code: 2626
message: Sorry, you cannot perform this action. Account is under review.
'404':
description: Catalogs product group not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsProductGroupNotFound:
value:
code: 4180
message: Sorry! We could not find your catalogs product group.
'409':
description: Conflict. Can't delete this catalogs product group.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsProductGroupHasActivePromotions:
value:
code: 4176
message: We can't delete a Catalogs Product Group with active promotions.
CannotAlterAutoGeneratedCatalogsProductGroup:
value:
code: 4177
message: You cannot alter an auto generated catalogs product group.
CatalogsMerchantNotCreated:
value:
code: 4182
message: Can't access this feature without an existing catalog.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Product
post:
x-ratelimit-category: catalogs_write
summary: Create multiple product group
description: 'Create product group to use in Catalogs owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>
Note: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.
If access is required, please contact your partner manager.'
operationId: catalogs_product_groups/create_many
security:
- pinterest_oauth2:
- catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Request object used to create one or more catalogs product groups.
required: true
content:
application/json:
schema:
type: array
title: multiple product groups
items:
oneOf:
- $ref: '#/components/schemas/CatalogsProductGroupCreateRequest'
- $ref: '#/components/schemas/CatalogsVerticalProductGroupCreateRequest'
examples:
RetailFewFiltersUsingAllOf:
summary: A simple retail example that applies "all of the following filters".
description: 'The use of "all_of" creates a Product Group where all of the individual filters
must be satisfied by a product to be included in the Product Group.
'
value:
- name: Few Filters using "all_of"
feed_id: '2680059592705'
featured: false
filters:
all_of:
- MIN_PRICE:
values: 999.99
inclusion: true
- CURRENCY:
values: USD
- CUSTOM_LABEL_0:
values:
- Luxury Items
RetailManyFiltersUsingAnyOf:
summary: A more complete retail example that applies "any of the following filters".
description: 'The use of "any_of" creates a Product Group where any of the individual filters
can add products to the Product Group independently.
'
value:
- name: Many Filters using "any_of"
featured: false
feed_id: '2680059592705'
filters:
all_of:
- MIN_PRICE:
values: 111.55
inclusion: false
negated: false
- CURRENCY:
values: USD
negated: false
- AVAILABILITY:
values:
- IN_STOCK
- OUT_OF_STOCK
- PREORDER
negated: false
- BRAND:
values:
- avanti
- beautyrest
negated: true
- GOOGLE_PRODUCT_CATEGORY_0:
values:
- - furniture
- tables
- accent tables
- end tables
- - furniture
- chairs
- slipper chairs
- - home & garden
negated: false
- CONDITION:
values:
- NEW
- REFURBISHED
- USED
negated: false
- CUSTOM_LABEL_0:
values:
- 004 - home furn leisure
negated: false
- CUSTOM_LABEL_1:
values:
- clearance
- original price
negated: false
- CUSTOM_LABEL_2:
values:
- 789 - table linens
- 794 - living room accents
negated: false
- GENDER:
values:
- FEMALE
- MALE
- UNISEX
negated: false
- ITEM_ID:
values:
- does not exists
- this one neither
- nope
negated: true
- ITEM_GROUP_ID:
values:
- nonexistant group
- another one
- last one
negated: true
- PRODUCT_TYPE_0:
values:
- - accent chairs
- club chairs
- - accent chairs
- slipper chairs
- - accent tables
- end tables
- - air mattresses
- air mattresses
- - table linens
negated: false
HotelFewFiltersUsingAllOf:
summary: A simple hotel example that applies "all of the following filters".
description: 'The use of "all_of" creates a Product Group where all of the individual filters
must be satisfied by a hotel to be included in the Product Group.
'
value:
- catalog_type: HOTEL
name: Few Filters using "all_of"
catalog_id: '4866935934774'
filters:
all_of:
- HOTEL_ID:
values:
- hotel1
- hotel2
- CUSTOM_LABEL_1:
values:
- big_hotels
negated: false
responses:
'201':
content:
application/json:
schema:
type: array
items:
description: ID of a created catalog product group.
example: '443727193917'
type: string
pattern: ^\d+$
description: Success
'400':
description: Invalid body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''feed_id'' value ''1511851494501_'' must match the pattern: ^\d+$"}'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
'403':
description: Forbidden. Account not approved for catalog product group mutations yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
MerchantUnderReview:
value:
code: 2626
message: Sorry, you cannot perform this action. Account is under review.
'409':
description: Conflict. Can't create this catalogs product group with this value.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsProductGroupFiltersAlreadyExist:
value:
code: 4178
message: A catalogs product group with these filters already exists for this feed.
CatalogsProductGroupNameAlreadyExist:
value:
code: 4179
message: A catalogs product group with this name already exists for this feed.
CatalogsMerchantNotCreated:
value:
code: 4182
message: Can't access this feature without an existing catalog.
CatalogsProductGroupFiltersInvalid:
value:
code: 4183
message: Catalog product group filters failed validation, please ensure all filters are set correctly.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Product
/catalogs/product_groups:
get:
x-ratelimit-category: catalogs_read
summary: List product groups
description: 'Get a list of product groups for a given Catalogs Feed Id owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>'
operationId: catalogs_product_groups/list
security:
- pinterest_oauth2:
- catalogs:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_catalogs_product_group_ids'
- $ref: '#/components/parameters/query_catalogs_feed_id'
- $ref: '#/components/parameters/query_catalogs_catalog_id'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CatalogsVerticalProductGroup'
description: Success
'400':
description: Invalid feed parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''feed_id'' value ''1511851494501_'' must match the pattern: ^\d+$"}'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
'403':
description: Forbidden. Account not approved for catalog product group mutations yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
MerchantUnderReview:
value:
code: 2626
message: Sorry, you cannot perform this action. Account is under review.
'404':
description: Data feed not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
FeedNotFound:
value:
code: 4161
message: Sorry! We could not find your catalogs feed.
'409':
description: Conflict. Can't create this catalogs product group with this value.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsMerchantNotCreated:
value:
code: 4182
message: Can't access this feature without an existing catalog.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Product
post:
x-ratelimit-category: catalogs_write
summary: Create single product group
description: 'Create product group to use in Catalogs owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>
Note: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.
If access is required, please contact your partner manager.'
operationId: catalogs_product_groups/create
security:
- pinterest_oauth2:
- catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Request object used to create a single catalogs product groups.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CatalogsProductGroupCreateRequest'
- $ref: '#/components/schemas/CatalogsVerticalProductGroupCreateRequest'
examples:
RetailFewFiltersUsingAllOf:
summary: A simple retail example that applies "all of the following filters".
description: 'The use of "all_of" creates a Product Group where all of the individual filters
must be satisfied by a product to be included in the Product Group.
'
value:
name: Few Filters using "all_of"
feed_id: '2680059592705'
featured: false
filters:
all_of:
- MIN_PRICE:
values: 999.99
inclusion: true
- CURRENCY:
values: USD
- CUSTOM_LABEL_0:
values:
- Luxury Items
RetailManyFiltersUsingAnyOf:
summary: A more complete retail example that applies "any of the following filters".
description: 'The use of "any_of" creates a Product Group where any of the individual filters
can add products to the Product Group independently.
'
value:
name: Many Filters using "any_of"
featured: false
feed_id: '2680059592705'
filters:
all_of:
- MIN_PRICE:
values: 111.55
inclusion: false
negated: false
- CURRENCY:
values: USD
negated: false
- AVAILABILITY:
values:
- IN_STOCK
- OUT_OF_STOCK
- PREORDER
negated: false
- BRAND:
values:
- avanti
- beautyrest
negated: true
- GOOGLE_PRODUCT_CATEGORY_0:
values:
- - furniture
- tables
- accent tables
- end tables
- - furniture
- chairs
- slipper chairs
- - home & garden
negated: false
- CONDITION:
values:
- NEW
- REFURBISHED
- USED
negated: false
- CUSTOM_LABEL_0:
values:
- 004 - home furn leisure
negated: false
- CUSTOM_LABEL_1:
values:
- clearance
- original price
negated: false
- CUSTOM_LABEL_2:
values:
- 789 - table linens
-
# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinterest/refs/heads/main/openapi/pinterest-product-api-openapi.yml