ad_account_id, 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 Business Access: 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 List product groups 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 ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Learn more'
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 ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Learn more
Note: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
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 ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Learn more'
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 ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Learn more
Note: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
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
- 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:
$ref: '#/components/schemas/CatalogsVerticalProductGroup'
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/{product_group_id}:
get:
x-ratelimit-category: catalogs_read
summary: Get single product group
description: 'Get a singe product group for a given Catalogs Product Group Id owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Learn more'
operationId: catalogs_product_groups/get
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_product_group_id'
- $ref: '#/components/parameters/query_ad_account_id'
security:
- pinterest_oauth2:
- catalogs:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogsVerticalProductGroup'
description: Success
'400':
description: Invalid catalogs product group id parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''product_group_id'' value ''11851494501_'' 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: 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 get a catalogs product group without an existing catalog.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsMerchantNotCreated:
value:
code: 4182
message: Can't acccess this feature without an existing catalog.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Product
delete:
x-ratelimit-category: catalogs_write
summary: Delete single product group
description: 'Delete a product group owned by the "operation user_account" from being in use in Catalogs.
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Learn more'
operationId: catalogs_product_groups/delete
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_product_group_id'
- $ref: '#/components/parameters/query_ad_account_id'
security:
- pinterest_oauth2:
- catalogs:write
responses:
'204':
description: Catalogs Product Group deleted successfully.
'400':
description: Invalid catalogs product group id parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''product_group_id'' value ''11851494501_'' 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: 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
patch:
x-ratelimit-category: catalogs_write
summary: Update single product group
description: 'Update product group owned by the "operation user_account" to use in Catalogs.
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Learn more
Note: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
If access is required, please contact your partner manager.'
operationId: catalogs_product_groups/update
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_product_group_id'
- $ref: '#/components/parameters/query_ad_account_id'
security:
- pinterest_oauth2:
- catalogs:write
requestBody:
description: Request object used to Update a catalogs product group.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CatalogsProductGroupUpdateRequest'
- $ref: '#/components/schemas/CatalogsVerticalProductGroupUpdateRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogsVerticalProductGroup'
description: Success
'400':
description: Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''product_group_id'' value ''11851494501_'' 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: 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 update this catalogs product group to this value.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CannotAlterAutoGeneratedCatalogsProductGroup:
value:
code: 4177
message: You cannot alter an auto generated catalogs product group.
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/{product_group_id}/product_counts:
get:
x-ratelimit-category: catalogs_read
summary: Get product counts for a Product Group
description: 'Get a product counts for a given Catalogs Product Group owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: This endpoint only supports RETAIL catalog at the moment.
Learn more'
operationId: catalogs_product_groups/product_counts_get
security:
- pinterest_oauth2:
- catalogs:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_product_group_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogsProductGroupProductCounts'
description: Success
'404':
description: 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: Can't access this feature without an existing catalog.
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
/catalogs/product_groups/{product_group_id}/products:
get:
x-ratelimit-category: catalogs_read
summary: List products for a Product Group
description: 'Get a list of product pins for a given Catalogs Product Group Id owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: This endpoint only supports RETAIL catalog at the moment.
Learn more'
operationId: catalogs_product_group_pins/list
security:
- pinterest_oauth2:
- boards:read
- catalogs:read
- pins:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/path_catalogs_product_group_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
description: Pins
items:
$ref: '#/components/schemas/CatalogsProduct'
description: Success
'400':
description: Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidRequest:
value:
code: 1
message: '''product_group_id'' value ''11851494501_'' 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.
'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.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Product
/catalogs/products/get_by_product_group_filters:
post:
x-ratelimit-category: catalogs_read
summary: List products for Product Group Filters
description: 'List products Pins owned by the "operation user_account" that meet the criteria specified in the Catalogs Product Group Filter given in the request.
- This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent.
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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 Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: This endpoint only supports RETAIL catalog at the moment.
Learn more'
operationId: products_by_product_group_filter/list
security:
- pinterest_oauth2:
- boards:read
- catalogs:read
- pins:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Object holding a group of filters for a catalog product group
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogsListProductsByFilterRequest'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
description: Pins
items:
$ref: '#/components/schemas/CatalogsProduct'
description: Success
'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.
'409':
description: Conflict. Can't get products.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsMerchantNotCreated:
value:
code: 4182
message: Can't acccess 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
components:
schemas:
CatalogsHotelProductGroupFiltersAllOf:
type: object
additionalProperties: false
properties:
all_of:
type: array
items:
type: object
$ref: '#/components/schemas/CatalogsHotelProductGroupFilterKeys'
required:
- all_of
CatalogsProductGroupCreateRequest:
type: object
title: retail feed based
description: Request object for creating a product group.
properties:
name:
type: string
description:
type: string
nullable: true
is_featured:
description: boolean indicator of whether the product group is being featured or not
type: boolean
default: false
filters:
$ref: '#/components/schemas/CatalogsProductGroupFiltersRequest'
feed_id:
description: Catalog Feed id pertaining to the catalog product group.
example: '2680059592705'
type: string
pattern: ^\d+$
required:
- name
- filters
- feed_id
EntityStatus:
type: string
description: Entity status
example: ACTIVE
enum:
- ACTIVE
- PAUSED
- ARCHIVED
- DRAFT
- DELETED_DRAFT
CatalogsHotelProductGroupFiltersAnyOf:
type: object
additionalProperties: false
properties:
any_of:
type: array
items:
type: object
$ref: '#/components/schemas/CatalogsHotelProductGroupFilterKeys'
required:
- any_of
ProductGroupPromotionCreateRequestElement:
type: object
title: ProductGroupPromotionCreateRequestElement
allOf:
- $ref: '#/components/schemas/ProductGroupPromotion'
- type: object
properties:
creative_type:
$ref: '#/components/schemas/CreativeType'
CatalogsProductMetadata:
type: object
description: Product metadata entity
properties:
item_id:
description: The user-created unique ID that represents the product.
example: DS0294-L
type: string
item_group_id:
description: The parent ID of the product.
example: DS0294
type: string
nullable: true
availability:
$ref: '#/components/schemas/NonNullableProductAvailabilityType'
price:
description: The price of the product.
example: 24.99
type: number
sale_price:
description: The discounted price of the product.
example: 14.99
type: number
nullable: true
currency:
$ref: '#/components/schemas/NonNullableCatalogsCurrency'
required:
- item_id
- item_group_id
- availability
- price
- sale_price
- currency
CatalogsProductGroupMultipleStringCriteria:
title: catalogs_product_group_multiple_string_criteria
type: object
additionalProperties: false
properties:
values:
type: array
items:
type: string
negated:
type: boolean
default: false
required:
- values
ProductType1Filter:
type: object
additionalProperties: false
properties:
PRODUCT_TYPE_1:
type: object
$ref: '#/components/schemas/CatalogsProductGroupMultipleStringListCriteria'
required:
- PRODUCT_TYPE_1
CustomLabel3Filter:
type: object
additionalProperties: false
properties:
CUSTOM_LABEL_3:
type: object
$ref: '#/components/schemas/CatalogsProductGroupMultipleStringCriteria'
required:
- CUSTOM_LABEL_3
GenderFilter:
type: object
additionalProperties: false
properties:
GENDER:
type: object
$ref: '#/components/schemas/CatalogsProductGroupMultipleGenderCriteria'
required:
- GENDER
CatalogsProductGroupCurrencyCriteria:
title: catalogs_product_group_currency_criteria
type: object
description: A currency filter. This filter cannot be negated
additionalProperties: false
properties:
values:
$ref: '#/components/schemas/NonNullableCatalogsCurrency'
negated:
type: boolean
default: false
enum:
- false
required:
- values
GoogleProductCategory4Filter:
type: object
additionalProperties: false
properties:
GOOGLE_PRODUCT_CATEGORY_4:
type: object
$ref: '#/components/schemas/CatalogsProductGroupMultipleStringListCriteria'
required:
- GOOGLE_PRODUCT_CATEGORY_4
NonNullableCatalogsCurrency:
type: string
description: Currency Codes from ISO 4217.
nullable: false
example: USD
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BTN
- BWP
- BYN
- BYR
- BZD
- CAD
- CDF
- CHF
- CLP
- CNY
- COP
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GGP
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- IMP
- INR
- IQD
- IRR
- ISK
- JEP
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SLL
- SOS
- SPL
- SRD
- STD
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TVD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VEF
- VND
- VUV
- WST
- XAF
- XCD
- XDR
- XOF
- XPF
- YER
- ZAR
- ZMW
- ZWD
CatalogsCreativeAssetsProductGroupCreateRequest:
type: object
title: creative_assets_product_groups_create_request
additionalProperties: false
description: Request object for creating a creative assets product group.
properties:
catalog_type:
type: string
enum:
- CREATIVE_ASSETS
name:
type: string
description:
type: string
nullable: true
filters:
$ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilters'
catalog_id:
description: Catalog id pertaining to the creative assets product group.
example: '2680059592705'
type: string
pattern: ^\d+$
required:
- name
- filters
- catalog_id
- catalog_type
Board:
title: Board
description: Board
type: object
properties:
id:
type: string
readOnly: true
example: '549755885175'
created_at:
type: string
description: Date and time of board creation.
readOnly: true
format: date-time
example: '2020-01-01T20:10:40-00:00'
board_pins_modified_at:
type: string
description: Date and time of last board pins modified.
readOnly: true
format: date-time
example: '2020-01-01T20:10:40-00:00'
name:
type: string
example: Summer Recipes
description:
type: string
nullable: true
example: My favorite summer recipes
collaborator_count:
type: integer
description: Count of collaborators on the board.
minimum: 0
readOnly: true
example: 17
pin_count:
type: integer
description: Count of pins on the board.
minimum: 0
readOnly: true
example: 5
follower_count:
type: integer
description: Board follower count.
readOnly: true
minimum: 0
example: 13
media:
type: object
readOnly: true
description: Board media.
properties:
image_cover_url:
type: string
nullable: true
description: Board cover image.
example: https://i.pinimg.com/400x300/fd/cd/d5/fdcdd5a6d8a80824add0d054125cd957.jpg
pin_thumbnail_urls:
type: array
description: Board pin thumbnail urls.
items:
type: string
example:
- https://i.pinimg.com/150x150/b4/57/10/b45710f1ede96af55230f4b43935c4af.jpg
- https://i.pinimg.com/150x150/dd/ff/46/ddff4616e39c1935cd05738794fa860e.jpg
- https://i.pinimg.com/150x150/84/ac/59/84ac59b670ccb5b903dace480a98930c.jpg
- https://i.pinimg.com/150x150/4c/54/6f/4c546f521be85e30838fb742bfff6936.jpg
owner:
allOf:
- $ref: '#/components/schemas/BoardOwner'
type: object
readOnly: true
privacy:
type: string
default: PUBLIC
description: Privacy setting for a board. Learn more about secret boards and protected boards
enum:
- PUBLIC
- PROTECTED
- SECRET
required:
- name
ProductType4Filter:
type: object
additionalProperties: false
properties:
PRODUCT_TYPE_4:
type: object
$ref: '#/components/schemas/CatalogsProductGroupMultipleStringListCriteria'
required:
- PRODUCT_TYPE_4
CatalogsProductGroupFilters:
description: Object holding a group of filters for a catalog product group
title: catalogs_product_group_filters
type: object
anyOf:
- $ref: '#/components/schemas/CatalogsProductGroupFiltersAnyOf'
- $ref: '#/components/schemas/CatalogsProductGroupFiltersAllOf'
PinMediaSourceImagesBase64:
title: Images Base64
description: Multiple Base64-encoded images media source
additionalProperties: false
properties:
source_type:
type: string
enum:
- multiple_image_base64
items:
items:
additionalProperties: false
properties:
title:
type: string
description:
type: string
link:
type: string
description: Destination link for the image.
content_type:
type: string
enum:
- image/jpeg
- image/png
data:
type: string
description: Image to upload as base64 string.
pattern: '[a-zA-Z0-9+\/=]+'
required:
- data
- content_type
type: object
minItems: 2
maxItems: 5
description: Array with image objects.
type: array
index:
type: integer
minimum: 0
required:
- items
type: object
ProductGroupReferenceFilter:
type: object
additionalProperties: false
properties:
PRODUCT_GROUP:
type: object
$ref: '#/components/schemas/CatalogsProductGroupMultipleStringCriteria'
required:
- PRODUCT_GROUP
CatalogsProductGroupFiltersAnyOf:
type: object
additionalProperties: false
properties:
any_of:
type: array
items:
type: object
$ref: '#/components/schemas/CatalogsProductGroupFilterKeys'
required:
- any_of
GoogleProductCategory6Filter:
type: object
additionalProperties: false
properties:
GOOGLE_PRODUCT_CATEGORY_6:
type: object
$ref: '#/components/schemas/CatalogsProductGroupMultipleStringListCriteria'
required:
- GOOGLE_PRODUCT_CATEGORY_6
CatalogsProductGroupType:
type: string
title: product_group_type
description: 'Catalog product group type
MERCHANT_CREATED: Product groups created by merchants.
ALL_PRODUCTS: Consists of every product in your latest successful feed upload.
BEST_DEALS: Consists of products with the deepest drop in price.
PINNER_FAVORITES: Consists of products that are resonating most with people on Pinterest, based on engagement.
TOP_SELLERS: Consists of products with the highest conversion rate, if you have the conversion tag installed.
BACK_IN_STOCK: Consists of products that were previously out of stock and are now in stock.
NEW_ARRIVALS: Consists of products that are new to your Catalog.
SHOPIFY_COLLECTION: Product groups created based on Shopify Product Collections.
I2PC: Product groups created based on predicted product category.