ad_account_id, filtered by the specified options.\n- 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.\n- 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.\n- 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.",
+ "description": "Get analytics for the specified ads in the specified ad_account_id, filtered by the specified options.\n- 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.\n- The request must contain either ad_ids or both campaign_ids and pin_ids.\n- 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.\n- 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": "ads/analytics",
"security": [
{
@@ -1223,7 +1222,7 @@
"$ref": "#/components/parameters/query_end_date"
},
{
- "$ref": "#/components/parameters/query_ad_ids_required"
+ "$ref": "#/components/parameters/query_ad_ids"
},
{
"$ref": "#/components/parameters/query_columns"
@@ -1242,6 +1241,24 @@
},
{
"$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time"
+ },
+ {
+ "name": "pin_ids",
+ "description": "List of Pin IDs.",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "minItems": 1,
+ "maxItems": 100
+ }
+ },
+ {
+ "$ref": "#/components/parameters/query_campaign_ids"
}
],
"responses": {
@@ -1288,7 +1305,7 @@
"/ad_accounts/{ad_account_id}/ads_credit/discounts": {
"get": {
"summary": "Get ads credit discounts",
- "description": "Returns the list of discounts applied to the account.\n\nThis endpoint might not be available to all apps. Learn more.",
+ "description": "Returns the list of discounts applied to the account.\n\nThis endpoint might not be available to all apps. Learn more.",
"operationId": "ads_credits_discounts/get",
"security": [
{
@@ -1356,7 +1373,7 @@
"/ad_accounts/{ad_account_id}/ads_credit/redeem": {
"post": {
"summary": "Redeem ad credits",
- "description": "Redeem ads credit on behalf of the ad account id and apply it towards billing.\n\nThis endpoint might not be available to all apps. Learn more.",
+ "description": "Redeem ads credit on behalf of the ad account id and apply it towards billing.\n\nThis endpoint might not be available to all apps. Learn more.",
"tags": [
"billing"
],
@@ -1457,7 +1474,7 @@
"$ref": "#/components/parameters/query_end_date"
},
{
- "$ref": "#/components/parameters/query_targeting_types"
+ "$ref": "#/components/parameters/query_ad_targeting_types"
},
{
"$ref": "#/components/parameters/query_columns"
@@ -1511,7 +1528,7 @@
"/ad_accounts/{ad_account_id}/ads/{ad_id}": {
"get": {
"summary": "Get ad",
- "description": "Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will\ncontain additional information from the Ad Review process.\nFor more information about our policies and rejection reasons see the Pinterest advertising standards.",
+ "description": "Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will\ncontain additional information from the Ad Review process.\nFor more information about our policies and rejection reasons see the Pinterest advertising standards.",
"operationId": "ads/get",
"security": [
{
@@ -1729,7 +1746,7 @@
"$ref": "#/components/parameters/query_page_size"
},
{
- "description": "This feature is currently in beta and not available to all apps.\nFilter audiences by ownership type.",
+ "description": "Filter audiences by ownership type.",
"in": "query",
"name": "ownership_type",
"required": false,
@@ -2028,6 +2045,243 @@
]
}
},
+ "/ad_accounts/{ad_account_id}/audiences/shared/accounts": {
+ "get": {
+ "summary": "List accounts with access to an audience owned by an ad account",
+ "description": "List all ad accounts and/or businesses that have access to a specific audience. The audience must be owned by the requesting ad account.",
+ "operationId": "ad_accounts_audiences_shared_accounts/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_audience_id"
+ },
+ {
+ "$ref": "#/components/parameters/query_account_type"
+ },
+ {
+ "$ref": "#/components/parameters/query_page_size"
+ },
+ {
+ "$ref": "#/components/parameters/query_bookmark"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/Paginated"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "items": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SharedAudienceAccount"
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid ad account audiences shared accounts parameters.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "example": {
+ "code": 400,
+ "message": "Invalid ad account audiences shared accounts parameters."
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Shared accounts not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "Unexpected error.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ },
+ "tags": [
+ "audience_sharing"
+ ]
+ }
+ },
+ "/ad_accounts/{ad_account_id}/audiences/ad_accounts/shared": {
+ "patch": {
+ "summary": "Update audience sharing between ad accounts",
+ "description": "From an ad account, share a specific audience with another ad account, or revoke access to a previously shared audience. Only the audience owner account can share the audience. The recipient ad account(s) must be in the same Pinterest Business Hierarchy as the business owner of the ad account.Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’ s profile.
\nEquivalency equations, using dollars as an example currency:
\nTo convert between currency and microcurrency, using dollars as an example currency:
\nCreate a customer list from your records(hashed or plain-text email addresses, or hashed MAIDs or IDFAs).
\nA customer list is one of the four types of Pinterest audiences: for more information, see Audience targeting\nor the Audiences section of the ads management guide.
\nPlease review our requirements for what type of information is allowed when uploading a customer list.
\nWhen you create a customer list, the system scans the list for existing Pinterest accounts;\nthe list must include at least 100 Pinterest accounts. Your original list will be deleted when the matching process\nis complete. The filtered list – containing only the Pinterest accounts that were included in your starting\nlist – is what will be used to create the audience.
\nNote that once you have created your customer list, you must convert it into an audience (of the “ CUSTOMER_LIST” type)\nusing the create audience endpoint before it can be used.
", + "description": "Create a customer list from your records(hashed or plain-text email addresses, or hashed MAIDs or IDFAs).
\nA customer list is one of the four types of Pinterest audiences: for more information, see Audience targeting\nor the Audiences section of the ads management guide.
\nPlease review our requirements for what type of information is allowed when uploading a customer list.
\nWhen you create a customer list, the system scans the list for existing Pinterest accounts;\nthe list must include at least 100 Pinterest accounts. Your original list will be deleted when the matching process\nis complete. The filtered list – containing only the Pinterest accounts that were included in your starting\nlist – is what will be used to create the audience.
\nNote that once you have created your customer list, you must convert it into an audience (of the “ CUSTOMER_LIST” type)\nusing the create audience endpoint before it can be used.
", "operationId": "customer_lists/create", "security": [ { @@ -3079,7 +3333,7 @@ ] }, "get": { - "description": "Get a set of customer lists including id and name based on the filters provided.
\n(Customer lists are a type of audience.) For more information, see\nAudience targeting\n or the Audiences\nsection of the ads management guide.
", + "description": "Get a set of customer lists including id and name based on the filters provided.
\n(Customer lists are a type of audience.) For more information, see\nAudience targeting\n or the Audiences\nsection of the ads management guide.
", "operationId": "customer_lists/list", "security": [ { @@ -3196,7 +3450,7 @@ ] }, "patch": { - "description": "Append or remove records to/from an existing customer list. (A customer list is one of the four types of Pinterest audiences.)
\nWhen you add records to an existing customer list, the system scans the additions for existing Pinterest\naccounts; those are the records that will be added to your “CUSTOMER_LIST” audience. Your original list of records\n to add will be deleted when the matching process is complete.
\nFor more information, see Audience targeting\nor the Audiences\nsection of the ads management guide.
", + "description": "Append or remove records to/from an existing customer list. (A customer list is one of the four types of Pinterest audiences.)
\nWhen you add records to an existing customer list, the system scans the additions for existing Pinterest\naccounts; those are the records that will be added to your “CUSTOMER_LIST” audience. Your original list of records\n to add will be deleted when the matching process is complete.
\nFor more information, see Audience targeting\nor the Audiences\nsection of the ads management guide.
", "operationId": "customer_lists/update", "security": [ { @@ -3256,7 +3510,7 @@ "/ad_accounts/{ad_account_id}/events": { "post": { "summary": "Send conversions", - "description": "The Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline conversions) based on theirad_account_id. The request body should be a JSON object.\n- This endpoint requires an access_token be generated through Ads Manager. Review the Conversions Guide for more details.\n- 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, Audience, Campaign. (Note that the token can be used across multiple ad accounts under an user ID.)\n- This endpoint has a rate limit of 5,000 calls per minute per ad account.\n- If the merchant is submitting this information using both Pinterest conversion tags and the Pinterest API, Pinterest will remove duplicate information before reporting. (Note that events that took place offline cannot be deduplicated.)",
+ "description": "The Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline conversions) based on their ad_account_id. The request body should be a JSON object.\n- This endpoint requires an access_token be generated through Ads Manager. Review the Conversions Guide for more details. (Note that the authorization header required is Authorization: Bearer <access_token>).\n- 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, Audience, Campaign. (Note that the token can be used across multiple ad accounts under an user ID.)\n- This endpoint has a rate limit of 5,000 calls per minute per ad account.\n- If the merchant is submitting this information using both Pinterest conversion tags and the Pinterest API, Pinterest will remove duplicate information before reporting. (Note that events that took place offline cannot be deduplicated.)",
"operationId": "events/create",
"tags": [
"conversion_events"
@@ -3459,7 +3713,7 @@
"/ad_accounts/{ad_account_id}/keywords": {
"get": {
"summary": "Get keywords",
- "description": "Get a list of keywords based on the filters provided. If no filter is provided, it will default to the ad_account_id filter, which means it will only return keywords that specifically have parent_id set to the ad_account_id. Note: Keywords can have ad_account_ids, campaign_ids, and ad_group_ids set as their parent_ids. Keywords created through Ads Manager will have their parent_id set to an ad_group_id, not ad_account_id.
\nFor more information, see Keyword targeting.
\nNotes:
For more information on match types, see match type enums.
\nReturns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ \"keywords\": [], \"errors\": [ { \"data\": { \"archived\": null, \"match_type\": \"EXACT\", \"parent_type\": null, \"value\": \"foobar\", \"parent_id\": null, \"type\": \"keyword\", \"id\": null }, \"error_messages\": [ \"Advertisers and Campaigns only accept excluded targeting attributes.\" ] } } Get a list of keywords based on the filters provided. If no filter is provided, it will default to the ad_account_id filter, which means it will only return keywords that specifically have parent_id set to the ad_account_id. Note: Keywords can have ad_account_ids, campaign_ids, and ad_group_ids set as their parent_ids. Keywords created through Ads Manager will have their parent_id set to an ad_group_id, not ad_account_id.
\nFor more information, see Keyword targeting.
\nNotes:
For more information on match types, see match type enums.
\nReturns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ \"keywords\": [], \"errors\": [ { \"data\": { \"archived\": null, \"match_type\": \"EXACT\", \"parent_type\": null, \"value\": \"foobar\", \"parent_id\": null, \"type\": \"keyword\", \"id\": null }, \"error_messages\": [ \"Advertisers and Campaigns only accept excluded targeting attributes.\" ] } } Create keywords for following entity types(advertiser, campaign, ad group or ad).
For more information, see Keyword targeting.
\nNotes:
For more information on match types, see match type enums.
\nReturns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ \"keywords\": [], \"errors\": [ { \"data\": { \"archived\": null, \"match_type\": \"EXACT\", \"parent_type\": null, \"value\": \"foobar\", \"parent_id\": null, \"type\": \"keyword\", \"id\": null }, \"error_messages\": [ \"Advertisers and Campaigns only accept excluded targeting attributes.\" ] } } Rate limit: WRITE.
", + "description": "Create keywords for following entity types(advertiser, campaign, ad group or ad).
For more information, see Keyword targeting.
\nNotes:
For more information on match types, see match type enums.
\nReturns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ \"keywords\": [], \"errors\": [ { \"data\": { \"archived\": null, \"match_type\": \"EXACT\", \"parent_type\": null, \"value\": \"foobar\", \"parent_id\": null, \"type\": \"keyword\", \"id\": null }, \"error_messages\": [ \"Advertisers and Campaigns only accept excluded targeting attributes.\" ] } } Rate limit: WRITE.
", "operationId": "keywords/create", "security": [ { @@ -3694,8 +3948,8 @@ }, "/ad_accounts/{ad_account_id}/lead_forms": { "get": { - "summary": "Get lead forms", - "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nGets all Lead Forms associated with an ad account ID.\n\nFor more, see Lead ads.", + "summary": "List lead forms", + "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nList lead forms associated with an ad account ID.\n\nFor more, see Lead ads.", "operationId": "lead_forms/list", "security": [ { @@ -3774,6 +4028,154 @@ "tags": [ "lead_forms" ] + }, + "post": { + "x-sandbox": "disabled", + "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nCreate lead forms. Lead forms are used in lead ads and allow you to control what text appears on the lead form’ s description, questions and confirmation sections.\n\nFor more, see Lead ads.", + "summary": "Create lead forms", + "operationId": "lead_forms/create", + "security": [ + { + "pinterest_oauth2": [ + "ads:write" + ] + } + ], + "x-ratelimit-category": "ads_write", + "parameters": [ + { + "$ref": "#/components/parameters/path_ad_account_id" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/LeadFormCreateRequest" + }, + "maxItems": 30, + "minItems": 1, + "type": "array" + } + } + }, + "description": "List of lead forms to create, size limit [1, 30].", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LeadFormArrayResponse" + } + } + }, + "description": "Success" + }, + "400": { + "description": "Invalid ad account lead forms parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "code": 400, + "message": "Invalid ad account lead forms parameters." + } + } + } + }, + "default": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "tags": [ + "lead_forms" + ] + }, + "patch": { + "x-sandbox": "disabled", + "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nUpdate lead forms. Lead ads help you reach people who are actively looking for, and interested in, your goods and services. The lead form can be associated with an ad to allow people to fill out the form.\n\nFor more, see Lead ads.", + "summary": "Update lead forms", + "operationId": "lead_forms/update", + "security": [ + { + "pinterest_oauth2": [ + "ads:write" + ] + } + ], + "x-ratelimit-category": "ads_write", + "parameters": [ + { + "$ref": "#/components/parameters/path_ad_account_id" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/LeadFormUpdateRequest" + }, + "maxItems": 30, + "minItems": 1, + "type": "array" + } + } + }, + "description": "List of lead forms to update, size limit [1, 30].", + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LeadFormArrayResponse" + } + } + }, + "description": "Success" + }, + "400": { + "description": "Invalid ad account lead forms parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "code": 400, + "message": "Invalid ad account lead forms parameters." + } + } + } + }, + "default": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "tags": [ + "lead_forms" + ] } }, "/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}": { @@ -3856,7 +4258,7 @@ "/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}/test": { "post": { "summary": "Create lead form test data", - "description": "Create lead form test data based on the list of answers provided as part of the body.\n- List of answers should follow the questions creation order.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", + "description": "Create lead form test data based on the list of answers provided as part of the body.\n- List of answers should follow the questions creation order.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "lead_form_test/create", "security": [ { @@ -3944,7 +4346,7 @@ "/ad_accounts/{ad_account_id}/leads/subscriptions": { "post": { "summary": "Create lead ads subscription", - "description": "Create a lead ads webhook subscription.\nSubscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can exist for a specific lead form or at ad account level. \n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n- Advertisers can set up multiple integrations using ad_account_id + lead_form_id but only one integration per unique records.\n- For data security, egress lead data is encrypted with AES-256-GCM.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", + "description": "Create a lead ads webhook subscription.\nSubscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can exist for a specific lead form or at ad account level.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n- Advertisers can set up multiple integrations using ad_account_id + lead_form_id but only one integration per unique records.\n- For data security, egress lead data is encrypted with AES-256-GCM.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "tags": [ "lead_ads" ], @@ -4031,7 +4433,7 @@ }, "get": { "summary": "Get lead ads subscriptions", - "description": "Get the advertiser's list of lead ads subscriptions.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", + "description": "Get the advertiser's list of lead ads subscriptions.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "ad_accounts_subscriptions/get_list", "security": [ { @@ -4116,7 +4518,7 @@ "/ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id}": { "get": { "summary": "Get lead ads subscription", - "description": "Get a specific lead ads subscription record.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", + "description": "Get a specific lead ads subscription record.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "ad_accounts_subscriptions/get_by_id", "security": [ { @@ -4213,7 +4615,7 @@ }, "delete": { "summary": "Delete lead ads subscription", - "description": "Delete an existing lead ads webhook subscription by ID.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", + "description": "Delete an existing lead ads webhook subscription by ID.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "ad_accounts_subscriptions/del_by_id", "security": [ { @@ -4302,6 +4704,161 @@ ] } }, + "/ad_accounts/{ad_account_id}/leads_export": { + "post": { + "x-sandbox": "disabled", + "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nCreate an export of leads collected from a lead ad. This returns a lead_export_id token that you can use to download the export when it is ready.\n\nNote: Lead ad data will be available up to 30 days after the lead has been submitted.\n\nFor more, see Lead ads.", + "summary": "Create a request to export leads collected from a lead ad", + "operationId": "leads_export/create", + "security": [ + { + "pinterest_oauth2": [ + "ads:write" + ] + } + ], + "x-ratelimit-category": "ads_write", + "parameters": [ + { + "$ref": "#/components/parameters/path_ad_account_id" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LeadsExportCreateRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LeadsExportCreateResponse" + } + } + }, + "description": "Success" + }, + "400": { + "description": "Invalid ad account parameter.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "code": 400, + "message": "Invalid ad account parameter." + } + } + } + }, + "default": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "tags": [ + "leads_export" + ] + } + }, + "/ad_accounts/{ad_account_id}/leads_export/{leads_export_id}": { + "get": { + "x-sandbox": "disabled", + "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nGet the export of leads collected from a lead ad. This returns a URL to a list of lead export given a lead_export_id token returned from the create a lead export call. You can use the URL to download the report.\n\nNote: Lead ad data will be available up to 30 days after the lead has been submitted.\n\nFor more, see Lead ads.", + "summary": "Get the lead export from the lead export create call", + "operationId": "leads_export/get", + "security": [ + { + "pinterest_oauth2": [ + "ads:read" + ] + } + ], + "x-ratelimit-category": "ads_read", + "parameters": [ + { + "$ref": "#/components/parameters/path_ad_account_id" + }, + { + "name": "leads_export_id", + "in": "path", + "description": "lead_export_id token returned from the create a lead export endpoint", + "example": "123755885175", + "required": true, + "schema": { + "type": "string", + "pattern": "^\\d+$" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LeadsExportResponseData" + } + } + }, + "description": "Success" + }, + "400": { + "description": "Invalid ad account parameter.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "code": 400, + "message": "Invalid ad account parameter." + } + } + } + }, + "404": { + "description": "Invalid leads export id parameter.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "code": 404, + "message": "Invalid leads export id parameter." + } + } + } + }, + "default": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "tags": [ + "leads_export" + ] + } + }, "/ad_accounts/{ad_account_id}/mmm_reports": { "get": { "summary": "Get advertiser Marketing Mix Modeling (MMM) report.", @@ -4877,26 +5434,26 @@ ] } }, - "/ad_accounts/{ad_account_id}/product_groups/catalogs": { + "/ad_accounts/{ad_account_id}/reports": { "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", + "summary": "Get the account analytics report created by the async call", + "description": "This returns a URL to an analytics report given a token returned from the post request report creation call. You can use the URL to download the report. The link is valid for five minutes and the report is valid for one hour.\n- 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.", + "operationId": "analytics/get_report", "security": [ { "pinterest_oauth2": [ - "ads:write" + "ads:read" ] } ], - "x-ratelimit-category": "ads_write", + "x-ratelimit-category": "ads_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { - "$ref": "#/components/parameters/query_feed_profile_id" + "$ref": "#/components/parameters/query_token_required" } ], "responses": { @@ -4904,29 +5461,14 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Paginated" - }, - { - "type": "object", - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CatalogProductGroup" - } - } - } - } - ] + "$ref": "#/components/schemas/AdsAnalyticsGetAsyncResponse" } } }, "description": "Success" }, "400": { - "description": "Invalid ad account ads parameters.", + "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { @@ -4934,27 +5476,136 @@ }, "example": { "code": 400, - "message": "Invalid ad account ads parameters." + "message": "Invalid ad account ads analytics parameters." } } } }, - "401": { - "description": "Access Denied. This can happen if account is not yet approved to operate as Merchant on Pinterest.", + "default": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "tags": [ + "ad_accounts" + ] + }, + "post": { + "summary": "Create async request for an account analytics report", + "description": "This returns a token that you can use to download the report when it is ready. Note that this endpoint requires the parameters to be passed as JSON-formatted in the request body. This endpoint does not support URL query parameters.\n- 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.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- 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.\n- If level is PRODUCT_ITEM, the furthest back you can are allowed to pull data is 92 days before the current date in UTC time and the max time range supported is 31 days.\n- If level is PRODUCT_ITEM, ad_ids and ad_statuses parameters are not allowed. Any columns related to pin promotion and ad is not allowed either.", + "operationId": "analytics/create_report", + "security": [ + { + "pinterest_oauth2": [ + "ads:read" + ] + } + ], + "x-ratelimit-category": "ads_analytics", + "x-sandbox": "disabled", + "parameters": [ + { + "$ref": "#/components/parameters/path_ad_account_id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdsAnalyticsCreateAsyncRequest" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdsAnalyticsCreateAsyncResponse" + } + } + }, + "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." } } } }, - "404": { - "description": "Merchant data not found.", + "default": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "tags": [ + "ad_accounts" + ] + } + }, + "/ad_accounts/{ad_account_id}/sandbox": { + "delete": { + "summary": "Delete ads data for ad account in API Sandbox", + "description": "Delete an ad account and all the ads data associated with that account.\nA string message is returned indicating the status of the delete operation.\n\nNote: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5).\nGo to /docs/developer-tools/sandbox/ for more information.", + "operationId": "sandbox/delete", + "security": [ + { + "pinterest_oauth2": [ + "ads:write" + ] + } + ], + "x-ratelimit-category": "ads_write", + "x-sandbox": "enabled", + "parameters": [ + { + "$ref": "#/components/parameters/path_ad_account_id" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": "Delete Success" + } + } + } + }, + "400": { + "description": "Invalid ad account id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" + }, + "example": { + "code": 400, + "message": "Invalid ad account id" } } } @@ -4970,17 +5621,16 @@ } } }, - "summary": "Get catalog product groups", "tags": [ - "product_groups" + "ad_accounts" ] } }, - "/ad_accounts/{ad_account_id}/reports": { + "/ad_accounts/{ad_account_id}/ssio/accounts": { "get": { - "summary": "Get the account analytics report created by the async call", - "description": "This returns a URL to an analytics report given a token returned from the post request report creation call. You can use the URL to download the report. The link is valid for five minutes and the report is valid for one hour.\n- 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.", - "operationId": "analytics/get_report", + "summary": "Get Salesforce account details including bill-to information.", + "description": "Get Salesforce account details including bill-to information to be used in insertion orders process forad_account_id.\n- 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, Finance, Campaign.",
+ "operationId": "ssio_accounts/get",
"security": [
{
"pinterest_oauth2": [
@@ -4988,14 +5638,11 @@
]
}
],
- "x-ratelimit-category": "ads_analytics",
- "x-sandbox": "disabled",
+ "x-ratelimit-category": "ads_read",
+ "x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
- },
- {
- "$ref": "#/components/parameters/query_token_required"
}
],
"responses": {
@@ -5003,14 +5650,14 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/AdsAnalyticsGetAsyncResponse"
+ "$ref": "#/components/schemas/SSIOAccountResponse"
}
}
},
"description": "Success"
},
"400": {
- "description": "Invalid ad account ads analytics parameters.",
+ "description": "Invalid request parameter.",
"content": {
"application/json": {
"schema": {
@@ -5018,7 +5665,7 @@
},
"example": {
"code": 400,
- "message": "Invalid ad account ads analytics parameters."
+ "message": "Invalid request parameter."
}
}
}
@@ -5035,50 +5682,53 @@
}
},
"tags": [
- "ad_accounts"
+ "billing"
]
- },
+ }
+ },
+ "/ad_accounts/{ad_account_id}/ssio/insertion_orders": {
"post": {
- "summary": "Create async request for an account analytics report",
- "description": "This returns a token that you can use to download the report when it is ready. Note that this endpoint requires the parameters to be passed as JSON-formatted in the request body. This endpoint does not support URL query parameters.\n- 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.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- 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.\n- If level is PRODUCT_ITEM, the furthest back you can are allowed to pull data is 92 days before the current date in UTC time and the max time range supported is 31 days.\n- If level is PRODUCT_ITEM, ad_ids and ad_statuses parameters are not allowed. Any columns related to pin promotion and ad is not allowed either.",
- "operationId": "analytics/create_report",
+ "summary": "Create insertion order through SSIO.",
+ "description": "Create insertion order through SSIO for ad_account_id.\n- 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, Finance, Campaign.",
+ "operationId": "ssio_insertion_order/create",
"security": [
{
"pinterest_oauth2": [
- "ads:read"
+ "ads:write"
]
}
],
- "x-ratelimit-category": "ads_analytics",
- "x-sandbox": "disabled",
+ "x-ratelimit-category": "ads_write",
+ "x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
- "required": true,
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/AdsAnalyticsCreateAsyncRequest"
+ "$ref": "#/components/schemas/SSIOCreateInsertionOrderRequest"
}
}
- }
+ },
+ "description": "Order line to create.",
+ "required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/AdsAnalyticsCreateAsyncResponse"
+ "$ref": "#/components/schemas/SSIOCreateInsertionOrderResponse"
}
}
},
"description": "Success"
},
"400": {
- "description": "Invalid ad account ads analytics parameters.",
+ "description": "Invalid request.",
"content": {
"application/json": {
"schema": {
@@ -5086,7 +5736,7 @@
},
"example": {
"code": 400,
- "message": "Invalid ad account ads analytics parameters."
+ "message": "Invalid request."
}
}
}
@@ -5103,15 +5753,13 @@
}
},
"tags": [
- "ad_accounts"
+ "billing"
]
- }
- },
- "/ad_accounts/{ad_account_id}/sandbox": {
- "delete": {
- "summary": "Delete ads data for ad account in API Sandbox",
- "description": "Delete an ad account and all the ads data associated with that account. \nA string message is returned indicating the status of the delete operation.\n\nNote: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5). \nGo to https://developers.pinterest.com/docs/dev-tools/sandbox/ for more information.",
- "operationId": "sandbox/delete",
+ },
+ "patch": {
+ "summary": "Edit insertion order through SSIO.",
+ "description": "Edit insertion order through SSIO for ad_account_id.\n- 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, Finance, Campaign.",
+ "operationId": "ssio_insertion_order/edit",
"security": [
{
"pinterest_oauth2": [
@@ -5126,20 +5774,30 @@
"$ref": "#/components/parameters/path_ad_account_id"
}
],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SSIOEditInsertionOrderRequest"
+ }
+ }
+ },
+ "description": "Order line to create.",
+ "required": true
+ },
"responses": {
"200": {
- "description": "OK",
"content": {
"application/json": {
"schema": {
- "type": "string",
- "example": "Delete Success"
+ "$ref": "#/components/schemas/SSIOEditInsertionOrderResponse"
}
}
- }
+ },
+ "description": "Success"
},
"400": {
- "description": "Invalid ad account id.",
+ "description": "Invalid request.",
"content": {
"application/json": {
"schema": {
@@ -5147,7 +5805,7 @@
},
"example": {
"code": 400,
- "message": "Invalid ad account id"
+ "message": "Invalid request."
}
}
}
@@ -5164,15 +5822,15 @@
}
},
"tags": [
- "ad_accounts"
+ "billing"
]
}
},
- "/ad_accounts/{ad_account_id}/ssio/accounts": {
+ "/ad_accounts/{ad_account_id}/ssio/insertion_orders/status": {
"get": {
- "summary": "Get Salesforce account details including bill-to information.",
- "description": "Get Salesforce account details including bill-to information to be used in insertion orders process for ad_account_id.\n- 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, Finance, Campaign.",
- "operationId": "ssio_accounts/get",
+ "summary": "Get insertion order status by ad account id.",
+ "description": "Get insertion order status for account id ad_account_id.\n- 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, Finance, Campaign.",
+ "operationId": "ssio_insertion_orders_status/get_by_ad_account",
"security": [
{
"pinterest_oauth2": [
@@ -5185,6 +5843,12 @@
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
+ },
+ {
+ "$ref": "#/components/parameters/query_bookmark"
+ },
+ {
+ "$ref": "#/components/parameters/query_page_size"
}
],
"responses": {
@@ -5192,228 +5856,22 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/SSIOAccountResponse"
- }
- }
- },
- "description": "Success"
- },
- "400": {
- "description": "Invalid request parameter.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- },
- "example": {
- "code": 400,
- "message": "Invalid request parameter."
- }
- }
- }
- },
- "default": {
- "description": "Unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- },
- "tags": [
- "billing"
- ]
- }
- },
- "/ad_accounts/{ad_account_id}/ssio/insertion_orders": {
- "post": {
- "summary": "Create insertion order through SSIO.",
- "description": "Create insertion order through SSIO for ad_account_id.\n- 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, Finance, Campaign.",
- "operationId": "ssio_insertion_order/create",
- "security": [
- {
- "pinterest_oauth2": [
- "ads:write"
- ]
- }
- ],
- "x-ratelimit-category": "ads_write",
- "x-sandbox": "enabled",
- "parameters": [
- {
- "$ref": "#/components/parameters/path_ad_account_id"
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/SSIOCreateInsertionOrderRequest"
- }
- }
- },
- "description": "Order line to create.",
- "required": true
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/SSIOCreateInsertionOrderResponse"
- }
- }
- },
- "description": "Success"
- },
- "400": {
- "description": "Invalid request.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- },
- "example": {
- "code": 400,
- "message": "Invalid request."
- }
- }
- }
- },
- "default": {
- "description": "Unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- },
- "tags": [
- "billing"
- ]
- },
- "patch": {
- "summary": "Edit insertion order through SSIO.",
- "description": "Edit insertion order through SSIO for ad_account_id.\n- 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, Finance, Campaign.",
- "operationId": "ssio_insertion_order/edit",
- "security": [
- {
- "pinterest_oauth2": [
- "ads:write"
- ]
- }
- ],
- "x-ratelimit-category": "ads_write",
- "x-sandbox": "enabled",
- "parameters": [
- {
- "$ref": "#/components/parameters/path_ad_account_id"
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/SSIOEditInsertionOrderRequest"
- }
- }
- },
- "description": "Order line to create.",
- "required": true
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/SSIOEditInsertionOrderResponse"
- }
- }
- },
- "description": "Success"
- },
- "400": {
- "description": "Invalid request.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- },
- "example": {
- "code": 400,
- "message": "Invalid request."
- }
- }
- }
- },
- "default": {
- "description": "Unexpected error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Error"
- }
- }
- }
- }
- },
- "tags": [
- "billing"
- ]
- }
- },
- "/ad_accounts/{ad_account_id}/ssio/insertion_orders/status": {
- "get": {
- "summary": "Get insertion order status by ad account id.",
- "description": "Get insertion order status for account id ad_account_id.\n- 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, Finance, Campaign.",
- "operationId": "ssio_insertion_orders_status/get_by_ad_account",
- "security": [
- {
- "pinterest_oauth2": [
- "ads:read"
- ]
- }
- ],
- "x-ratelimit-category": "ads_read",
- "x-sandbox": "enabled",
- "parameters": [
- {
- "$ref": "#/components/parameters/path_ad_account_id"
- },
- {
- "$ref": "#/components/parameters/query_bookmark"
- },
- {
- "$ref": "#/components/parameters/query_page_size"
- }
- ],
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "allOf": [
- {
- "$ref": "#/components/schemas/Paginated"
- },
- {
- "type": "object",
- "properties": {
- "items": {
- "description": "Insertion orders status by ad acount id",
- "items": {
- "$ref": "#/components/schemas/SSIOInsertionOrderStatus"
- }
- }
- }
- }
- ]
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/Paginated"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "items": {
+ "description": "Insertion orders status by ad acount id",
+ "items": {
+ "$ref": "#/components/schemas/SSIOInsertionOrderStatus"
+ }
+ }
+ }
+ }
+ ]
}
}
},
@@ -6115,6 +6573,234 @@
]
}
},
+ "/advanced_auction/items/get": {
+ "post": {
+ "summary": "Get item bid options (POST)",
+ "description": "Get the bid options for a batch of retail catalog items.\n\nThe catalog must be owned by the \"operation user_account\". See detailed documentation here. By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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`.\n\nThis endpoint is not available to all users.",
+ "operationId": "advanced_auction_items_get/post",
+ "x-ratelimit-category": "advanced_auction_read",
+ "x-sandbox": "enabled",
+ "security": [
+ {
+ "pinterest_oauth2": [
+ "ads:read",
+ "catalogs:read"
+ ]
+ }
+ ],
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/query_ad_account_id"
+ }
+ ],
+ "requestBody": {
+ "description": "Request object used to get bid options values for a batch of retail catalog items",
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdvancedAuctionItemsGetRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Response containing the bid option values for the requested retail catalog items. Items that don't exist or do not have bid options set won't be present in the response.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdvancedAuctionItems"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request parameters.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "examples": {
+ "InvalidRequest": {
+ "value": {
+ "code": 1,
+ "message": "Invalid request: {'catalog_id': '1234'} list of retail catalog items not provided"
+ }
+ }
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Not authenticated to get item bid options",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "examples": {
+ "UnauthenticatedAccess": {
+ "value": {
+ "code": 2,
+ "message": "Authentication failed."
+ }
+ }
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Not authorized to get item bid options",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "Unexpected error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ },
+ "tags": [
+ "advanced_auction"
+ ]
+ }
+ },
+ "/advanced_auction/items/submit": {
+ "post": {
+ "summary": "Operate on item level bid options",
+ "description": "This endpoint supports multiple operations on a set of one or more bid options (bid price and bid adjustments for targeting categories) for retail catalog items. These advanced auction settings are applied in campaigns using objective_type `CATALOG_SALES` and ad groups using bid_strategy_type `MAX_BID`.\n\nThe catalog must be owned by the \"operation user_account\". See detailed documentation here. By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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`.\n\nThis endpoint is not available to all users.",
+ "operationId": "advanced_auction_items_submit/post",
+ "x-ratelimit-category": "advanced_auction_write",
+ "x-sandbox": "enabled",
+ "security": [
+ {
+ "pinterest_oauth2": [
+ "ads:write",
+ "catalogs:read"
+ ]
+ }
+ ],
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/query_ad_account_id"
+ }
+ ],
+ "requestBody": {
+ "description": "Request object used to upsert or delete bid options for a batch of retail catalog items",
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Response containing the results of the item bid options operations",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdvancedAuctionProcessedItems"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request parameters.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "examples": {
+ "InvalidRequest": {
+ "value": {
+ "code": 1,
+ "message": "Invalid request: {'catalog_id': '1234'} list of item bid option operations not provided"
+ }
+ }
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Not authenticated to post item bid options",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "examples": {
+ "UnauthenticatedAccess": {
+ "value": {
+ "code": 2,
+ "message": "Authentication failed."
+ }
+ }
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Not authorized to post item bid options",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "Unexpected error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ },
+ "tags": [
+ "advanced_auction"
+ ]
+ }
+ },
"/boards": {
"get": {
"summary": "List boards",
@@ -6128,6 +6814,11 @@
"pinterest_oauth2": [
"boards:read"
]
+ },
+ {
+ "client_credentials": [
+ "boards:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -6310,6 +7001,11 @@
"pinterest_oauth2": [
"boards:read"
]
+ },
+ {
+ "client_credentials": [
+ "boards:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -6318,17 +7014,17 @@
{
"lang": "python",
"label": "Python SDK",
- "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.boards import Board\n# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\nBOARD_ID=\"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.\n\nLearn more",
+ "description": "Fetch catalogs owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "catalogs/list",
"security": [
{
@@ -8740,19 +10009,115 @@
"tags": [
"catalogs"
]
+ },
+ "post": {
+ "x-ratelimit-category": "catalogs_write",
+ "summary": "Create catalog",
+ "description": "Create a new catalog owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more\n\nNote: this API only supports the catalog type of HOTEL for now.",
+ "operationId": "catalogs/create",
+ "security": [
+ {
+ "pinterest_oauth2": [
+ "catalogs:write"
+ ]
+ }
+ ],
+ "x-sandbox": "enabled",
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/query_ad_account_id"
+ }
+ ],
+ "requestBody": {
+ "description": "Request object used to created a feed.",
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CatalogsCreateRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Catalog"
+ }
+ }
+ },
+ "description": "Success"
+ },
+ "400": {
+ "description": "Invalid parameters.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ },
+ "examples": {
+ "InvalidRequest": {
+ "value": {
+ "code": 1,
+ "message": "Invalid request: ..."
+ }
+ }
+ }
+ }
+ }
+ },
+ "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."
+ }
+ }
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "Unexpected error.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ },
+ "tags": [
+ "catalogs"
+ ]
}
},
"/catalogs/feeds": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "List feeds",
- "description": "Fetch feeds owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.",
+ "description": "Fetch feeds owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.",
"operationId": "feeds/list",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
+ },
+ {
+ "client_credentials": [
+ "catalogs:read"
+ ]
}
],
"x-sandbox": "enabled",
@@ -8850,7 +10215,7 @@
"post": {
"x-ratelimit-category": "catalogs_write",
"summary": "Create feed",
- "description": "Create a new feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nPlease, be aware that \"default_country\"\nand \"default_locale\" are not required in the spec for forward compatibility\nbut for now the API will not accept requests without those fields.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "description": "Create a new feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nPlease, be aware that \"default_country\"\nand \"default_locale\" are not required in the spec for forward compatibility\nbut for now the API will not accept requests without those fields.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.",
"operationId": "feeds/create",
"security": [
{
@@ -8858,6 +10223,12 @@
"catalogs:read",
"catalogs:write"
]
+ },
+ {
+ "client_credentials": [
+ "catalogs:read",
+ "catalogs:write"
+ ]
}
],
"x-sandbox": "enabled",
@@ -8948,7 +10319,7 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -9035,13 +10406,18 @@
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "Get feed",
- "description": "Get a single feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.",
+ "description": "Get a single feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.",
"operationId": "feeds/get",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
+ },
+ {
+ "client_credentials": [
+ "catalogs:read"
+ ]
}
],
"x-sandbox": "enabled",
@@ -9136,7 +10512,7 @@
"patch": {
"x-ratelimit-category": "catalogs_write",
"summary": "Update feed",
- "description": "Update a feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "description": "Update a feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.",
"operationId": "feeds/update",
"security": [
{
@@ -9144,6 +10520,12 @@
"catalogs:read",
"catalogs:write"
]
+ },
+ {
+ "client_credentials": [
+ "catalogs:read",
+ "catalogs:write"
+ ]
}
],
"x-sandbox": "enabled",
@@ -9213,13 +10595,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -9262,7 +10644,7 @@
"delete": {
"x-ratelimit-category": "catalogs_write",
"summary": "Delete feed",
- "description": "Delete a feed owned by the \"operating user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.",
+ "description": "Delete a feed owned by the \"operating user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.",
"operationId": "feeds/delete",
"security": [
{
@@ -9270,6 +10652,12 @@
"catalogs:read",
"catalogs:write"
]
+ },
+ {
+ "client_credentials": [
+ "catalogs:read",
+ "catalogs:write"
+ ]
}
],
"x-sandbox": "enabled",
@@ -9314,13 +10702,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -9382,8 +10770,8 @@
"/catalogs/feeds/{feed_id}/ingest": {
"post": {
"x-ratelimit-category": "catalogs_write",
- "summary": "Ingest items for a given feed",
- "description": "Ingest items for a given feed owned by the \"operation user_account\".\n\nOptional: 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.\n\nLearn more\n\nNote: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5).\nGo to https://developers.pinterest.com/docs/dev-tools/sandbox/ for more information.",
+ "summary": "Ingest feed items",
+ "description": "Ingest items for a given feed owned by the \"operation user_account\".\n\nOptional: 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.\n\nLearn more\n\nNote: This endpoint is restricted to a specific group of users. If you require access, please reach out to your partner manager.",
"operationId": "feeds/ingest",
"security": [
{
@@ -9402,8 +10790,15 @@
}
],
"responses": {
- "204": {
- "description": "The ingestion process was successfully started."
+ "200": {
+ "description": "The ingestion process was successfully started.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CatalogsFeedIngestion"
+ }
+ }
+ }
},
"400": {
"description": "Invalid feed parameters.",
@@ -9434,13 +10829,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -9484,8 +10879,8 @@
"/catalogs/feeds/{feed_id}/processing_results": {
"get": {
"x-ratelimit-category": "catalogs_read",
- "summary": "List processing results for a given feed",
- "description": "Fetch a feed processing results owned by the \"operation user_account\". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
+ "summary": "List feed processing results",
+ "description": "Fetch a feed processing results owned by the \"operation user_account\". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "feed_processing_results/list",
"security": [
{
@@ -9608,8 +11003,8 @@
"/catalogs/processing_results/{processing_result_id}/item_issues": {
"get": {
"x-ratelimit-category": "catalogs_read",
- "summary": "List item issues for a given processing result",
- "description": "List item validation issues for a given feed processing result owned by the \"operation user_account\". Up to 20 random samples of affected items are returned for each error and warning code. Please note that for now query parameters 'item_numbers' and 'item_validation_issue' cannot be used simultaneously until it is implemented in some release in the future.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
+ "summary": "List item issues",
+ "description": "List item validation issues for a given feed processing result owned by the \"operation user_account\". Up to 20 random samples of affected items are returned for each error and warning code. Please note that for now query parameters 'item_numbers' and 'item_validation_issue' cannot be used simultaneously until it is implemented in some release in the future.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: To get a list of all affected items instead of sampled issues, please refer to Build catalogs report and Get catalogs report endpoints. Moreover, they support multiple types of catalogs.\n\nLearn more",
"operationId": "items_issues/list",
"security": [
{
@@ -9737,8 +11132,9 @@
},
"/catalogs/items": {
"get": {
+ "deprecated": true,
"summary": "Get catalogs items",
- "description": "Get the items of the catalog owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "description": "Get the items of the catalog owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: this endpoint is deprecated and will be deleted soon. Please use Get catalogs items (POST) instead.",
"operationId": "items/get",
"security": [
{
@@ -9840,7 +11236,7 @@
},
"post": {
"summary": "Get catalogs items (POST)",
- "description": "Get the items of the catalog owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "description": "Get the items of the catalog owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.",
"operationId": "items/post",
"security": [
{
@@ -9943,7 +11339,7 @@
"/catalogs/items/batch": {
"post": {
"summary": "Operate on item batch",
- "description": "This endpoint supports multiple operations on a set of one or more catalog items owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "description": "This endpoint supports multiple operations on a set of one or more catalog items owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote:\n- Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.\n- The item UPSERT operation is restricted to users without a feed data source. If you plan to migrate item ingestion from feeds to the API, please reach out to your partner manager to get assistance.",
"operationId": "items_batch/post",
"x-ratelimit-category": "catalogs_write",
"x-sandbox": "enabled",
@@ -9953,6 +11349,12 @@
"catalogs:read",
"catalogs:write"
]
+ },
+ {
+ "client_credentials": [
+ "catalogs:read",
+ "catalogs:write"
+ ]
}
],
"parameters": [
@@ -10053,14 +11455,19 @@
},
"/catalogs/items/batch/{batch_id}": {
"get": {
- "summary": "Get catalogs item batch status",
- "description": "Get a single catalogs items batch owned by the \"operating user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.",
+ "summary": "Get item batch status",
+ "description": "Get a single catalogs items batch owned by the \"operating user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.",
"operationId": "items_batch/get",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
+ },
+ {
+ "client_credentials": [
+ "catalogs:read"
+ ]
}
],
"x-ratelimit-category": "catalogs_read",
@@ -10170,8 +11577,8 @@
"/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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
+ "summary": "Delete product groups",
+ "description": "Delete product groups owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "catalogs_product_groups/delete_many",
"x-sandbox": "enabled",
"parameters": [
@@ -10222,13 +11629,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -10300,8 +11707,8 @@
},
"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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "summary": "Create product groups",
+ "description": "Create product group to use in Catalogs owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.",
"operationId": "catalogs_product_groups/create_many",
"security": [
{
@@ -10343,7 +11750,6 @@
{
"name": "Few Filters using \"all_of\"",
"feed_id": "2680059592705",
- "featured": false,
"filters": {
"all_of": [
{
@@ -10375,7 +11781,6 @@
"value": [
{
"name": "Many Filters using \"any_of\"",
- "featured": false,
"feed_id": "2680059592705",
"filters": {
"all_of": [
@@ -10529,6 +11934,39 @@
}
]
},
+ "CatalogBasedRetailFewFiltersUsingAllOf": {
+ "summary": "A simple catalog based 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\nmust be satisfied by a retail to be included in the Product Group.\n",
+ "value": [
+ {
+ "catalog_type": "RETAIL",
+ "name": "Few Filters using \"all_of\"",
+ "catalog_id": "4866935934774",
+ "country": "US",
+ "locale": "en-US",
+ "filters": {
+ "all_of": [
+ {
+ "ITEM_ID": {
+ "values": [
+ "item1",
+ "item2"
+ ]
+ }
+ },
+ {
+ "CUSTOM_LABEL_1": {
+ "values": [
+ "shoes"
+ ],
+ "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\nmust be satisfied by a hotel to be included in the Product Group.\n",
@@ -10628,13 +12066,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -10697,7 +12135,7 @@
"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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
+ "description": "Get a list of product groups for a given Catalogs Feed Id owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "catalogs_product_groups/list",
"security": [
{
@@ -10800,13 +12238,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -10866,8 +12304,8 @@
},
"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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "summary": "Create product group",
+ "description": "Create product group to use in Catalogs owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.",
"operationId": "catalogs_product_groups/create",
"security": [
{
@@ -10904,7 +12342,6 @@
"value": {
"name": "Few Filters using \"all_of\"",
"feed_id": "2680059592705",
- "featured": false,
"filters": {
"all_of": [
{
@@ -10934,7 +12371,6 @@
"description": "The use of \"any_of\" creates a Product Group where any of the individual filters\ncan add products to the Product Group independently.\n",
"value": {
"name": "Many Filters using \"any_of\"",
- "featured": false,
"feed_id": "2680059592705",
"filters": {
"all_of": [
@@ -11115,6 +12551,37 @@
]
}
}
+ },
+ "CatalogBasedRetailFewFiltersUsingAllOf": {
+ "summary": "A simple catalog based 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\nmust be satisfied by a retail to be included in the Product Group.\n",
+ "value": {
+ "catalog_type": "RETAIL",
+ "name": "Few Filters using \"all_of\"",
+ "catalog_id": "4866935934774",
+ "country": "US",
+ "locale": "en-US",
+ "filters": {
+ "all_of": [
+ {
+ "ITEM_ID": {
+ "values": [
+ "item1",
+ "item2"
+ ]
+ }
+ },
+ {
+ "CUSTOM_LABEL_1": {
+ "values": [
+ "shoes"
+ ],
+ "negated": false
+ }
+ }
+ ]
+ }
+ }
}
}
}
@@ -11178,13 +12645,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -11246,8 +12713,8 @@
"/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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
+ "summary": "Get product group",
+ "description": "Get a singe product group for a given Catalogs Product Group Id owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "catalogs_product_groups/get",
"x-sandbox": "enabled",
"parameters": [
@@ -11323,13 +12790,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -11389,8 +12856,8 @@
},
"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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
+ "summary": "Delete product group",
+ "description": "Delete a product group owned by the \"operation user_account\" from being in use in Catalogs.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "catalogs_product_groups/delete",
"x-sandbox": "enabled",
"parameters": [
@@ -11459,13 +12926,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -11538,7 +13005,7 @@
"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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more\n\nNote: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.\nIf access is required, please contact your partner manager.",
+ "description": "Update product group owned by the \"operation user_account\" to use in Catalogs.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.",
"operationId": "catalogs_product_groups/update",
"x-sandbox": "enabled",
"parameters": [
@@ -11632,13 +13099,13 @@
"MerchantDisapproved": {
"value": {
"code": 2625,
- "message": "Sorry, you cannot perform this action. Account is disapproved."
+ "message": "Sorry, you cannot perform this action as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
- "message": "Sorry, you cannot perform this action. Account is under review."
+ "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/"
}
}
}
@@ -11724,8 +13191,8 @@
"/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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: This endpoint only supports RETAIL catalog at the moment.\n\nLearn more",
+ "summary": "Get product counts",
+ "description": "Get a product counts for a given Catalogs Product Group owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "catalogs_product_groups/product_counts_get",
"security": [
{
@@ -11748,7 +13215,7 @@
"content": {
"application/json": {
"schema": {
- "$ref": "#/components/schemas/CatalogsProductGroupProductCounts"
+ "$ref": "#/components/schemas/CatalogsProductGroupProductCountsVertical"
}
}
},
@@ -11809,8 +13276,8 @@
"/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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: This endpoint only supports RETAIL catalog at the moment.\n\nLearn more",
+ "summary": "List products by product group",
+ "description": "Get a list of product pins for a given Catalogs Product Group Id owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nLearn more",
"operationId": "catalogs_product_group_pins/list",
"security": [
{
@@ -11834,6 +13301,9 @@
},
{
"$ref": "#/components/parameters/query_ad_account_id"
+ },
+ {
+ "$ref": "#/components/parameters/query_pin_metrics"
}
],
"responses": {
@@ -11935,8 +13405,8 @@
"/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.\n- This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: This endpoint only supports RETAIL catalog at the moment.\n\nLearn more",
+ "summary": "List products by filter",
+ "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.\n- This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: This endpoint only supports RETAIL catalog at the moment.\n\nLearn more",
"operationId": "products_by_product_group_filter/list",
"security": [
{
@@ -11957,6 +13427,9 @@
},
{
"$ref": "#/components/parameters/query_ad_account_id"
+ },
+ {
+ "$ref": "#/components/parameters/query_pin_metrics"
}
],
"requestBody": {
@@ -12825,7 +14298,7 @@
"/media": {
"get": {
"summary": "List media uploads",
- "description": "List media uploads filtered by given parameters.\n\nLearn more about video Pin creation.",
+ "description": "List media uploads filtered by given parameters.\n\nLearn more about video Pin creation.",
"tags": [
"media"
],
@@ -12887,7 +14360,7 @@
},
"post": {
"summary": "Register media upload",
- "description": "Register your intent to upload media\n\nThe response includes all of the information needed to upload the media\nto Pinterest.\n\nTo upload the media, make an HTTP POST request (using curl, for\nexample) to upload_url using the Content-Type header\nvalue. Send the media file's contents as the request's file\nparameter and also include all of the parameters from\nupload_parameters.\n\nLearn more about video Pin creation.",
+ "description": "Register your intent to upload media\n\nThe response includes all of the information needed to upload the media\nto Pinterest.\n\nTo upload the media, make an HTTP POST request (using curl, for\nexample) to upload_url using the Content-Type header\nvalue. Send the media file's contents as the request's file\nparameter and also include all of the parameters from\nupload_parameters.\n\nLearn more about video Pin creation.",
"tags": [
"media"
],
@@ -12940,7 +14413,7 @@
"/media/{media_id}": {
"get": {
"summary": "Get media upload details",
- "description": "Get details for a registered media upload, including its current status.\n\nLearn more about video Pin creation.",
+ "description": "Get details for a registered media upload, including its current status.\n\nLearn more about video Pin creation.",
"tags": [
"media"
],
@@ -13000,7 +14473,7 @@
"/oauth/token": {
"post": {
"summary": "Generate OAuth access token",
- "description": "Generate an OAuth access token by using an authorization code or a refresh token.\n\nIMPORTANT: You need to start the OAuth flow via www.pinterest.com/oauth before calling this endpoint (or have an existing refresh token).\n\nSee Authentication for more.\n\nParameter refresh_on and its corresponding response type everlasting_refresh are now available to all apps! Later this year, continuous refresh will become the default behavior (ie you will no longer need to send this parameter). Learn more.",
+ "description": "Generate an OAuth access token by using an authorization code or a refresh token.\n\nIMPORTANT: You need to start the OAuth flow via www.pinterest.com/oauth before calling this endpoint (or have an existing refresh token).\n\nSee Authentication for more.\n\nParameter refresh_on and its corresponding response type everlasting_refresh are now available to all apps! Later this year, continuous refresh will become the default behavior (ie you will no longer need to send this parameter). Learn more.\n\nGrant type client_credentials and its corresponding response type are not fully available. You will likely get a default error if you attempt to use this grant_type.",
"tags": [
"oauth"
],
@@ -13058,6 +14531,12 @@
"boards:read",
"pins:read"
]
+ },
+ {
+ "client_credentials": [
+ "boards:read",
+ "pins:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -13157,7 +14636,7 @@
},
"post": {
"summary": "Create Pin",
- "description": "Create a Pin on a board or board section owned by the \"operation user_account\".\n\nNote: If the current \"operation user_account\" (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to make use of the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).\n\n- This function is intended solely for publishing new content created by the user. If you are interested in saving content created by others to your Pinterest boards, sometimes called 'curated content', please use our Save button instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.\n\nLearn more about video Pin creation.",
+ "description": "Create a Pin on a board or board section owned by the \"operation user_account\".\n\nNote: If the current \"operation user_account\" (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to make use of the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).\n\n- This function is intended solely for publishing new content created by the user. If you are interested in saving content created by others to your Pinterest boards, sometimes called 'curated content', please use our Save button instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.\n\nLearn more about video Pin creation.",
"tags": [
"pins"
],
@@ -13178,17 +14657,17 @@
{
"lang": "python",
"label": "Python SDK",
- "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.pins import Pin\n# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\nBOARD_ID=\"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:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.",
+ "description": "Update a pin owned by the \"operating user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.",
"tags": [
"pins"
],
@@ -13519,12 +15004,12 @@
{
"lang": "cURL",
"label": "curl",
- "source": "# Pin information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n\ncurl --location --request PATCH 'https://api.pinterest.com/v5/pins/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:\n\n- For Pins on public or protected boards: Admin, Analyst.\n- For Pins on secret boards: Admin.\n\nIf Pin was created before 2023-03-20 lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then.",
+ "description": "Get analytics for a Pin owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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:\n\n- For Pins on public or protected boards: Admin, Analyst.\n- For Pins on secret boards: Admin.\n\nIf Pin was created before 2023-03-20 lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then.",
"tags": [
"pins"
],
@@ -13625,6 +15110,12 @@
"boards:read",
"pins:read"
]
+ },
+ {
+ "client_credentials": [
+ "boards:read",
+ "pins:read"
+ ]
}
],
"x-ratelimit-category": "org_analytics",
@@ -13721,7 +15212,7 @@
"/pins/analytics": {
"get": {
"summary": "Get multiple Pin analytics",
- "description": "This endpoint is currently in beta and not available to all apps. Learn more.\n\nGet analytics for multiple pins owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- The maximum number of pins supported in a single request is 100.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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:\n\n- For Pins on public or protected boards: Admin, Analyst.\n- For Pins on secret boards: Admin.\n\nIf Pin was created before 2023-03-20 lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then.",
+ "description": "This endpoint is currently in beta and not available to all apps. Learn more.\n\nGet analytics for multiple pins owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- The maximum number of pins supported in a single request is 100.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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:\n\n- For Pins on public or protected boards: Admin, Analyst.\n- For Pins on secret boards: Admin.\n\nIf Pin was created before 2023-03-20 lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then.",
"tags": [
"pins"
],
@@ -13732,24 +15223,19 @@
"boards:read",
"pins:read"
]
+ },
+ {
+ "client_credentials": [
+ "boards:read",
+ "pins:read"
+ ]
}
],
"x-ratelimit-category": "org_analytics",
"x-sandbox": "disabled",
"parameters": [
{
- "name": "pin_ids",
- "description": "List of Pin IDs.",
- "in": "query",
- "schema": {
- "type": "array",
- "items": {
- "type": "string",
- "pattern": "^\\d+$"
- },
- "minItems": 1,
- "maxItems": 100
- }
+ "$ref": "#/components/parameters/query_required_pin_ids"
},
{
"$ref": "#/components/parameters/query_start_date"
@@ -13780,7 +15266,9 @@
"SAVE",
"SAVE_RATE",
"TOTAL_COMMENTS",
- "TOTAL_REACTIONS"
+ "TOTAL_REACTIONS",
+ "USER_FOLLOW",
+ "PROFILE_VISIT"
]
},
{
@@ -13915,17 +15403,17 @@
{
"lang": "python",
"label": "Python SDK",
- "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.pins import Pin\n# Pin information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\nPIN_ID=\"Get the top trending search keywords among the Pinterest user audience.
\nTrending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.
\nGeographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords.
\nFor an interactive way to explore this data, please visit trends.pinterest.com.", + "description": "
Get the top trending search keywords among the Pinterest user audience.
Trending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.
Geographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords.
For an interactive way to explore this data, please visit trends.pinterest.com.\n",
"operationId": "trending_keywords/list",
"security": [
{
@@ -14791,7 +16288,7 @@
"/user_account": {
"get": {
"summary": "Get user account",
- "description": "Get account information for the \"operation user_account\"\n- By default, the \"operation user_account\" is the token user_account.\n\nIf using Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\". See Understanding Business Access for more information.",
+ "description": "Get account information for the \"operation user_account\"\n- By default, the \"operation user_account\" is the token user_account.\n\nIf using Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\". See Understanding Business Access for more information.",
"tags": [
"user_account"
],
@@ -14801,6 +16298,11 @@
"pinterest_oauth2": [
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -14963,6 +16465,12 @@
"pins:read",
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "pins:read",
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "org_analytics",
@@ -15057,6 +16565,12 @@
"pins:read",
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "pins:read",
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "org_analytics",
@@ -15147,6 +16661,11 @@
"pinterest_oauth2": [
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -15191,6 +16710,11 @@
"pinterest_oauth2": [
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "ads_read",
@@ -15269,6 +16793,11 @@
"pinterest_oauth2": [
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -15342,6 +16871,11 @@
"pinterest_oauth2": [
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -15419,7 +16953,7 @@
"/user_account/following/{username}": {
"post": {
"summary": "Follow user",
- "description": "This endpoint is currently in beta and not available to all apps. Learn more.\n\nUse this request, as a signed-in user, to follow another user.",
+ "description": "This endpoint is currently in beta and not available to all apps. Learn more.\n\nUse this request, as a signed-in user, to follow another user.",
"tags": [
"user_account"
],
@@ -15508,6 +17042,11 @@
],
"x-ratelimit-category": "org_write",
"x-sandbox": "disabled",
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/query_ad_account_id"
+ }
+ ],
"requestBody": {
"description": "Verify a website.",
"required": true,
@@ -15678,11 +17217,21 @@
"user_account"
],
"operationId": "website_verification/get",
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/query_ad_account_id"
+ }
+ ],
"security": [
{
"pinterest_oauth2": [
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "user_accounts:read"
+ ]
}
],
"responses": {
@@ -15738,6 +17287,11 @@
"pinterest_oauth2": [
"user_accounts:read"
]
+ },
+ {
+ "client_credentials": [
+ "user_accounts:read"
+ ]
}
],
"x-ratelimit-category": "org_read",
@@ -15862,6 +17416,34 @@
"basic": {
"type": "http",
"scheme": "basic"
+ },
+ "client_credentials": {
+ "flows": {
+ "clientCredentials": {
+ "scopes": {
+ "ads:read": "See all of your advertising data, including ads, ad groups, campaigns etc.",
+ "ads:write": "Create, update, or delete ads, ad groups, campaigns etc.",
+ "billing:read": "See all of your billing data, billing profile, etc.",
+ "billing:write": "Create, update, or delete billing data, billing profiles, etc.",
+ "biz_access:read": "See business access data",
+ "biz_access:write": "Create, update, or delete business access data",
+ "boards:read": "See your public boards, including group boards you join",
+ "boards:read_secret": "See your secret boards",
+ "boards:write": "Create, update, or delete your public boards",
+ "boards:write_secret": "Create, update, or delete your secret boards",
+ "catalogs:read": "See all of your catalogs data",
+ "catalogs:write": "Create, update, or delete your catalogs data",
+ "pins:read": "See your public Pins",
+ "pins:read_secret": "See your secret Pins",
+ "pins:write": "Create, update, or delete your public Pins",
+ "pins:write_secret": "Create, update, or delete your secret Pins",
+ "user_accounts:read": "See your user accounts and followers",
+ "user_accounts:write": "Update your user accounts and followers"
+ },
+ "tokenUrl": "https://api.pinterest.com/v3/oauth/access_token/"
+ }
+ },
+ "type": "oauth2"
}
},
"schemas": {
@@ -16114,12 +17696,14 @@
"cryptographic_key": {
"description": "Base64 encoded key for client to decrypt lead data.",
"example": "ucvxbV2Tdss0vNeYsdh4Qfa/1Khm2b0PqXvXeTTZh54",
- "type": "string"
+ "type": "string",
+ "nullable": true
},
"cryptographic_algorithm": {
"description": "Lead data encryption algorithm.",
"example": "AES-256-GCM",
- "type": "string"
+ "type": "string",
+ "nullable": true
},
"created_time": {
"description": "Subscription creation time. Unix timestamp in milliseconds.",
@@ -16179,12 +17763,14 @@
"cryptographic_key": {
"description": "Base64 encoded key for client to decrypt lead data.",
"example": "ucvxbV2Tdss0vNeYsdh4Qfa/1Khm2b0PqXvXeTTZh54",
- "type": "string"
+ "type": "string",
+ "nullable": true
},
"cryptographic_algorithm": {
"description": "Lead data encryption algorithm.",
"example": "AES-256-GCM",
- "type": "string"
+ "type": "string",
+ "nullable": true
},
"created_time": {
"description": "Lead form creation time. Unix timestamp in milliseconds.",
@@ -16264,7 +17850,7 @@
"pattern": "^(AG)?\\d+$"
},
"android_deep_link": {
- "description": "Deep link URL for Android devices. Not currently available. Using this field will generate an error.",
+ "description": "Deep link URL for Android devices.",
"nullable": true,
"type": "string"
},
@@ -16306,7 +17892,7 @@
"nullable": true
},
"ios_deep_link": {
- "description": "Deep link URL for iOS devices. Not currently available. Using this field will generate an error.",
+ "description": "Deep link URL for iOS devices.",
"type": "string",
"nullable": true
},
@@ -16353,7 +17939,7 @@
},
"customizable_cta_type": {
"type": "string",
- "description": "Select a call to action (CTA) to display below your ad. Available only for ads with direct links enabled. CTA options for consideration and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP, VISIT_WEBSITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion campaigns with add to cart conversion events only)",
+ "description": "Select a call to action (CTA) to display below your ad. Available only for ads with direct links enabled. CTA options for consideration and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP, VISIT_SITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion campaigns with add to cart conversion events only)",
"example": "LEARN_MORE",
"nullable": true,
"enum": [
@@ -16366,7 +17952,7 @@
"BUY_NOW",
"CONTACT_US",
"GET_QUOTE",
- "VISIT_WEBSITE",
+ "VISIT_SITE",
"APPLY_NOW",
"BOOK_NOW",
"REQUEST_DEMO",
@@ -16665,6 +18251,366 @@
}
]
},
+ "AdvancedAuctionItemsGetRequest": {
+ "type": "object",
+ "description": "Request object used to get bid options values for a batch of retail catalog items",
+ "additionalProperties": false,
+ "properties": {
+ "catalog_id": {
+ "description": "Catalog id pertaining to the retail item",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "items": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 10000,
+ "description": "A list of retail catalog items to fetch bid options for",
+ "items": {
+ "$ref": "#/components/schemas/AdvancedAuctionItemsGetRecord"
+ }
+ }
+ },
+ "required": [
+ "catalog_id",
+ "items"
+ ]
+ },
+ "AdvancedAuctionItemsGetRecord": {
+ "description": "Object uniquely identifying a retail catalog item",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/AdvancedAuctionKey"
+ }
+ ]
+ },
+ "AdvancedAuctionItems": {
+ "type": "object",
+ "description": "Response object containing item bid options",
+ "properties": {
+ "catalog_id": {
+ "description": "Response object of item bid options",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "items": {
+ "type": "array",
+ "description": "Array with item bid options",
+ "items": {
+ "$ref": "#/components/schemas/AdvancedAuctionItem"
+ }
+ }
+ }
+ },
+ "AdvancedAuctionItemsSubmitRequest": {
+ "type": "object",
+ "description": "Request containing operations to perform on bid prices and bid multipliers for a batch of retail catalog items",
+ "additionalProperties": false,
+ "properties": {
+ "catalog_id": {
+ "description": "Catalog id pertaining to all items",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "items": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 10000,
+ "description": "Array of item bid option operations",
+ "items": {
+ "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitRecord"
+ }
+ }
+ },
+ "required": [
+ "catalog_id",
+ "items"
+ ]
+ },
+ "AdvancedAuctionItemsSubmitRecord": {
+ "type": "object",
+ "description": "Object describing an item bid option operation",
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord"
+ },
+ {
+ "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "operation",
+ "mapping": {
+ "UPSERT": "#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord",
+ "DELETE": "#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord"
+ }
+ },
+ "properties": {
+ "operation": {
+ "$ref": "#/components/schemas/AdvancedAuctionOperation"
+ }
+ },
+ "required": [
+ "operation"
+ ]
+ },
+ "AdvancedAuctionItemsSubmitUpsertRecord": {
+ "description": "Object describing an item bid option upsert operation",
+ "example": {
+ "item_id": "DS0294-M",
+ "country": "US",
+ "language": "EN",
+ "operation": "UPSERT",
+ "bid_options": {
+ "bid_in_micro_currency": 5000000,
+ "app_type_multipliers": {
+ "android_mobile": 1.1,
+ "android_tablet": 1.1,
+ "ipad": 1.2,
+ "iphone": 1.2,
+ "web": 0.9,
+ "web_mobile": 0.8
+ }
+ },
+ "update_mask": [
+ "BID",
+ "APP_TYPE_BID_MULTIPLIER_SET"
+ ]
+ },
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/AdvancedAuctionItem"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "update_mask": {
+ "type": "array",
+ "description": "The list of item bid option fields to be set or updated. Fields specified in the updated mask without a value specified in the `bid_options` object in the body will be set to `null`. If an item bid option record is being created, fields not specified in the update mask will be initialized to `null`.",
+ "example": [
+ "BID",
+ "APP_TYPE_BID_MULTIPLIER_SET"
+ ],
+ "nullable": true,
+ "items": {
+ "$ref": "#/components/schemas/UpdateMaskBidOptionField"
+ }
+ }
+ },
+ "required": [
+ "update_mask"
+ ]
+ }
+ ]
+ },
+ "AdvancedAuctionItemsSubmitDeleteRecord": {
+ "description": "Object describing an item bid option deletion operation",
+ "example": {
+ "item_id": "DS0294-M",
+ "country": "US",
+ "language": "EN",
+ "operation": "DELETE"
+ },
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/AdvancedAuctionKey"
+ }
+ ]
+ },
+ "AdvancedAuctionProcessedItems": {
+ "type": "object",
+ "description": "Response object containing the results of an operation on an item bid option",
+ "properties": {
+ "catalog_id": {
+ "description": "Catalog id pertaining to all items",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "items": {
+ "type": "array",
+ "description": "Array of advanced auction processed items",
+ "items": {
+ "$ref": "#/components/schemas/AdvancedAuctionProcessedItem"
+ }
+ }
+ }
+ },
+ "AdvancedAuctionProcessedItem": {
+ "description": "Object describing the result of an operation on an item bid option",
+ "type": "object",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitRecord"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "description": "Array with validation errors for the supplied item bid option modification operation.\nA non empty errors list means this single item operation was not applied.",
+ "items": {
+ "$ref": "#/components/schemas/AdvancedAuctionOperationError"
+ }
+ }
+ }
+ }
+ ]
+ },
+ "AdvancedAuctionItem": {
+ "title": "Advanced Auction Item",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/AdvancedAuctionKey"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "bid_options": {
+ "$ref": "#/components/schemas/AdvancedAuctionBidOptions"
+ }
+ },
+ "required": [
+ "bid_options"
+ ]
+ }
+ ]
+ },
+ "AdvancedAuctionKey": {
+ "type": "object",
+ "description": "Object uniquely identifying a retail catalog item",
+ "properties": {
+ "item_id": {
+ "description": "The catalog retail item id in the merchant namespace",
+ "example": "DS0294-M",
+ "type": "string"
+ },
+ "country": {
+ "$ref": "#/components/schemas/Country"
+ },
+ "language": {
+ "$ref": "#/components/schemas/Language"
+ }
+ },
+ "required": [
+ "item_id",
+ "country",
+ "language"
+ ]
+ },
+ "AdvancedAuctionOperation": {
+ "type": "string",
+ "enum": [
+ "UPSERT",
+ "DELETE"
+ ]
+ },
+ "AdvancedAuctionBidOptions": {
+ "type": "object",
+ "description": "Object describing a retail catalog item's bid options (bid price and bid multipliers).",
+ "properties": {
+ "bid_in_micro_currency": {
+ "$ref": "#/components/schemas/BidInMicroCurrency"
+ },
+ "app_type_multipliers": {
+ "$ref": "#/components/schemas/AppTypeMultipliers"
+ },
+ "placement_multipliers": {
+ "$ref": "#/components/schemas/PlacementMultipliers"
+ }
+ }
+ },
+ "AdvancedAuctionOperationError": {
+ "description": "Error which occurred when applying a bid options operation to a specific item.",
+ "type": "object",
+ "properties": {
+ "code": {
+ "description": "The error code for the item bid option operation validation error",
+ "type": "integer",
+ "example": 6
+ },
+ "message": {
+ "description": "Message describing the item bid option operation validation error",
+ "type": "string",
+ "example": "Bid in micro currency should be non-negative"
+ }
+ }
+ },
+ "BidInMicroCurrency": {
+ "type": "integer",
+ "format": "int64",
+ "description": "Bid price in micro currency. A value of 0 will stop distribution for this item in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. A value of `null` will fallback to the ad group's `bid_in_micro_currency`.",
+ "example": 5000000,
+ "nullable": true
+ },
+ "AppTypeMultipliers": {
+ "type": "object",
+ "description": "This represents a mapping from app type targeting criteria to a bid price adjustment.\n\nMultiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified app type in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All app type multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment).",
+ "example": {
+ "android_mobile": 1.1,
+ "android_tablet": 1.1,
+ "ipad": 1.2,
+ "iphone": 1.2,
+ "web": 0.9,
+ "web_mobile": 0.8
+ },
+ "properties": {
+ "APP_TYPE": {
+ "$ref": "#/components/schemas/TargetingSpecAppType"
+ }
+ },
+ "additionalProperties": {
+ "type": "number",
+ "format": "double"
+ },
+ "nullable": true
+ },
+ "TargetingSpecAppType": {
+ "type": "string",
+ "enum": [
+ "android_mobile",
+ "android_tablet",
+ "ipad",
+ "iphone",
+ "web",
+ "web_mobile"
+ ]
+ },
+ "PlacementMultipliers": {
+ "type": "object",
+ "description": "This represents a mapping from placement to a bid price adjustment.\n\nMultiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified placement in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All placement multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment).",
+ "example": {
+ "browse": 0.9,
+ "search": 1.2
+ },
+ "properties": {
+ "PLACEMENT": {
+ "type": "string",
+ "enum": [
+ "SEARCH",
+ "BROWSE"
+ ]
+ }
+ },
+ "additionalProperties": {
+ "type": "number",
+ "format": "double"
+ },
+ "nullable": true
+ },
+ "UpdateMaskBidOptionField": {
+ "type": "string",
+ "description": "bid option field to apply operation updates to",
+ "example": "BID",
+ "enum": [
+ "BID",
+ "APP_TYPE_BID_MULTIPLIER_SET",
+ "PLACEMENT_BID_MULTIPLIER_SET"
+ ]
+ },
"AdGroupArrayResponse": {
"type": "object",
"properties": {
@@ -16753,7 +18699,7 @@
"$ref": "#/components/schemas/TargetingSpec"
},
"lifetime_frequency_cap": {
- "description": "Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION billable_event value. This field **REQUIRES** the `end_time` field.",
+ "description": "Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION billable_event value. This field **REQUIRES** the `end_time` field.",
"type": "integer",
"example": 100
},
@@ -16764,7 +18710,7 @@
"$ref": "#/components/schemas/TrackingUrls"
}
],
- "description": "Third-party tracking URLs.
JSON object with the format: {\"Tracking event enum\":[URL string array],...}
For example: {\"impression\": [\"URL1\", \"URL2\"], \"click\": [\"URL1\", \"URL2\", \"URL3\"]}.
Up to three tracking URLs are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. May be null. Pass in an empty object - {} - to remove tracking URLs.
For more information, see Third-party and dynamic tracking.",
+ "description": "Third-party tracking URLs.
JSON object with the format: {\"Tracking event enum\":[URL string array],...}
For example: {\"impression\": [\"URL1\", \"URL2\"], \"click\": [\"URL1\", \"URL2\", \"URL3\"]}.
Up to three tracking URLs are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. May be null. Pass in an empty object - {} - to remove tracking URLs.
For more information, see Third-party and dynamic tracking.",
"nullable": true
},
"auto_targeting_enabled": {
@@ -16780,7 +18726,7 @@
"$ref": "#/components/schemas/PlacementGroupType"
}
],
- "description": "Placement group."
+ "description": "Placement group."
},
"pacing_delivery_type": {
"type": "string",
@@ -16801,7 +18747,7 @@
},
"bid_strategy_type": {
"nullable": true,
- "description": "Bid strategy type",
+ "description": "Bid strategy type. For Campaigns with Video Completion objectives, the only supported bid strategy type is AUTOMATIC_BID.",
"enum": [
"AUTOMATIC_BID",
"MAX_BID",
@@ -17338,6 +19284,48 @@
}
]
},
+ "AdsAnalyticsAdTargetingType": {
+ "type": "string",
+ "description": "Reporting targeting type for ads",
+ "example": "APPTYPE",
+ "enum": [
+ "KEYWORD",
+ "APPTYPE",
+ "GENDER",
+ "LOCATION",
+ "PLACEMENT",
+ "COUNTRY",
+ "TARGETED_INTEREST",
+ "PINNER_INTEREST",
+ "AUDIENCE_INCLUDE",
+ "GEO",
+ "AGE_BUCKET",
+ "REGION",
+ "QUIZ_RESULT",
+ "AGE_BUCKET_AND_GENDER"
+ ]
+ },
+ "AdsAnalyticsCampaignTargetingType": {
+ "type": "string",
+ "description": "Reporting targeting type for campaigns",
+ "example": "APPTYPE",
+ "enum": [
+ "KEYWORD",
+ "APPTYPE",
+ "GENDER",
+ "LOCATION",
+ "PLACEMENT",
+ "COUNTRY",
+ "TARGETED_INTEREST",
+ "PINNER_INTEREST",
+ "AUDIENCE_INCLUDE",
+ "GEO",
+ "AGE_BUCKET",
+ "REGION",
+ "CREATIVE_TYPE",
+ "AGE_BUCKET_AND_GENDER"
+ ]
+ },
"AdsAnalyticsCreateAsyncRequest": {
"type": "object",
"allOf": [
@@ -17471,7 +19459,7 @@
"items": {
"$ref": "#/components/schemas/ObjectiveType"
},
- "maxItems": 6,
+ "maxItems": 7,
"minItems": 1
}
}
@@ -17659,7 +19647,7 @@
"allOf": [
{
"type": "string",
- "description": "Whether to first sort the report by date or by ID. BY_DATE is recommended for large requests. BY_DATE for JSON format is currently not supported.",
+ "description": "Whether to first sort the report by date or by entity ID of the reporting entity level. Date will be used as the first level key for JSON reports that use BY_DATE. BY_DATE is recommended for large requests.",
"example": "BY_ID",
"enum": [
"BY_ID",
@@ -17668,6 +19656,18 @@
}
],
"default": "BY_ID"
+ },
+ "start_hour": {
+ "description": "Which hour of the start date to begin the report. The entire day will be included if no start hour is provided. Only allowed for hourly reports.",
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 23
+ },
+ "end_hour": {
+ "description": "Which hour of the end date to stop the report (inclusive). For example, with an end_date of '2020-01-01' and end_hour of '15', the report will contain metrics up to '2020-01-01 14:59:59'. The entire day will be included if no end hour is provided. Only allowed for hourly reports.",
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 23
}
}
}
@@ -18012,6 +20012,11 @@
},
"permissions": {
"$ref": "#/components/schemas/PermissionsResponse"
+ },
+ "asset_group_info": {
+ "nullable": true,
+ "description": "An object containing all the information specific to the provided asset group. This field will be populated only if asset_type equals 'ASSET_GROUP'.",
+ "$ref": "#/components/schemas/AssetGroupBinding"
}
}
},
@@ -18041,7 +20046,7 @@
}
},
"AssetTypeResponse": {
- "description": "Type of asset. Currently we only support AD_ACCOUNT and PROFILE.",
+ "description": "Type of asset. Currently we only support AD_ACCOUNT and PROFILE, and ASSET_GROUP.",
"example": "AD_ACCOUNT",
"type": "string"
},
@@ -18520,7 +20525,7 @@
}
},
"AudienceRule": {
- "description": "JSON object defining targeted audience users. Example rule formats per audience type:
CUSTOMER_LIST: { \"customer_list_id\": \"<customer list ID>\"}
ACTALIKE: { \"seed_id\": [\"<audience ID>\"], \"country\": \"US\", \"percentage\": \"10\" }
(Valid countries include: \"US\", \"CA\", and \"GB\". Percentage should be 1-10.
The targeted audience should be this % size across Pinterest.)
VISITOR: { \"visitor_source_id\": [\"<conversion tag ID>\"], \"retention_days\": \"180\", \"event_source\": {\"=\": [\"web\", \"mobile\"]}, \"ingestion_source\": {\"=\": [\"tag\"]}}
(Retention days should be 1-540. Retention applies to specific customers.)
ENGAGEMENT: {\"engagement_domain\": [\"www.entomi.com\"], \"engager_type\": 1}
For more details on engagement audiences, see November 2021 changelog.",
+ "description": "JSON object defining targeted audience users. Example rule formats per audience type:
CUSTOMER_LIST: { \"customer_list_id\": \"<customer list ID>\"}
ACTALIKE: { \"seed_id\": [\"<audience ID>\"], \"country\": \"US\", \"percentage\": \"10\" }
(Valid countries include: \"US\", \"CA\", and \"GB\". Percentage should be 1-10.
The targeted audience should be this % size across Pinterest.)
VISITOR: { \"visitor_source_id\": [\"<conversion tag ID>\"], \"retention_days\": \"180\", \"event_source\": {\"=\": [\"web\", \"mobile\"]}, \"ingestion_source\": {\"=\": [\"tag\"]}}
(Retention days should be 1-540. Retention applies to specific customers.)
ENGAGEMENT: {\"engagement_domain\": [\"www.entomi.com\"], \"engager_type\": 1}
For more details on engagement audiences, see November 2021 changelog.",
"properties": {
"country": {
"description": "Valid countries include: \"US\", \"CA\", and \"GB\".",
@@ -18807,6 +20812,22 @@
"title": "Rule",
"type": "object"
},
+ "AudienceShareType": {
+ "type": "string",
+ "default": "SHARED",
+ "enum": [
+ "SHARED",
+ "RECEIVED"
+ ]
+ },
+ "AudienceAccountType": {
+ "type": "string",
+ "default": "AD_ACCOUNT",
+ "enum": [
+ "AD_ACCOUNT",
+ "BUSINESS_ACCOUNT"
+ ]
+ },
"AudienceSharingType": {
"description": "Audience sharing type: [\"CUSTOM\", \"SYNDICATED\"]",
"type": "string",
@@ -20166,13 +22187,8 @@
"example": 1644023526,
"nullable": true
},
- "summary_status": {
- "type": "string",
- "allOf": [
- {
- "$ref": "#/components/schemas/CampaignSummaryStatus"
- }
- ]
+ "is_flexible_daily_budgets": {
+ "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets"
}
}
},
@@ -20185,24 +22201,6 @@
{
"type": "object",
"properties": {
- "status": {
- "type": "string",
- "default": "ACTIVE",
- "allOf": [
- {
- "$ref": "#/components/schemas/EntityStatus"
- }
- ]
- },
- "is_flexible_daily_budgets": {
- "type": "boolean",
- "default": false,
- "allOf": [
- {
- "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets"
- }
- ]
- },
"default_ad_group_budget_in_micro_currency": {
"type": "integer",
"description": "When transitioning from campaign budget optimization to non-campaign budget optimization, the default_ad_group_budget_in_micro_currency will propagate to each child ad groups daily budget. Unit is micro currency of the associated advertiser account.",
@@ -20210,13 +22208,7 @@
"nullable": true
},
"is_automated_campaign": {
- "type": "boolean",
- "default": false,
- "allOf": [
- {
- "$ref": "#/components/schemas/CampaignIsAutomatedCampaign"
- }
- ]
+ "$ref": "#/components/schemas/CampaignIsAutomatedCampaign"
}
}
}
@@ -20231,6 +22223,33 @@
{
"type": "object",
"properties": {
+ "is_flexible_daily_budgets": {
+ "type": "boolean",
+ "default": false,
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets"
+ }
+ ]
+ },
+ "is_automated_campaign": {
+ "type": "boolean",
+ "default": false,
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/CampaignIsAutomatedCampaign"
+ }
+ ]
+ },
+ "status": {
+ "type": "string",
+ "default": "ACTIVE",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/EntityStatus"
+ }
+ ]
+ },
"objective_type": {
"$ref": "#/components/schemas/ObjectiveType"
}
@@ -20302,19 +22321,19 @@
"type": "boolean",
"description": "Specifies whether the campaign was created in the automated campaign flow",
"example": true,
- "default": false
+ "nullable": true
},
"CampaignIsCampaignBudgetOptimization": {
"type": "boolean",
"description": "Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared.",
"example": true,
- "default": false
+ "nullable": true
},
"CampaignIsFlexibleDailyBudgets": {
"type": "boolean",
"description": "Determine if a campaign has flexible daily budgets setup.",
"example": true,
- "default": false
+ "nullable": true
},
"CampaignResponse": {
"type": "object",
@@ -20346,17 +22365,11 @@
"description": "Always \"campaign\".",
"example": "campaign"
},
- "is_flexible_daily_budgets": {
- "type": "boolean",
- "description": "Determines if a campaign has flexible daily budgets setup.",
- "example": true,
- "nullable": true
- },
"is_campaign_budget_optimization": {
- "type": "boolean",
- "description": "Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared.",
- "example": true,
- "nullable": true
+ "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization"
+ },
+ "summary_status": {
+ "$ref": "#/components/schemas/CampaignSummaryStatus"
}
}
}
@@ -20383,9 +22396,6 @@
{
"$ref": "#/components/schemas/CampaignId"
},
- {
- "$ref": "#/components/schemas/CampaignCommon"
- },
{
"$ref": "#/components/schemas/CampaignCreateCommon"
},
@@ -20393,40 +22403,7 @@
"type": "object",
"properties": {
"is_campaign_budget_optimization": {
- "type": "boolean",
- "nullable": true,
- "allOf": [
- {
- "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization"
- }
- ]
- },
- "is_flexible_daily_budgets": {
- "type": "boolean",
- "nullable": true,
- "allOf": [
- {
- "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets"
- }
- ]
- },
- "is_automated_campaign": {
- "type": "boolean",
- "nullable": true,
- "allOf": [
- {
- "$ref": "#/components/schemas/CampaignIsAutomatedCampaign"
- }
- ]
- },
- "status": {
- "type": "string",
- "nullable": true,
- "allOf": [
- {
- "$ref": "#/components/schemas/EntityStatus"
- }
- ]
+ "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization"
},
"objective_type": {
"type": "string",
@@ -20539,87 +22516,28 @@
}
]
},
- "CatalogProductGroup": {
- "description": "non-promoted catalog product group entity",
+ "CatalogsCreateRequest": {
+ "type": "object",
+ "title": "catalogs_create_request",
+ "description": "Request object for creating a catalog.",
+ "additionalProperties": false,
"properties": {
- "id": {
- "description": "ID of the catalog product group.",
- "example": "2680059592705",
- "title": "id",
- "type": "string"
- },
- "merchant_id": {
- "description": "Merchant ID pertaining to the owner of the catalog product group.",
- "example": "2680059592705",
- "pattern": "^\\d+$",
- "title": "merchant_id",
- "type": "string"
+ "catalog_type": {
+ "description": "Type of the catalog entity.",
+ "type": "string",
+ "enum": [
+ "HOTEL"
+ ]
},
"name": {
- "description": "Name of catalog product group",
- "example": "Most Popular",
- "title": "name",
+ "description": "A human-friendly name associated to a given catalog.",
"type": "string"
- },
- "filters": {
- "description": "Object holding a list of filters",
- "example": {
- "1": [
- "123chars_title"
- ]
- },
- "title": "filters",
- "type": "object"
- },
- "filter_v2": {
- "description": "Object holding a list of filters",
- "example": {
- "1": [
- "123chars_title"
- ]
- },
- "title": "filters",
- "type": "object"
- },
- "type": {
- "$ref": "#/components/schemas/Board"
- },
- "status": {
- "$ref": "#/components/schemas/EntityStatus"
- },
- "feed_profile_id": {
- "description": "id of the feed profile belonging to this catalog product group",
- "pattern": "^\\d+$",
- "title": "feed_profile_id",
- "type": "string"
- },
- "created_at": {
- "description": "Unix timestamp in seconds of when catalog product group was created.",
- "example": 1621350033000,
- "title": "created_at",
- "type": "integer"
- },
- "last_update": {
- "description": "Unix timestamp in seconds of last time catalog product group was updated.",
- "example": 1622742155000,
- "title": "last_update",
- "type": "integer"
- },
- "product_count": {
- "description": "Amount of products in the catalog product group",
- "example": 6,
- "title": "product_count",
- "type": "integer"
- },
- "featured_position": {
- "description": "index of the featured position of the catalog product group",
- "example": 2,
- "title": "featured_position",
- "type": "integer"
}
},
- "title": "CatalogProductGroup",
- "type": "object"
+ "required": [
+ "catalog_type",
+ "name"
+ ]
},
"CatalogsDbItem": {
"type": "object",
@@ -20638,7 +22556,12 @@
"format": "date-time",
"example": "2022-03-14T15:16:34Z"
}
- }
+ },
+ "required": [
+ "id",
+ "created_at",
+ "updated_at"
+ ]
},
"CatalogsCreateReportResponse": {
"type": "object",
@@ -20920,7 +22843,7 @@
"processing_result_id": {
"type": "string",
"pattern": "^\\d+$",
- "description": "Unique identifier of a feed processing result. It can be acquired from the \"id\" field of the \"items\" array within the response of the [List processing results for a given feed](https://developers.pinterest.com/docs/api/v5/#operation/feed_processing_results/list). If not provided, default to most recent completed processing result."
+ "description": "Unique identifier of a feed processing result. It can be acquired from the \"id\" field of the \"items\" array within the response of the [List processing results for a given feed](/docs/api/v5/#operation/feed_processing_results/list). If not provided, default to most recent completed processing result."
}
},
"required": [
@@ -21298,6 +23221,33 @@
}
}
},
+ "CatalogsFeedIngestion": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "example": "01234"
+ },
+ "feed_id": {
+ "type": "string",
+ "example": "56789"
+ },
+ "created_at": {
+ "type": "string",
+ "format": "date-time",
+ "example": "2022-03-14T15:16:34Z"
+ },
+ "status": {
+ "$ref": "#/components/schemas/CatalogsFeedProcessingStatus"
+ }
+ },
+ "required": [
+ "id",
+ "feed_id",
+ "created_at",
+ "status"
+ ]
+ },
"CatalogsFeedIngestionWarnings": {
"type": "object",
"properties": {
@@ -21776,13 +23726,8 @@
"type": "string",
"enum": [
"COMPLETED",
- "COMPLETED_EARLY",
- "DISAPPROVED",
"FAILED",
- "PROCESSING",
- "QUEUED_FOR_PROCESSING",
- "UNDER_APPEAL",
- "UNDER_REVIEW"
+ "PROCESSING"
]
},
"CatalogsFeedProductCounts": {
@@ -22203,6 +24148,17 @@
},
"default_availability": {
"$ref": "#/components/schemas/ProductAvailabilityType"
+ },
+ "status": {
+ "type": "string",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsStatus"
+ },
+ {
+ "default": "ACTIVE"
+ }
+ ]
}
},
"required": [
@@ -22304,6 +24260,17 @@
},
"default_availability": {
"$ref": "#/components/schemas/ProductAvailabilityType"
+ },
+ "status": {
+ "type": "string",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsStatus"
+ },
+ {
+ "default": "ACTIVE"
+ }
+ ]
}
},
"required": [
@@ -22421,6 +24388,17 @@
"nullable": true,
"type": "string",
"pattern": "^\\d+$"
+ },
+ "status": {
+ "type": "string",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsStatus"
+ },
+ {
+ "default": "ACTIVE"
+ }
+ ]
}
},
"required": [
@@ -22596,6 +24574,17 @@
"nullable": true,
"type": "string",
"pattern": "^\\d+$"
+ },
+ "status": {
+ "type": "string",
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsStatus"
+ },
+ {
+ "default": "ACTIVE"
+ }
+ ]
}
},
"required": [
@@ -23326,15 +25315,15 @@
"type": "string"
},
"created_time": {
- "description": "Time of the batch creation: YYYY-MM-DD'T'hh:mm:ssTZD",
- "example": "2020-01-01T20:10:40-00:00",
+ "description": "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss",
+ "example": "2024-01-01T20:10:40",
"type": "string",
"format": "date-time",
"readOnly": true
},
"completed_time": {
- "description": "Time of the batch completion: YYYY-MM-DD'T'hh:mm:ssTZD",
- "example": "2022-03-10T15:37:10-00:00",
+ "description": "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss",
+ "example": "2024-01-01T20:20:00",
"type": "string",
"format": "date-time",
"readOnly": true,
@@ -23368,15 +25357,15 @@
"type": "string"
},
"created_time": {
- "description": "Time of the batch creation: YYYY-MM-DD'T'hh:mm:ssTZD",
- "example": "2020-01-01T20:10:40-00:00",
+ "description": "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss",
+ "example": "2024-01-01T20:10:40",
"type": "string",
"format": "date-time",
"readOnly": true
},
"completed_time": {
- "description": "Time of the batch completion: YYYY-MM-DD'T'hh:mm:ssTZD",
- "example": "2022-03-10T15:37:10-00:00",
+ "description": "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss",
+ "example": "2024-01-01T20:20:00",
"type": "string",
"format": "date-time",
"readOnly": true,
@@ -23410,15 +25399,15 @@
"type": "string"
},
"created_time": {
- "description": "Time of the batch creation: YYYY-MM-DD'T'hh:mm:ssTZD",
- "example": "2020-01-01T20:10:40-00:00",
+ "description": "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss",
+ "example": "2024-01-01T20:10:40",
"type": "string",
"format": "date-time",
"readOnly": true
},
"completed_time": {
- "description": "Time of the batch completion: YYYY-MM-DD'T'hh:mm:ssTZD",
- "example": "2022-03-10T15:37:10-00:00",
+ "description": "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss",
+ "example": "2024-01-01T20:20:00",
"type": "string",
"format": "date-time",
"readOnly": true,
@@ -23451,7 +25440,15 @@
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"filters": {
"$ref": "#/components/schemas/CatalogsItemsPostFilters"
@@ -23504,7 +25501,15 @@
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"operation": {
"$ref": "#/components/schemas/BatchOperation"
@@ -23535,7 +25540,15 @@
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"operation": {
"$ref": "#/components/schemas/BatchOperation"
@@ -23564,7 +25577,15 @@
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"operation": {
"$ref": "#/components/schemas/BatchOperation"
@@ -23593,7 +25614,15 @@
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"operation": {
"$ref": "#/components/schemas/BatchOperation"
@@ -23623,7 +25652,15 @@
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"operation": {
"$ref": "#/components/schemas/BatchOperation"
@@ -23650,25 +25687,149 @@
"type": "object",
"oneOf": [
{
- "description": "Request object to list products for a given feed_id and product group filter.",
- "type": "object",
- "additionalProperties": false,
- "properties": {
- "feed_id": {
- "description": "Catalog Feed id pertaining to the catalog product group filter.",
- "example": "2680059592705",
- "type": "string",
- "pattern": "^\\d+$"
- },
- "filters": {
- "$ref": "#/components/schemas/CatalogsProductGroupFilters"
- }
- },
- "required": [
- "feed_id",
- "filters"
+ "$ref": "#/components/schemas/CatalogsListProductsByFeedBasedFilter"
+ },
+ {
+ "$ref": "#/components/schemas/CatalogsVerticalsListProductsByCatalogBasedFilterRequest"
+ }
+ ]
+ },
+ "CatalogsListProductsByFeedBasedFilter": {
+ "title": "feed based product group",
+ "description": "Request object to list products for a given feed_id and product group filter.",
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "feed_id": {
+ "description": "Catalog Feed id pertaining to the catalog product group filter.",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "filters": {
+ "$ref": "#/components/schemas/CatalogsProductGroupFilters"
+ }
+ },
+ "required": [
+ "feed_id",
+ "filters"
+ ]
+ },
+ "CatalogsVerticalsListProductsByCatalogBasedFilterRequest": {
+ "type": "object",
+ "title": "catalog based product group",
+ "description": "Request object to list products for a given catalog_id and product group filter.",
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest"
+ },
+ {
+ "$ref": "#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest"
+ },
+ {
+ "$ref": "#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "catalog_type",
+ "mapping": {
+ "RETAIL": "#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest",
+ "HOTEL": "#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest",
+ "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest"
+ }
+ }
+ },
+ "CatalogsRetailListProductsByCatalogBasedFilterRequest": {
+ "type": "object",
+ "title": "retail_list_products_by_catalog_based_filter_request",
+ "additionalProperties": false,
+ "description": "Request object to list products for a given retail catalog_id and product group filter.",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "RETAIL"
+ ],
+ "description": "Retail catalog based product group is available only for selected partners at the moment. If you are not eligible, please use feed based one."
+ },
+ "catalog_id": {
+ "description": "Catalog id pertaining to the retail product group.",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "filters": {
+ "$ref": "#/components/schemas/CatalogsProductGroupFilters"
+ },
+ "country": {
+ "$ref": "#/components/schemas/Country"
+ },
+ "locale": {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ }
+ },
+ "required": [
+ "catalog_type",
+ "catalog_id",
+ "filters",
+ "country",
+ "locale"
+ ]
+ },
+ "CatalogsHotelListProductsByCatalogBasedFilterRequest": {
+ "type": "object",
+ "title": "hotel_list_products_by_catalog_based_filter_request",
+ "additionalProperties": false,
+ "description": "Request object to list products for a given hotel catalog_id and product group filter.",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "HOTEL"
+ ]
+ },
+ "catalog_id": {
+ "description": "Catalog id pertaining to the hotel product group.",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "filters": {
+ "$ref": "#/components/schemas/CatalogsHotelProductGroupFilters"
+ }
+ },
+ "required": [
+ "catalog_type",
+ "catalog_id",
+ "filters"
+ ]
+ },
+ "CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest": {
+ "type": "object",
+ "title": "creative_assets_list_products_by_catalog_based_filter_request",
+ "additionalProperties": false,
+ "description": "Request object to list products for a given creative assets catalog_id and product group filter.",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "CREATIVE_ASSETS"
]
+ },
+ "catalog_id": {
+ "description": "Catalog id pertaining to the creative assets product group.",
+ "example": "2680059592705",
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "filters": {
+ "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFilters"
}
+ },
+ "required": [
+ "catalog_type",
+ "catalog_id",
+ "filters"
]
},
"CatalogsLocale": {
@@ -23724,18 +25885,34 @@
},
"CatalogsProduct": {
"type": "object",
+ "description": "Catalogs product for all verticals",
"properties": {
- "metadata": {
- "$ref": "#/components/schemas/CatalogsProductMetadata"
- },
- "pin": {
- "$ref": "#/components/schemas/Pin"
+ "catalog_type": {
+ "$ref": "#/components/schemas/CatalogsType"
}
},
"required": [
- "metadata",
- "pin"
- ]
+ "catalog_type"
+ ],
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsRetailProduct"
+ },
+ {
+ "$ref": "#/components/schemas/CatalogsHotelProduct"
+ },
+ {
+ "$ref": "#/components/schemas/CatalogsCreativeAssetsProduct"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "catalog_type",
+ "mapping": {
+ "RETAIL": "#/components/schemas/CatalogsRetailProduct",
+ "HOTEL": "#/components/schemas/CatalogsHotelProduct",
+ "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsProduct"
+ }
+ }
},
"CatalogsVerticalProductGroup": {
"type": "object",
@@ -24120,6 +26297,7 @@
"$ref": "#/components/schemas/CatalogsProductGroupFilters"
},
"is_featured": {
+ "deprecated": true,
"description": "boolean indicator of whether the product group is being featured or not",
"type": "boolean"
},
@@ -24150,6 +26328,14 @@
"type": "string",
"pattern": "^\\d+$",
"nullable": true
+ },
+ "country": {
+ "type": "string",
+ "nullable": true
+ },
+ "locale": {
+ "type": "string",
+ "nullable": true
}
},
"required": [
@@ -24309,6 +26495,7 @@
"nullable": true
},
"is_featured": {
+ "deprecated": true,
"description": "boolean indicator of whether the product group is being featured or not",
"type": "boolean",
"default": false
@@ -24395,6 +26582,9 @@
{
"$ref": "#/components/schemas/GenderFilter"
},
+ {
+ "$ref": "#/components/schemas/MediaTypeFilter"
+ },
{
"$ref": "#/components/schemas/ProductType4Filter"
},
@@ -24647,11 +26837,95 @@
"values"
]
},
- "CatalogsProductGroupProductCounts": {
- "title": "catalogs_product_group_product_counts",
+ "CatalogsProductGroupProductCountsVertical": {
+ "type": "object",
"description": "Product counts for a CatalogsProductGroup",
+ "properties": {
+ "catalog_type": {
+ "$ref": "#/components/schemas/CatalogsType"
+ }
+ },
+ "required": [
+ "catalog_type"
+ ],
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsRetailProductGroupProductCounts"
+ },
+ {
+ "$ref": "#/components/schemas/CatalogsHotelProductGroupProductCounts"
+ },
+ {
+ "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "catalog_type",
+ "mapping": {
+ "RETAIL": "#/components/schemas/CatalogsRetailProductGroupProductCounts",
+ "HOTEL": "#/components/schemas/CatalogsHotelProductGroupProductCounts",
+ "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts"
+ }
+ }
+ },
+ "CatalogsHotelProductGroupProductCounts": {
+ "title": "catalogs_hotel_product_group_product_counts",
+ "description": "Product counts for a Hotel CatalogsProductGroup",
+ "type": "object",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "HOTEL"
+ ]
+ },
+ "total": {
+ "type": "number",
+ "minimum": 0
+ }
+ },
+ "required": [
+ "catalog_type",
+ "total"
+ ]
+ },
+ "CatalogsCreativeAssetsProductGroupProductCounts": {
+ "title": "catalogs_creative_assets_product_group_product_counts",
+ "description": "Product counts for a Creative Assets CatalogsProductGroup",
"type": "object",
"properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "CREATIVE_ASSETS"
+ ]
+ },
+ "total": {
+ "type": "number",
+ "minimum": 0
+ },
+ "videos": {
+ "type": "number",
+ "minimum": 0
+ }
+ },
+ "required": [
+ "catalog_type",
+ "total",
+ "videos"
+ ]
+ },
+ "CatalogsRetailProductGroupProductCounts": {
+ "title": "catalogs_retail_product_group_product_counts",
+ "description": "Product counts for a Retail CatalogsProductGroup",
+ "type": "object",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "RETAIL"
+ ]
+ },
"in_stock": {
"type": "number",
"minimum": 0
@@ -24667,9 +26941,14 @@
"total": {
"type": "number",
"minimum": 0
+ },
+ "videos": {
+ "type": "number",
+ "minimum": 0
}
},
"required": [
+ "catalog_type",
"in_stock",
"out_of_stock",
"preorder",
@@ -24714,6 +26993,7 @@
"nullable": true
},
"is_featured": {
+ "deprecated": true,
"description": "boolean indicator of whether the product group is being featured or not",
"type": "boolean"
},
@@ -24722,9 +27002,31 @@
}
}
},
- "CatalogsProductMetadata": {
+ "CatalogsRetailProduct": {
"type": "object",
- "description": "Product metadata entity",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "RETAIL"
+ ]
+ },
+ "metadata": {
+ "$ref": "#/components/schemas/CatalogsRetailProductMetadata"
+ },
+ "pin": {
+ "$ref": "#/components/schemas/Pin"
+ }
+ },
+ "required": [
+ "catalog_type",
+ "metadata",
+ "pin"
+ ]
+ },
+ "CatalogsRetailProductMetadata": {
+ "type": "object",
+ "description": "Retail product metadata entity",
"properties": {
"item_id": {
"description": "The user-created unique ID that represents the product.",
@@ -24967,13 +27269,24 @@
"additionalProperties": false,
"properties": {
"catalog_type": {
- "$ref": "#/components/schemas/CatalogsType"
+ "type": "string",
+ "enum": [
+ "RETAIL"
+ ]
},
"country": {
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"items": {
"minItems": 1,
@@ -25079,10 +27392,7 @@
"operation": {
"type": "string",
"enum": [
- "CREATE",
- "UPDATE",
- "UPSERT",
- "DELETE"
+ "CREATE"
]
},
"attributes": {
@@ -25107,10 +27417,7 @@
"operation": {
"type": "string",
"enum": [
- "CREATE",
- "UPDATE",
- "UPSERT",
- "DELETE"
+ "UPDATE"
]
},
"attributes": {
@@ -25188,10 +27495,7 @@
"operation": {
"type": "string",
"enum": [
- "CREATE",
- "UPDATE",
- "UPSERT",
- "DELETE"
+ "UPSERT"
]
},
"attributes": {
@@ -25216,9 +27520,6 @@
"operation": {
"type": "string",
"enum": [
- "CREATE",
- "UPDATE",
- "UPSERT",
"DELETE"
]
}
@@ -25234,13 +27535,24 @@
"additionalProperties": false,
"properties": {
"catalog_type": {
- "$ref": "#/components/schemas/CatalogsType"
+ "type": "string",
+ "enum": [
+ "HOTEL"
+ ]
},
"country": {
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"items": {
"minItems": 1,
@@ -25386,6 +27698,42 @@
}
}
},
+ "CatalogsHotelProduct": {
+ "type": "object",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "HOTEL"
+ ]
+ },
+ "metadata": {
+ "$ref": "#/components/schemas/CatalogsHotelProductMetadata"
+ },
+ "pin": {
+ "$ref": "#/components/schemas/Pin"
+ }
+ },
+ "required": [
+ "catalog_type",
+ "metadata",
+ "pin"
+ ]
+ },
+ "CatalogsHotelProductMetadata": {
+ "type": "object",
+ "description": "Hotel product metadata entity",
+ "properties": {
+ "hotel_id": {
+ "description": "The user-created unique ID that represents the hotel item.",
+ "example": "123abc",
+ "type": "string"
+ }
+ },
+ "required": [
+ "hotel_id"
+ ]
+ },
"CatalogsUpdatableHotelAttributes": {
"type": "object",
"properties": {
@@ -25478,19 +27826,79 @@
}
}
},
+ "CatalogsCreativeAssetsProductMetadata": {
+ "type": "object",
+ "description": "Creative assets product metadata entity",
+ "properties": {
+ "creative_assets_id": {
+ "description": "The user-created unique ID that represents the creative assets item.",
+ "example": "123abc",
+ "type": "string"
+ },
+ "visibility": {
+ "$ref": "#/components/schemas/CreativeAssetsVisibilityType"
+ }
+ },
+ "required": [
+ "creative_assets_id",
+ "visibility"
+ ]
+ },
+ "CatalogsCreativeAssetsProduct": {
+ "type": "object",
+ "properties": {
+ "catalog_type": {
+ "type": "string",
+ "enum": [
+ "CREATIVE_ASSETS"
+ ]
+ },
+ "metadata": {
+ "$ref": "#/components/schemas/CatalogsCreativeAssetsProductMetadata"
+ },
+ "pin": {
+ "$ref": "#/components/schemas/Pin"
+ }
+ },
+ "required": [
+ "catalog_type",
+ "metadata",
+ "pin"
+ ]
+ },
+ "CreativeAssetsVisibilityType": {
+ "description": "Creative assets visibility.",
+ "nullable": false,
+ "type": "string",
+ "enum": [
+ "VISIBLE",
+ "HIDDEN"
+ ]
+ },
"CatalogsCreativeAssetsBatchRequest": {
"description": "Request object to update catalogs creative assets items",
"type": "object",
"additionalProperties": false,
"properties": {
"catalog_type": {
- "$ref": "#/components/schemas/CatalogsType"
+ "type": "string",
+ "enum": [
+ "CREATIVE_ASSETS"
+ ]
},
"country": {
"$ref": "#/components/schemas/Country"
},
"language": {
- "$ref": "#/components/schemas/Language"
+ "description": "We recommend using the CatalogsLocale values.",
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CatalogsLocale"
+ },
+ {
+ "$ref": "#/components/schemas/Language"
+ }
+ ]
},
"items": {
"minItems": 1,
@@ -25889,12 +28297,12 @@
"additionalProperties": false,
"properties": {
"event_name": {
- "description": "The type of the user event. Please use the right event_name otherwise the event won’t be accepted and show up correctly in reports.
add_to_cart checkout custom lead page_visit search signup view_category watch_video",
+ "description": "The type of the user event. Please use the right event_name otherwise the event won't be accepted and show up correctly in reports.\n
add_to_cartcheckoutcustomleadpage_visitsearchsignupview_categorywatch_videoapp_android app_ios web offline",
+ "description": "\n The source indicating where the conversion event occurred.\n
app_androidapp_iosweboffline<= 2,000 characters
\nHosted link to the product video.
\nFile types for linked videos must be .mp4, .mov or .m4v.
\nFile size cannot exceed 2GB.
", + "example": "https://www.example.com/cat/womens-clothing/denim-shirt-0294.mp4", + "type": "string", + "nullable": true } } }, @@ -28901,6 +31479,12 @@ "nullable": false } ] + }, + "video_link": { + "description": "<= 2,000 characters
\nHosted link to the product video.
\nFile types for linked videos must be .mp4, .mov or .m4v.
\nFile size cannot exceed 2GB.
", + "example": "https://www.example.com/cat/womens-clothing/denim-shirt-0294.mp4", + "type": "string", + "nullable": true } } }, @@ -29321,9 +31905,8 @@ }, "bid": { "type": "integer", - "minimum": 1, - "description": "Keyword custom bid in microcurrency - null if inherited from parent ad group.", - "example": 200000, + "description": "Note: bid field has been deprecated. Input will not be set and field will return null. Keyword custom bid in microcurrency - null if inherited from parent ad group.", + "example": null, "nullable": true, "title": "bid" } @@ -29336,7 +31919,7 @@ "type": "object", "properties": { "keywords": { - "description": "Keywords to update. Object array. Each object has 3 possible fields:NO_SPLIT.",
+ "description": "Pin metric types to get data for. VIDEO_MRC_VIEW are Video views, VIDEO_V50_WATCH_TIME is Total play time. If Pin was created before 2023-03-20, Profile visits and Follows will only be available for Idea Pins. These metrics are available for all Pin formats since then. Keep in mind this cannot have ALL if split_field is set to any value other than NO_SPLIT.",
"explode": false,
"in": "query",
"name": "metric_types",
@@ -38658,7 +42191,9 @@
"SAVE",
"SAVE_RATE",
"TOTAL_COMMENTS",
- "TOTAL_REACTIONS"
+ "TOTAL_REACTIONS",
+ "USER_FOLLOW",
+ "PROFILE_VISIT"
]
},
{
@@ -38714,10 +42249,7 @@
"ADS_STANDARD",
"ADS_PRODUCT",
"ADS_VIDEO",
- "ADS_IDEA",
- "PRODUCT",
- "REGULAR",
- "VIDEO"
+ "ADS_IDEA"
],
"type": "string"
}
@@ -38783,6 +42315,15 @@
"type": "string"
}
},
+ "query_account_type": {
+ "description": "Filter accounts by account type.",
+ "in": "query",
+ "name": "account_type",
+ "required": true,
+ "schema": {
+ "$ref": "#/components/schemas/AudienceAccountType"
+ }
+ },
"query_report_type": {
"name": "report_type",
"description": "Report type.",
@@ -38796,6 +42337,21 @@
]
}
},
+ "query_required_pin_ids": {
+ "name": "pin_ids",
+ "description": "List of Pin IDs.",
+ "in": "query",
+ "required": true,
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "pattern": "^\\d+$"
+ },
+ "minItems": 1,
+ "maxItems": 100
+ }
+ },
"query_required_search_query": {
"description": "Search query. Can contain pin description keywords or comma-separated pin IDs.",
"in": "query",
@@ -38815,7 +42371,8 @@
"type": "string",
"enum": [
"AD_ACCOUNT",
- "PROFILE"
+ "PROFILE",
+ "ASSET_GROUP"
],
"default": "AD_ACCOUNT",
"example": "AD_ACCOUNT"
diff --git a/v5/openapi.yaml b/v5/openapi.yaml
index f7e629a..54b810e 100644
--- a/v5/openapi.yaml
+++ b/v5/openapi.yaml
@@ -1,6 +1,6 @@
openapi: 3.0.3
info:
- version: 5.13.0
+ version: 5.14.0
title: Pinterest REST API
description: Pinterest's REST API
contact:
@@ -20,7 +20,7 @@ tags:
Note: If the current operation_user_account (defined by the access token)
has access to another user's Ad Accounts via
- Pinterest Business Access,
+ Pinterest Business Access,
you can modify your request to use the current operation_user_account's
permissions to those Ad Accounts by including the ad_account_id in the path
parameters for the request (e.g. .../?ad_account_id=12345&...).
@@ -28,8 +28,16 @@ tags:
description: View, create or update ad groups.
- name: ads
description: View, create or update ads.
+- name: advanced_auction
+ description: View, create, or update advanced auction item bid options.
- name: audience_insights
description: View audience insights.
+- name: audience_sharing
+ description: |-
+ View, share, or revoke shared audiences.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.
+ - The request must contain either ad_ids or both campaign_ids and pin_ids.
- 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: ads/analytics
@@ -772,13 +776,25 @@ paths:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_start_date'
- $ref: '#/components/parameters/query_end_date'
- - $ref: '#/components/parameters/query_ad_ids_required'
+ - $ref: '#/components/parameters/query_ad_ids'
- $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'
+ - name: pin_ids
+ description: List of Pin IDs.
+ in: query
+ required: false
+ schema:
+ type: array
+ items:
+ type: string
+ pattern: ^\d+$
+ minItems: 1
+ maxItems: 100
+ - $ref: '#/components/parameters/query_campaign_ids'
responses:
'200':
content:
@@ -809,7 +825,7 @@ paths:
description: |-
Returns the list of discounts applied to the account.
- This endpoint might not be available to all apps. Learn more.
+ This endpoint might not be available to all apps. Learn more.
operationId: ads_credits_discounts/get
security:
- pinterest_oauth2:
@@ -849,7 +865,7 @@ paths:
description: |-
Redeem ads credit on behalf of the ad account id and apply it towards billing.
- This endpoint might not be available to all apps. Learn more.
+ This endpoint might not be available to all apps. Learn more.
tags:
- billing
operationId: ads_credit/redeem
@@ -915,7 +931,7 @@ paths:
- $ref: '#/components/parameters/query_ad_ids_required'
- $ref: '#/components/parameters/query_start_date'
- $ref: '#/components/parameters/query_end_date'
- - $ref: '#/components/parameters/query_targeting_types'
+ - $ref: '#/components/parameters/query_ad_targeting_types'
- $ref: '#/components/parameters/query_columns'
- $ref: '#/components/parameters/query_granularity'
- $ref: '#/components/parameters/query_conversion_attribution_click_window_days'
@@ -944,8 +960,7 @@ paths:
description: |-
Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will
contain additional information from the Ad Review process.
- For more information about our policies and rejection reasons see the Pinterest advertising standards.
+ For more information about our policies and rejection reasons see the Pinterest advertising standards.
operationId: ads/get
security:
- pinterest_oauth2:
@@ -1077,9 +1092,7 @@ paths:
- ASCENDING
- DESCENDING
- $ref: '#/components/parameters/query_page_size'
- - description: |-
- This feature is currently in beta and not available to all apps.
- Filter audiences by ownership type.
+ - description: Filter audiences by ownership type.
in: query
name: ownership_type
required: false
@@ -1260,6 +1273,155 @@ paths:
$ref: '#/components/schemas/Error'
tags:
- audiences
+ /ad_accounts/{ad_account_id}/audiences/shared/accounts:
+ get:
+ summary: List accounts with access to an audience owned by an ad account
+ description: List all ad accounts and/or businesses that have access to a specific
+ audience. The audience must be owned by the requesting ad account.
+ operationId: ad_accounts_audiences_shared_accounts/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_audience_id'
+ - $ref: '#/components/parameters/query_account_type'
+ - $ref: '#/components/parameters/query_page_size'
+ - $ref: '#/components/parameters/query_bookmark'
+ responses:
+ '200':
+ description: Success
+ content:
+ application/json:
+ schema:
+ allOf:
+ - $ref: '#/components/schemas/Paginated'
+ - type: object
+ properties:
+ items:
+ type: array
+ items:
+ $ref: '#/components/schemas/SharedAudienceAccount'
+ '400':
+ description: Invalid ad account audiences shared accounts parameters.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ example:
+ code: 400
+ message: Invalid ad account audiences shared accounts parameters.
+ '404':
+ description: Shared accounts not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ default:
+ description: Unexpected error.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ tags:
+ - audience_sharing
+ /ad_accounts/{ad_account_id}/audiences/ad_accounts/shared:
+ patch:
+ summary: Update audience sharing between ad accounts
+ description: From an ad account, share a specific audience with another ad account,
+ or revoke access to a previously shared audience. Only the audience owner
+ account can share the audience. The recipient ad account(s) must be in the
+ same Pinterest
+ Business Hierarchy as the business owner of the ad account.A customer list is one\ \ of the four types of Pinterest audiences: for more information, see Audience targeting\nor the Audience targeting\nor the Audiences section of the ads management guide.
\n\ \Please review our requirements for what type of information is allowed\ @@ -1947,7 +2109,7 @@ paths:
Get a set of customer lists including id and name based on the filters provided.
(Customer lists are a type of audience.) For more information, see Audience targeting - or the Audiences + or the Audiences section of the ads management guide.
operationId: customer_lists/list security: @@ -2019,7 +2181,7 @@ paths: \ be added to your \u201CCUSTOMER_LIST\u201D audience. Your original list\ \ of records\n to add will be deleted when the matching process is complete.\n\For more information, see Audience targeting\nor the Audience targeting\nor the Audiences\nsection of the ads management guide.
" operationId: customer_lists/update security: @@ -2057,7 +2219,7 @@ paths: summary: Send conversions description: |- The Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline conversions) based on theirad_account_id. The request body should be a JSON object.
- - This endpoint requires an access_token be generated through Ads Manager. Review the Conversions Guide for more details.
+ - This endpoint requires an access_token be generated through Ads Manager. Review the Conversions Guide for more details. (Note that the authorization header required is Authorization: Bearer <access_token>).
- 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, Audience, Campaign. (Note that the token can be used across multiple ad accounts under an user ID.)
- This endpoint has a rate limit of 5,000 calls per minute per ad account.
- If the merchant is submitting this information using both Pinterest conversion tags and the Pinterest API, Pinterest will remove duplicate information before reporting. (Note that events that took place offline cannot be deduplicated.)
@@ -2201,7 +2363,7 @@ paths:
description: |-
Get a list of keywords based on the filters provided. If no filter is provided, it will default to the ad_account_id filter, which means it will only return keywords that specifically have parent_id set to the ad_account_id. Note: Keywords can have ad_account_ids, campaign_ids, and ad_group_ids set as their parent_ids. Keywords created through Ads Manager will have their parent_id set to an ad_group_id, not ad_account_id.
For more information, see Keyword targeting.
-Notes:
For more information on match types, see match type enums.
+Notes:
For more information on match types, see match type enums.
Returns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } } Create keywords for following entity types(advertiser, campaign, ad group or ad).
For more information, see Keyword targeting.
-Notes:
For more information on match types, see match type enums.
+Notes:
For more information on match types, see match type enums.
Returns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } } Rate limit: WRITE.
+Rate limit: WRITE.
operationId: keywords/create security: - pinterest_oauth2: @@ -2342,11 +2504,11 @@ paths: - keywords /ad_accounts/{ad_account_id}/lead_forms: get: - summary: Get lead forms + summary: List lead forms description: |- This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager. - Gets all Lead Forms associated with an ad account ID. + List lead forms associated with an ad account ID. For more, see Lead ads. operationId: lead_forms/list @@ -2391,6 +2553,109 @@ paths: $ref: '#/components/schemas/Error' tags: - lead_forms + post: + x-sandbox: disabled + description: "This feature is currently in beta and not available to\ + \ all apps, if you're interested in joining the beta, please reach out to\ + \ your Pinterest account manager.\n\nCreate lead forms. Lead forms\ + \ are used in lead ads and allow you to control what text appears on the lead\ + \ form\u2019 s description, questions and confirmation sections.\n\nFor more,\ + \ see Lead ads." + summary: Create lead forms + operationId: lead_forms/create + security: + - pinterest_oauth2: + - ads:write + x-ratelimit-category: ads_write + parameters: + - $ref: '#/components/parameters/path_ad_account_id' + requestBody: + content: + application/json: + schema: + items: + $ref: '#/components/schemas/LeadFormCreateRequest' + maxItems: 30 + minItems: 1 + type: array + description: List of lead forms to create, size limit [1, 30]. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LeadFormArrayResponse' + description: Success + '400': + description: Invalid ad account lead forms parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + code: 400 + message: Invalid ad account lead forms parameters. + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - lead_forms + patch: + x-sandbox: disabled + description: |- + This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager. + + Update lead forms. Lead ads help you reach people who are actively looking for, and interested in, your goods and services. The lead form can be associated with an ad to allow people to fill out the form. + + For more, see Lead ads. + summary: Update lead forms + operationId: lead_forms/update + security: + - pinterest_oauth2: + - ads:write + x-ratelimit-category: ads_write + parameters: + - $ref: '#/components/parameters/path_ad_account_id' + requestBody: + content: + application/json: + schema: + items: + $ref: '#/components/schemas/LeadFormUpdateRequest' + maxItems: 30 + minItems: 1 + type: array + description: List of lead forms to update, size limit [1, 30]. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LeadFormArrayResponse' + description: Success + '400': + description: Invalid ad account lead forms parameters. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + code: 400 + message: Invalid ad account lead forms parameters. + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - lead_forms /ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}: get: summary: Get lead form by id @@ -2449,7 +2714,7 @@ paths: Create lead form test data based on the list of answers provided as part of the body. - List of answers should follow the questions creation order. - This endpoint is currently in beta and not available to all apps. Learn more. + This endpoint is currently in beta and not available to all apps. Learn more. operationId: lead_form_test/create security: - pinterest_oauth2: @@ -2502,15 +2767,14 @@ paths: /ad_accounts/{ad_account_id}/leads/subscriptions: post: summary: Create lead ads subscription - description: "Create a lead ads webhook subscription.\nSubscriptions allow Pinterest\ - \ to deliver lead data from Ads Manager directly to the subscriber. Subscriptions\ - \ can exist for a specific lead form or at ad account level. \n- Only requests\ - \ for the OWNER or ADMIN of the ad_account will be allowed.\n- Advertisers\ - \ can set up multiple integrations using ad_account_id + lead_form_id but\ - \ only one integration per unique records.\n- For data security, egress lead\ - \ data is encrypted with AES-256-GCM.\n\nThis endpoint is currently\ - \ in beta and not available to all apps. Learn\ - \ more." + description: |- + Create a lead ads webhook subscription. + Subscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can exist for a specific lead form or at ad account level. + - Only requests for the OWNER or ADMIN of the ad_account will be allowed. + - Advertisers can set up multiple integrations using ad_account_id + lead_form_id but only one integration per unique records. + - For data security, egress lead data is encrypted with AES-256-GCM. + + This endpoint is currently in beta and not available to all apps. Learn more. tags: - lead_ads operationId: ad_accounts_subscriptions/post @@ -2567,7 +2831,7 @@ paths: Get the advertiser's list of lead ads subscriptions. - Only requests for the OWNER or ADMIN of the ad_account will be allowed. - This endpoint is currently in beta and not available to all apps. Learn more. + This endpoint is currently in beta and not available to all apps. Learn more. operationId: ad_accounts_subscriptions/get_list security: - pinterest_oauth2: @@ -2618,7 +2882,7 @@ paths: Get a specific lead ads subscription record. - Only requests for the OWNER or ADMIN of the ad_account will be allowed. - This endpoint is currently in beta and not available to all apps. Learn more. + This endpoint is currently in beta and not available to all apps. Learn more. operationId: ad_accounts_subscriptions/get_by_id security: - pinterest_oauth2: @@ -2680,7 +2944,7 @@ paths: Delete an existing lead ads webhook subscription by ID. - Only requests for the OWNER or ADMIN of the ad_account will be allowed. - This endpoint is currently in beta and not available to all apps. Learn more. + This endpoint is currently in beta and not available to all apps. Learn more. operationId: ad_accounts_subscriptions/del_by_id security: - pinterest_oauth2: @@ -2732,37 +2996,47 @@ paths: $ref: '#/components/schemas/Error' tags: - lead_ads - /ad_accounts/{ad_account_id}/mmm_reports: - get: - summary: Get advertiser Marketing Mix Modeling (MMM) report. + /ad_accounts/{ad_account_id}/leads_export: + post: + x-sandbox: disabled description: |- - Get an mmm report for an ad account. This returns a URL to an mmm metrics report given a token returned from the - create mmm report endpoint. - operationId: analytics/get_mmm_report + This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager. + + Create an export of leads collected from a lead ad. This returns a lead_export_id token that you can use to download the export when it is ready. + + Note: Lead ad data will be available up to 30 days after the lead has been submitted. + + For more, see Lead ads. + summary: Create a request to export leads collected from a lead ad + operationId: leads_export/create security: - pinterest_oauth2: - - ads:read - x-ratelimit-category: ads_read - x-sandbox: disabled + - ads:write + x-ratelimit-category: ads_write parameters: - $ref: '#/components/parameters/path_ad_account_id' - - $ref: '#/components/parameters/query_token_required' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LeadsExportCreateRequest' + required: true responses: '200': content: application/json: schema: - $ref: '#/components/schemas/GetMMMReportResponse' + $ref: '#/components/schemas/LeadsExportCreateResponse' description: Success '400': - description: Invalid ad account ads analytics parameters. + description: Invalid ad account parameter. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 400 - message: Invalid ad account ads analytics parameters. + message: Invalid ad account parameter. default: description: Unexpected error content: @@ -2770,16 +3044,115 @@ paths: schema: $ref: '#/components/schemas/Error' tags: - - ad_accounts - post: - summary: Create a request for a Marketing Mix Modeling (MMM) report + - leads_export + /ad_accounts/{ad_account_id}/leads_export/{leads_export_id}: + get: + x-sandbox: disabled description: |- - This creates an asynchronous mmm report based on the given request. It returns a token that you can use to download - the report when it is ready. NOTE: An additional limit of 5 queries per minute per advertiser applies to this endpoint while it's in beta release. - operationId: analytics/create_mmm_report - security: - - pinterest_oauth2: - - ads:read + This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager. + + Get the export of leads collected from a lead ad. This returns a URL to a list of lead export given a lead_export_id token returned from the create a lead export call. You can use the URL to download the report. + + Note: Lead ad data will be available up to 30 days after the lead has been submitted. + + For more, see Lead ads. + summary: Get the lead export from the lead export create call + operationId: leads_export/get + security: + - pinterest_oauth2: + - ads:read + x-ratelimit-category: ads_read + parameters: + - $ref: '#/components/parameters/path_ad_account_id' + - name: leads_export_id + in: path + description: lead_export_id token returned from the create a lead export endpoint + example: '123755885175' + required: true + schema: + type: string + pattern: ^\d+$ + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LeadsExportResponseData' + description: Success + '400': + description: Invalid ad account parameter. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + code: 400 + message: Invalid ad account parameter. + '404': + description: Invalid leads export id parameter. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + code: 404 + message: Invalid leads export id parameter. + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - leads_export + /ad_accounts/{ad_account_id}/mmm_reports: + get: + summary: Get advertiser Marketing Mix Modeling (MMM) report. + description: |- + Get an mmm report for an ad account. This returns a URL to an mmm metrics report given a token returned from the + create mmm report endpoint. + operationId: analytics/get_mmm_report + 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_token_required' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetMMMReportResponse' + 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: + - ad_accounts + post: + summary: Create a request for a Marketing Mix Modeling (MMM) report + description: |- + This creates an asynchronous mmm report based on the given request. It returns a token that you can use to download + the report when it is ready. NOTE: An additional limit of 5 queries per minute per advertiser applies to this endpoint while it's in beta release. + operationId: analytics/create_mmm_report + security: + - pinterest_oauth2: + - ads:read x-ratelimit-category: ads_analytics x-sandbox: disabled parameters: @@ -3069,65 +3442,6 @@ paths: $ref: '#/components/schemas/Error' tags: - product_group_promotions - /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_groups /ad_accounts/{ad_account_id}/reports: get: summary: Get the account analytics report created by the async call @@ -3217,11 +3531,12 @@ paths: /ad_accounts/{ad_account_id}/sandbox: delete: summary: Delete ads data for ad account in API Sandbox - description: "Delete an ad account and all the ads data associated with that\ - \ account. \nA string message is returned indicating the status of the delete\ - \ operation.\n\nNote: This endpoint is only allowed in the Pinterest API Sandbox\ - \ (https://api-sandbox.pinterest.com/v5). \nGo to https://developers.pinterest.com/docs/dev-tools/sandbox/\ - \ for more information." + description: |- + Delete an ad account and all the ads data associated with that account. + A string message is returned indicating the status of the delete operation. + + Note: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5). + Go to /docs/developer-tools/sandbox/ for more information. operationId: sandbox/delete security: - pinterest_oauth2: @@ -3824,97 +4139,257 @@ paths: summary: Get terms of service tags: - terms_of_service - /boards: - get: - summary: List boards + /advanced_auction/items/get: + post: + summary: Get item bid options (POST) description: |- - Get a list of the boards owned by the "operation user_account" + group boards where this account is a collaborator - Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - Optional: Specify a privacy type (public, protected, or secret) to indicate which boards to return. - - If no privacy is specified, all boards that can be returned (based on the scopes of the token and ad_account role if applicable) will be returned. - tags: - - boards - operationId: boards/list + Get the bid options for a batch of retail catalog items. + + The catalog must be owned by the "operation user_account". See detailed documentation here. By default, the "operation user_account" is the token user_account. + + Optional: Business Access: Specify anad_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`.
+
+ This endpoint is not available to all users.
+ operationId: advanced_auction_items_get/post
+ x-ratelimit-category: advanced_auction_read
+ x-sandbox: enabled
security:
- pinterest_oauth2:
- - boards:read
- x-ratelimit-category: org_read
- x-sandbox: enabled
- x-codeSamples:
- - lang: cURL
- label: curl
- source: |
- curl --location --request GET 'https://api.pinterest.com/v5/boards' \
- --header 'Authorization: Bearer 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`.
+
+ This endpoint is not available to all users.
+ operationId: advanced_auction_items_submit/post
+ x-ratelimit-category: advanced_auction_write
+ x-sandbox: enabled
+ security:
+ - pinterest_oauth2:
+ - ads:write
+ - catalogs:read
+ parameters:
+ - $ref: '#/components/parameters/query_ad_account_id'
+ requestBody:
+ description: Request object used to upsert or delete bid options for a batch
+ of retail catalog items
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AdvancedAuctionItemsSubmitRequest'
+ responses:
+ '200':
+ description: Response containing the results of the item bid options operations
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AdvancedAuctionProcessedItems'
+ '400':
+ description: Invalid request parameters.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ examples:
+ InvalidRequest:
+ value:
+ code: 1
+ message: 'Invalid request: {''catalog_id'': ''1234''} list of
+ item bid option operations not provided'
+ '401':
+ description: Not authenticated to post item bid options
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ examples:
+ UnauthenticatedAccess:
+ value:
+ code: 2
+ message: Authentication failed.
+ '403':
+ description: Not authorized to post item bid options
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ '500':
+ description: Internal error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ default:
+ description: Unexpected error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ tags:
+ - advanced_auction
+ /boards:
+ get:
+ summary: List boards
+ description: |-
+ Get a list of the boards owned by the "operation user_account" + group boards where this account is a collaborator
+ Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
+ Optional: Specify a privacy type (public, protected, or secret) to indicate which boards to return.
+ - If no privacy is specified, all boards that can be returned (based on the scopes of the token and ad_account role if applicable) will be returned.
+ tags:
+ - boards
+ operationId: boards/list
+ security:
+ - pinterest_oauth2:
+ - boards:read
+ - client_credentials:
+ - boards:read
+ x-ratelimit-category: org_read
+ x-sandbox: enabled
+ x-codeSamples:
+ - lang: cURL
+ label: curl
+ source: |
+ curl --location --request GET 'https://api.pinterest.com/v5/boards' \
+ --header 'Authorization: Bearer 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
+ Learn more
operationId: catalogs/list
security:
- pinterest_oauth2:
@@ -5592,6 +6426,69 @@ paths:
$ref: '#/components/schemas/Error'
tags:
- catalogs
+ post:
+ x-ratelimit-category: catalogs_write
+ summary: Create catalog
+ description: |-
+ Create a new catalog 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: this API only supports the catalog type of HOTEL for now.
+ operationId: catalogs/create
+ security:
+ - pinterest_oauth2:
+ - catalogs:write
+ x-sandbox: enabled
+ parameters:
+ - $ref: '#/components/parameters/query_ad_account_id'
+ requestBody:
+ description: Request object used to created a feed.
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogsCreateRequest'
+ responses:
+ '200':
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Catalog'
+ description: Success
+ '400':
+ description: Invalid parameters.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ examples:
+ InvalidRequest:
+ value:
+ code: 1
+ message: 'Invalid request: ...'
+ '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.
+ default:
+ description: Unexpected error.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ tags:
+ - catalogs
/catalogs/feeds:
get:
x-ratelimit-category: catalogs_read
@@ -5602,11 +6499,13 @@ paths:
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.
- For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
+ For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
operationId: feeds/list
security:
- pinterest_oauth2:
- catalogs:read
+ - client_credentials:
+ - catalogs:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_bookmark'
@@ -5670,15 +6569,18 @@ paths:
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.
- For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
+ For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
- Note: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
- If access is required, please contact your partner manager.
+ Note: Access to the Creative Assets catalog type is restricted to a specific group of users.
+ If you require access, please reach out to your partner manager.
operationId: feeds/create
security:
- pinterest_oauth2:
- catalogs:read
- catalogs:write
+ - client_credentials:
+ - catalogs:read
+ - catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_ad_account_id'
@@ -5734,7 +6636,9 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
'409':
description: User website required.
content:
@@ -5790,11 +6694,13 @@ paths:
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.
- For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
+ For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
operationId: feeds/get
security:
- pinterest_oauth2:
- catalogs:read
+ - client_credentials:
+ - catalogs:read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
@@ -5857,15 +6763,18 @@ paths:
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.
- For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
+ For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
- Note: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
- If access is required, please contact your partner manager.
+ Note: Access to the Creative Assets catalog type is restricted to a specific group of users.
+ If you require access, please reach out to your partner manager.
operationId: feeds/update
security:
- pinterest_oauth2:
- catalogs:read
- catalogs:write
+ - client_credentials:
+ - catalogs:read
+ - catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
@@ -5907,12 +6816,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Data feed not found.
content:
@@ -5941,12 +6852,15 @@ paths:
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.
- For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
+ For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
operationId: feeds/delete
security:
- pinterest_oauth2:
- catalogs:read
- catalogs:write
+ - client_credentials:
+ - catalogs:read
+ - catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_catalogs_feed_id'
@@ -5976,12 +6890,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Data feed not found.
content:
@@ -6015,16 +6931,15 @@ paths:
/catalogs/feeds/{feed_id}/ingest:
post:
x-ratelimit-category: catalogs_write
- summary: Ingest items for a given feed
+ summary: Ingest feed items
description: |-
Ingest items for a given feed owned by the "operation 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
+ Learn more
- Note: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5).
- Go to https://developers.pinterest.com/docs/dev-tools/sandbox/ for more information.
+ Note: This endpoint is restricted to a specific group of users. If you require access, please reach out to your partner manager.
operationId: feeds/ingest
security:
- pinterest_oauth2:
@@ -6034,8 +6949,12 @@ paths:
- $ref: '#/components/parameters/path_catalogs_feed_id'
- $ref: '#/components/parameters/query_ad_account_id'
responses:
- '204':
+ '200':
description: The ingestion process was successfully started.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogsFeedIngestion'
'400':
description: Invalid feed parameters.
content:
@@ -6058,12 +6977,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Data feed not found.
content:
@@ -6086,14 +7007,14 @@ paths:
/catalogs/feeds/{feed_id}/processing_results:
get:
x-ratelimit-category: catalogs_read
- summary: List processing results for a given feed
+ summary: List feed processing results
description: |-
Fetch a feed processing results owned by the "operation user_account". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future.
- 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
+ Learn more
operationId: feed_processing_results/list
security:
- pinterest_oauth2:
@@ -6162,14 +7083,16 @@ paths:
/catalogs/processing_results/{processing_result_id}/item_issues:
get:
x-ratelimit-category: catalogs_read
- summary: List item issues for a given processing result
+ summary: List item issues
description: |-
List item validation issues for a given feed processing result owned by the "operation user_account". Up to 20 random samples of affected items are returned for each error and warning code. Please note that for now query parameters 'item_numbers' and 'item_validation_issue' cannot be used simultaneously until it is implemented in some release in the future.
- 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: To get a list of all affected items instead of sampled issues, please refer to Build catalogs report and Get catalogs report endpoints. Moreover, they support multiple types of catalogs.
+
+ Learn more
operationId: items_issues/list
security:
- pinterest_oauth2:
@@ -6239,15 +7162,15 @@ paths:
- catalogs
/catalogs/items:
get:
+ deprecated: true
summary: Get catalogs items
description: |-
- Get the items of the catalog owned by the "operation user_account". See detailed documentation here.
+ Get the items of the catalog owned by the "operation user_account". See detailed documentation here.
- 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: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
- If access is required, please contact your partner manager.
+ Note: this endpoint is deprecated and will be deleted soon. Please use Get catalogs items (POST) instead.
operationId: items/get
security:
- pinterest_oauth2:
@@ -6306,13 +7229,13 @@ paths:
post:
summary: Get catalogs items (POST)
description: |-
- Get the items of the catalog owned by the "operation user_account". See detailed documentation here.
+ Get the items of the catalog owned by the "operation user_account". See detailed documentation here.
- 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: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
- If access is required, please contact your partner manager.
+ Note: Access to the Creative Assets catalog type is restricted to a specific group of users.
+ If you require access, please reach out to your partner manager.
operationId: items/post
security:
- pinterest_oauth2:
@@ -6377,13 +7300,15 @@ paths:
post:
summary: Operate on item batch
description: |-
- This endpoint supports multiple operations on a set of one or more catalog items owned by the "operation user_account". See detailed documentation here.
+ This endpoint supports multiple operations on a set of one or more catalog items owned by the "operation user_account". See detailed documentation here.
- 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: The catalog type of Creative Assets is only allowed in the Pinterest API Sandbox.
- If access is required, please contact your partner manager.
+ Note:
+ - Access to the Creative Assets catalog type is restricted to a specific group of users.
+ If you require access, please reach out to your partner manager.
+ - The item UPSERT operation is restricted to users without a feed data source. If you plan to migrate item ingestion from feeds to the API, please reach out to your partner manager to get assistance.
operationId: items_batch/post
x-ratelimit-category: catalogs_write
x-sandbox: enabled
@@ -6391,6 +7316,9 @@ paths:
- pinterest_oauth2:
- catalogs:read
- catalogs:write
+ - client_credentials:
+ - catalogs:read
+ - catalogs:write
parameters:
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
@@ -6451,9 +7379,9 @@ paths:
- catalogs
/catalogs/items/batch/{batch_id}:
get:
- summary: Get catalogs item batch status
+ summary: Get item batch status
description: |-
- Get a single catalogs items batch owned by the "operating user_account". See detailed documentation here.
+ Get a single catalogs items batch owned by the "operating user_account". See detailed documentation here.
- 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.
@@ -6461,6 +7389,8 @@ paths:
security:
- pinterest_oauth2:
- catalogs:read
+ - client_credentials:
+ - catalogs:read
x-ratelimit-category: catalogs_read
x-sandbox: enabled
parameters:
@@ -6527,14 +7457,14 @@ paths:
/catalogs/product_groups/multiple:
delete:
x-ratelimit-category: catalogs_write
- summary: Delete multiple product groups
+ summary: Delete 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
+ Learn more
operationId: catalogs_product_groups/delete_many
x-sandbox: enabled
parameters:
@@ -6568,12 +7498,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Catalogs product group not found.
content:
@@ -6615,17 +7547,17 @@ paths:
- catalogs
post:
x-ratelimit-category: catalogs_write
- summary: Create multiple product group
+ summary: Create product groups
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
+ 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.
+ Note: Access to the Creative Assets catalog type is restricted to a specific group of users.
+ If you require access, please reach out to your partner manager.
operationId: catalogs_product_groups/create_many
security:
- pinterest_oauth2:
@@ -6655,7 +7587,6 @@ paths:
value:
- name: Few Filters using "all_of"
feed_id: '2680059592705'
- featured: false
filters:
all_of:
- MIN_PRICE:
@@ -6674,7 +7605,6 @@ paths:
can add products to the Product Group independently.
value:
- name: Many Filters using "any_of"
- featured: false
feed_id: '2680059592705'
filters:
all_of:
@@ -6757,6 +7687,28 @@ paths:
- air mattresses
- - table linens
negated: false
+ CatalogBasedRetailFewFiltersUsingAllOf:
+ summary: A simple catalog based 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 retail to be included in the Product Group.
+ value:
+ - catalog_type: RETAIL
+ name: Few Filters using "all_of"
+ catalog_id: '4866935934774'
+ country: US
+ locale: en-US
+ filters:
+ all_of:
+ - ITEM_ID:
+ values:
+ - item1
+ - item2
+ - CUSTOM_LABEL_1:
+ values:
+ - shoes
+ negated: false
HotelFewFiltersUsingAllOf:
summary: A simple hotel example that applies "all of the following
filters".
@@ -6823,12 +7775,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'409':
description: Conflict. Can't create this catalogs product group with this
value.
@@ -6874,7 +7828,7 @@ paths:
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
+ Learn more
operationId: catalogs_product_groups/list
security:
- pinterest_oauth2:
@@ -6935,12 +7889,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Data feed not found.
content:
@@ -6974,17 +7930,17 @@ paths:
- catalogs
post:
x-ratelimit-category: catalogs_write
- summary: Create single product group
+ summary: Create 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
+ 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.
+ Note: Access to the Creative Assets catalog type is restricted to a specific group of users.
+ If you require access, please reach out to your partner manager.
operationId: catalogs_product_groups/create
security:
- pinterest_oauth2:
@@ -7011,7 +7967,6 @@ paths:
value:
name: Few Filters using "all_of"
feed_id: '2680059592705'
- featured: false
filters:
all_of:
- MIN_PRICE:
@@ -7030,7 +7985,6 @@ paths:
can add products to the Product Group independently.
value:
name: Many Filters using "any_of"
- featured: false
feed_id: '2680059592705'
filters:
all_of:
@@ -7133,6 +8087,28 @@ paths:
values:
- big_hotels
negated: false
+ CatalogBasedRetailFewFiltersUsingAllOf:
+ summary: A simple catalog based 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 retail to be included in the Product Group.
+ value:
+ catalog_type: RETAIL
+ name: Few Filters using "all_of"
+ catalog_id: '4866935934774'
+ country: US
+ locale: en-US
+ filters:
+ all_of:
+ - ITEM_ID:
+ values:
+ - item1
+ - item2
+ - CUSTOM_LABEL_1:
+ values:
+ - shoes
+ negated: false
responses:
'201':
content:
@@ -7174,12 +8150,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'409':
description: Conflict. Can't create this catalogs product group with this
value.
@@ -7218,14 +8196,14 @@ paths:
/catalogs/product_groups/{product_group_id}:
get:
x-ratelimit-category: catalogs_read
- summary: Get single product group
+ summary: Get 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
+ Learn more
operationId: catalogs_product_groups/get
x-sandbox: enabled
parameters:
@@ -7275,12 +8253,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Catalogs product group not found.
content:
@@ -7314,14 +8294,14 @@ paths:
- catalogs
delete:
x-ratelimit-category: catalogs_write
- summary: Delete single product group
+ summary: Delete 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
+ Learn more
operationId: catalogs_product_groups/delete
x-sandbox: enabled
parameters:
@@ -7367,12 +8347,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Catalogs product group not found.
content:
@@ -7421,10 +8403,10 @@ paths:
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
+ 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.
+ Note: Access to the Creative Assets catalog type is restricted to a specific group of users.
+ If you require access, please reach out to your partner manager.
operationId: catalogs_product_groups/update
x-sandbox: enabled
parameters:
@@ -7483,12 +8465,14 @@ paths:
MerchantDisapproved:
value:
code: 2625
- message: Sorry, you cannot perform this action. Account is disapproved.
+ message: Sorry, you cannot perform this action as your account
+ has been disapproved. Please see business hub for more details.
+ https://www.pinterest.com/business/hub/
MerchantUnderReview:
value:
code: 2626
- message: Sorry, you cannot perform this action. Account is under
- review.
+ message: We are reviewing your account. Please see business hub
+ for more details. https://www.pinterest.com/business/hub/
'404':
description: Catalogs product group not found.
content:
@@ -7542,16 +8526,14 @@ paths:
/catalogs/product_groups/{product_group_id}/product_counts:
get:
x-ratelimit-category: catalogs_read
- summary: Get product counts for a Product Group
+ summary: Get product counts
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
+ Learn more
operationId: catalogs_product_groups/product_counts_get
security:
- pinterest_oauth2:
@@ -7565,7 +8547,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/CatalogsProductGroupProductCounts'
+ $ref: '#/components/schemas/CatalogsProductGroupProductCountsVertical'
description: Success
'404':
description: Product Group Not Found.
@@ -7600,16 +8582,14 @@ paths:
/catalogs/product_groups/{product_group_id}/products:
get:
x-ratelimit-category: catalogs_read
- summary: List products for a Product Group
+ summary: List products by 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
+ Learn more
operationId: catalogs_product_group_pins/list
security:
- pinterest_oauth2:
@@ -7622,6 +8602,7 @@ paths:
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/path_catalogs_product_group_id'
- $ref: '#/components/parameters/query_ad_account_id'
+ - $ref: '#/components/parameters/query_pin_metrics'
responses:
'200':
content:
@@ -7681,7 +8662,7 @@ paths:
/catalogs/products/get_by_product_group_filters:
post:
x-ratelimit-category: catalogs_read
- summary: List products for Product Group Filters
+ summary: List products by filter
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.
@@ -7691,7 +8672,7 @@ paths:
Note: This endpoint only supports RETAIL catalog at the moment.
- Learn more
+ Learn more
operationId: products_by_product_group_filter/list
security:
- pinterest_oauth2:
@@ -7703,6 +8684,7 @@ paths:
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_ad_account_id'
+ - $ref: '#/components/parameters/query_pin_metrics'
requestBody:
description: Object holding a group of filters for a catalog product group
required: true
@@ -8247,7 +9229,7 @@ paths:
description: |-
List media uploads filtered by given parameters.
- Learn more about video Pin creation.
+ Learn more about video Pin creation.
tags:
- media
operationId: media/list
@@ -8293,7 +9275,7 @@ paths:
parameter and also include all of the parameters from
upload_parameters.
- Learn more about video Pin creation.
+ Learn more about video Pin creation.
tags:
- media
operationId: media/create
@@ -8329,7 +9311,7 @@ paths:
description: |-
Get details for a registered media upload, including its current status.
- Learn more about video Pin creation.
+ Learn more about video Pin creation.
tags:
- media
operationId: media/get
@@ -8370,9 +9352,11 @@ paths:
IMPORTANT: You need to start the OAuth flow via www.pinterest.com/oauth before calling this endpoint (or have an existing refresh token).
- See Authentication for more.
+ See Authentication for more.
+
+ Parameter refresh_on and its corresponding response type everlasting_refresh are now available to all apps! Later this year, continuous refresh will become the default behavior (ie you will no longer need to send this parameter). Learn more.
- Parameter refresh_on and its corresponding response type everlasting_refresh are now available to all apps! Later this year, continuous refresh will become the default behavior (ie you will no longer need to send this parameter). Learn more.
+ Grant type client_credentials and its corresponding response type are not fully available. You will likely get a default error if you attempt to use this grant_type.
tags:
- oauth
operationId: oauth/token
@@ -8416,6 +9400,9 @@ paths:
- pinterest_oauth2:
- boards:read
- pins:read
+ - client_credentials:
+ - boards:read
+ - pins:read
x-ratelimit-category: org_read
x-sandbox: enabled
x-codeSamples:
@@ -8478,9 +9465,9 @@ paths:
Note: If the current "operation user_account" (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to make use of the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).
- - This function is intended solely for publishing new content created by the user. If you are interested in saving content created by others to your Pinterest boards, sometimes called 'curated content', please use our Save button instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.
+ - This function is intended solely for publishing new content created by the user. If you are interested in saving content created by others to your Pinterest boards, sometimes called 'curated content', please use our Save button instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.
- Learn more about video Pin creation.
+ Learn more about video Pin creation.
tags:
- pins
operationId: pins/create
@@ -8500,7 +9487,7 @@ paths:
from pinterest.organic.pins import Pin
# Board information can be fetched from profile page or from create/list board method here:
- # https://developers.pinterest.com/docs/api/v5/#operation/boards/list
+ # /docs/api/v5/#operation/boards/list
BOARD_ID="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:
+ 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:
- For Pins on public or protected boards: Admin, Analyst.
- For Pins on secret boards: Admin.
@@ -8924,6 +9914,9 @@ paths:
- pinterest_oauth2:
- boards:read
- pins:read
+ - client_credentials:
+ - boards:read
+ - pins:read
x-ratelimit-category: org_analytics
x-sandbox: disabled
parameters:
@@ -8978,13 +9971,13 @@ paths:
get:
summary: Get multiple Pin analytics
description: |-
- This endpoint is currently in beta and not available to all apps. Learn more.
+ This endpoint is currently in beta and not available to all apps. Learn more.
Get analytics for multiple pins owned by the "operation user_account" - or on a group board that has been shared with this account.
- The maximum number of pins supported in a single request is 100.
- 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:
+ 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:
- For Pins on public or protected boards: Admin, Analyst.
- For Pins on secret boards: Admin.
@@ -8997,19 +9990,13 @@ paths:
- pinterest_oauth2:
- boards:read
- pins:read
+ - client_credentials:
+ - boards:read
+ - pins:read
x-ratelimit-category: org_analytics
x-sandbox: disabled
parameters:
- - name: pin_ids
- description: List of Pin IDs.
- in: query
- schema:
- type: array
- items:
- type: string
- pattern: ^\d+$
- minItems: 1
- maxItems: 100
+ - $ref: '#/components/parameters/query_required_pin_ids'
- $ref: '#/components/parameters/query_start_date'
- $ref: '#/components/parameters/query_end_date'
- $ref: '#/components/parameters/query_app_types'
@@ -9032,6 +10019,8 @@ paths:
- SAVE_RATE
- TOTAL_COMMENTS
- TOTAL_REACTIONS
+ - USER_FOLLOW
+ - PROFILE_VISIT
- description: Video Pin metric types
type: string
enum:
@@ -9137,11 +10126,11 @@ paths:
from pinterest.organic.pins import Pin
# Pin information can be fetched from profile page or from create/list pin method here:
- # https://developers.pinterest.com/docs/api/v5/#operation/pins/list
+ # /docs/api/v5/#operation/pins/list
PIN_ID="Get the top trending search keywords among the Pinterest user audience.
-Trending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.
-Geographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords.
-For an interactive way to explore this data, please visit trends.pinterest.com. + description: | +
Get the top trending search keywords among the Pinterest user audience.
Trending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.
Geographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords.
For an interactive way to explore this data, please visit trends.pinterest.com.
operationId: trending_keywords/list
security:
- pinterest_oauth2:
@@ -9720,13 +10710,15 @@ paths:
Get account information for the "operation user_account"
- By default, the "operation user_account" is the token user_account.
- If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See Understanding Business Access for more information.
+ If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See Understanding Business Access for more information.
tags:
- user_account
operationId: user_account/get
security:
- pinterest_oauth2:
- user_accounts:read
+ - client_credentials:
+ - user_accounts:read
x-ratelimit-category: org_read
x-sandbox: enabled
parameters:
@@ -9826,6 +10818,9 @@ paths:
- pinterest_oauth2:
- pins:read
- user_accounts:read
+ - client_credentials:
+ - pins:read
+ - user_accounts:read
x-ratelimit-category: org_analytics
x-sandbox: disabled
parameters:
@@ -9878,6 +10873,9 @@ paths:
- pinterest_oauth2:
- pins:read
- user_accounts:read
+ - client_credentials:
+ - pins:read
+ - user_accounts:read
x-ratelimit-category: org_analytics
x-sandbox: disabled
parameters:
@@ -9923,6 +10921,8 @@ paths:
security:
- pinterest_oauth2:
- user_accounts:read
+ - client_credentials:
+ - user_accounts:read
x-ratelimit-category: org_read
x-sandbox: enabled
responses:
@@ -9950,6 +10950,8 @@ paths:
security:
- pinterest_oauth2:
- user_accounts:read
+ - client_credentials:
+ - user_accounts:read
x-ratelimit-category: ads_read
x-sandbox: enabled
parameters:
@@ -9994,6 +10996,8 @@ paths:
security:
- pinterest_oauth2:
- user_accounts:read
+ - client_credentials:
+ - user_accounts:read
x-ratelimit-category: org_read
x-sandbox: disabled
parameters:
@@ -10033,6 +11037,8 @@ paths:
security:
- pinterest_oauth2:
- user_accounts:read
+ - client_credentials:
+ - user_accounts:read
x-ratelimit-category: org_read
x-sandbox: enabled
parameters:
@@ -10075,7 +11081,7 @@ paths:
post:
summary: Follow user
description: |-
- This endpoint is currently in beta and not available to all apps. Learn more.
+ This endpoint is currently in beta and not available to all apps. Learn more.
Use this request, as a signed-in user, to follow another user.
tags:
@@ -10131,6 +11137,8 @@ paths:
- user_accounts:write
x-ratelimit-category: org_write
x-sandbox: disabled
+ parameters:
+ - $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Verify a website.
required: true
@@ -10233,9 +11241,13 @@ paths:
tags:
- user_account
operationId: website_verification/get
+ parameters:
+ - $ref: '#/components/parameters/query_ad_account_id'
security:
- pinterest_oauth2:
- user_accounts:read
+ - client_credentials:
+ - user_accounts:read
responses:
'200':
content:
@@ -10272,6 +11284,8 @@ paths:
security:
- pinterest_oauth2:
- user_accounts:read
+ - client_credentials:
+ - user_accounts:read
x-ratelimit-category: org_read
parameters:
- $ref: '#/components/parameters/path_username'
@@ -10354,6 +11368,32 @@ components:
basic:
type: http
scheme: basic
+ client_credentials:
+ flows:
+ clientCredentials:
+ scopes:
+ ads:read: See all of your advertising data, including ads, ad groups,
+ campaigns etc.
+ ads:write: Create, update, or delete ads, ad groups, campaigns etc.
+ billing:read: See all of your billing data, billing profile, etc.
+ billing:write: Create, update, or delete billing data, billing profiles,
+ etc.
+ biz_access:read: See business access data
+ biz_access:write: Create, update, or delete business access data
+ boards:read: See your public boards, including group boards you join
+ boards:read_secret: See your secret boards
+ boards:write: Create, update, or delete your public boards
+ boards:write_secret: Create, update, or delete your secret boards
+ catalogs:read: See all of your catalogs data
+ catalogs:write: Create, update, or delete your catalogs data
+ pins:read: See your public Pins
+ pins:read_secret: See your secret Pins
+ pins:write: Create, update, or delete your public Pins
+ pins:write_secret: Create, update, or delete your secret Pins
+ user_accounts:read: See your user accounts and followers
+ user_accounts:write: Update your user accounts and followers
+ tokenUrl: https://api.pinterest.com/v3/oauth/access_token/
+ type: oauth2
schemas:
Account:
type: object
@@ -10557,10 +11597,12 @@ components:
description: Base64 encoded key for client to decrypt lead data.
example: ucvxbV2Tdss0vNeYsdh4Qfa/1Khm2b0PqXvXeTTZh54
type: string
+ nullable: true
cryptographic_algorithm:
description: Lead data encryption algorithm.
example: AES-256-GCM
type: string
+ nullable: true
created_time:
description: Subscription creation time. Unix timestamp in milliseconds.
example: 1699209842000
@@ -10607,10 +11649,12 @@ components:
description: Base64 encoded key for client to decrypt lead data.
example: ucvxbV2Tdss0vNeYsdh4Qfa/1Khm2b0PqXvXeTTZh54
type: string
+ nullable: true
cryptographic_algorithm:
description: Lead data encryption algorithm.
example: AES-256-GCM
type: string
+ nullable: true
created_time:
description: Lead form creation time. Unix timestamp in milliseconds.
example: 1699209842000
@@ -10665,8 +11709,7 @@ components:
type: string
pattern: ^(AG)?\d+$
android_deep_link:
- description: Deep link URL for Android devices. Not currently available.
- Using this field will generate an error.
+ description: Deep link URL for Android devices.
nullable: true
type: string
carousel_android_deep_links:
@@ -10698,8 +11741,7 @@ components:
type: string
nullable: true
ios_deep_link:
- description: Deep link URL for iOS devices. Not currently available. Using
- this field will generate an error.
+ description: Deep link URL for iOS devices.
type: string
nullable: true
is_pin_deleted:
@@ -10737,7 +11779,7 @@ components:
description: Select a call to action (CTA) to display below your ad. Available
only for ads with direct links enabled. CTA options for consideration
and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP,
- VISIT_WEBSITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion
+ VISIT_SITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion
campaigns with add to cart conversion events only)
example: LEARN_MORE
nullable: true
@@ -10751,7 +11793,7 @@ components:
- BUY_NOW
- CONTACT_US
- GET_QUOTE
- - VISIT_WEBSITE
+ - VISIT_SITE
- APPLY_NOW
- BOOK_NOW
- REQUEST_DEMO
@@ -11025,14 +12067,287 @@ components:
AdCreateRequest:
type: object
allOf:
- - $ref: '#/components/schemas/AdCommon'
- - $ref: '#/components/schemas/AdPinId'
+ - $ref: '#/components/schemas/AdCommon'
+ - $ref: '#/components/schemas/AdPinId'
+ - type: object
+ title: Request schema for creating ads
+ required:
+ - ad_group_id
+ - pin_id
+ - creative_type
+ AdvancedAuctionItemsGetRequest:
+ type: object
+ description: Request object used to get bid options values for a batch of retail
+ catalog items
+ additionalProperties: false
+ properties:
+ catalog_id:
+ description: Catalog id pertaining to the retail item
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ items:
+ type: array
+ minItems: 1
+ maxItems: 10000
+ description: A list of retail catalog items to fetch bid options for
+ items:
+ $ref: '#/components/schemas/AdvancedAuctionItemsGetRecord'
+ required:
+ - catalog_id
+ - items
+ AdvancedAuctionItemsGetRecord:
+ description: Object uniquely identifying a retail catalog item
+ allOf:
+ - $ref: '#/components/schemas/AdvancedAuctionKey'
+ AdvancedAuctionItems:
+ type: object
+ description: Response object containing item bid options
+ properties:
+ catalog_id:
+ description: Response object of item bid options
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ items:
+ type: array
+ description: Array with item bid options
+ items:
+ $ref: '#/components/schemas/AdvancedAuctionItem'
+ AdvancedAuctionItemsSubmitRequest:
+ type: object
+ description: Request containing operations to perform on bid prices and bid
+ multipliers for a batch of retail catalog items
+ additionalProperties: false
+ properties:
+ catalog_id:
+ description: Catalog id pertaining to all items
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ items:
+ type: array
+ minItems: 1
+ maxItems: 10000
+ description: Array of item bid option operations
+ items:
+ $ref: '#/components/schemas/AdvancedAuctionItemsSubmitRecord'
+ required:
+ - catalog_id
+ - items
+ AdvancedAuctionItemsSubmitRecord:
+ type: object
+ description: Object describing an item bid option operation
+ oneOf:
+ - $ref: '#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord'
+ - $ref: '#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord'
+ discriminator:
+ propertyName: operation
+ mapping:
+ UPSERT: '#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord'
+ DELETE: '#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord'
+ properties:
+ operation:
+ $ref: '#/components/schemas/AdvancedAuctionOperation'
+ required:
+ - operation
+ AdvancedAuctionItemsSubmitUpsertRecord:
+ description: Object describing an item bid option upsert operation
+ example:
+ item_id: DS0294-M
+ country: US
+ language: EN
+ operation: UPSERT
+ bid_options:
+ bid_in_micro_currency: 5000000
+ app_type_multipliers:
+ android_mobile: 1.1
+ android_tablet: 1.1
+ ipad: 1.2
+ iphone: 1.2
+ web: 0.9
+ web_mobile: 0.8
+ update_mask:
+ - BID
+ - APP_TYPE_BID_MULTIPLIER_SET
+ allOf:
+ - $ref: '#/components/schemas/AdvancedAuctionItem'
- type: object
- title: Request schema for creating ads
+ properties:
+ update_mask:
+ type: array
+ description: The list of item bid option fields to be set or updated.
+ Fields specified in the updated mask without a value specified in the
+ `bid_options` object in the body will be set to `null`. If an item bid
+ option record is being created, fields not specified in the update mask
+ will be initialized to `null`.
+ example:
+ - BID
+ - APP_TYPE_BID_MULTIPLIER_SET
+ nullable: true
+ items:
+ $ref: '#/components/schemas/UpdateMaskBidOptionField'
required:
- - ad_group_id
- - pin_id
- - creative_type
+ - update_mask
+ AdvancedAuctionItemsSubmitDeleteRecord:
+ description: Object describing an item bid option deletion operation
+ example:
+ item_id: DS0294-M
+ country: US
+ language: EN
+ operation: DELETE
+ allOf:
+ - $ref: '#/components/schemas/AdvancedAuctionKey'
+ AdvancedAuctionProcessedItems:
+ type: object
+ description: Response object containing the results of an operation on an item
+ bid option
+ properties:
+ catalog_id:
+ description: Catalog id pertaining to all items
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ items:
+ type: array
+ description: Array of advanced auction processed items
+ items:
+ $ref: '#/components/schemas/AdvancedAuctionProcessedItem'
+ AdvancedAuctionProcessedItem:
+ description: Object describing the result of an operation on an item bid option
+ type: object
+ allOf:
+ - $ref: '#/components/schemas/AdvancedAuctionItemsSubmitRecord'
+ - type: object
+ properties:
+ errors:
+ type: array
+ description: |-
+ Array with validation errors for the supplied item bid option modification operation.
+ A non empty errors list means this single item operation was not applied.
+ items:
+ $ref: '#/components/schemas/AdvancedAuctionOperationError'
+ AdvancedAuctionItem:
+ title: Advanced Auction Item
+ allOf:
+ - $ref: '#/components/schemas/AdvancedAuctionKey'
+ - type: object
+ properties:
+ bid_options:
+ $ref: '#/components/schemas/AdvancedAuctionBidOptions'
+ required:
+ - bid_options
+ AdvancedAuctionKey:
+ type: object
+ description: Object uniquely identifying a retail catalog item
+ properties:
+ item_id:
+ description: The catalog retail item id in the merchant namespace
+ example: DS0294-M
+ type: string
+ country:
+ $ref: '#/components/schemas/Country'
+ language:
+ $ref: '#/components/schemas/Language'
+ required:
+ - item_id
+ - country
+ - language
+ AdvancedAuctionOperation:
+ type: string
+ enum:
+ - UPSERT
+ - DELETE
+ AdvancedAuctionBidOptions:
+ type: object
+ description: Object describing a retail catalog item's bid options (bid price
+ and bid multipliers).
+ properties:
+ bid_in_micro_currency:
+ $ref: '#/components/schemas/BidInMicroCurrency'
+ app_type_multipliers:
+ $ref: '#/components/schemas/AppTypeMultipliers'
+ placement_multipliers:
+ $ref: '#/components/schemas/PlacementMultipliers'
+ AdvancedAuctionOperationError:
+ description: Error which occurred when applying a bid options operation to a
+ specific item.
+ type: object
+ properties:
+ code:
+ description: The error code for the item bid option operation validation
+ error
+ type: integer
+ example: 6
+ message:
+ description: Message describing the item bid option operation validation
+ error
+ type: string
+ example: Bid in micro currency should be non-negative
+ BidInMicroCurrency:
+ type: integer
+ format: int64
+ description: Bid price in micro currency. A value of 0 will stop distribution
+ for this item in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. A value
+ of `null` will fallback to the ad group's `bid_in_micro_currency`.
+ example: 5000000
+ nullable: true
+ AppTypeMultipliers:
+ type: object
+ description: |-
+ This represents a mapping from app type targeting criteria to a bid price adjustment.
+
+ Multiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified app type in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All app type multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment).
+ example:
+ android_mobile: 1.1
+ android_tablet: 1.1
+ ipad: 1.2
+ iphone: 1.2
+ web: 0.9
+ web_mobile: 0.8
+ properties:
+ APP_TYPE:
+ $ref: '#/components/schemas/TargetingSpecAppType'
+ additionalProperties:
+ type: number
+ format: double
+ nullable: true
+ TargetingSpecAppType:
+ type: string
+ enum:
+ - android_mobile
+ - android_tablet
+ - ipad
+ - iphone
+ - web
+ - web_mobile
+ PlacementMultipliers:
+ type: object
+ description: |-
+ This represents a mapping from placement to a bid price adjustment.
+
+ Multiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified placement in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All placement multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment).
+ example:
+ browse: 0.9
+ search: 1.2
+ properties:
+ PLACEMENT:
+ type: string
+ enum:
+ - SEARCH
+ - BROWSE
+ additionalProperties:
+ type: number
+ format: double
+ nullable: true
+ UpdateMaskBidOptionField:
+ type: string
+ description: bid option field to apply operation updates to
+ example: BID
+ enum:
+ - BID
+ - APP_TYPE_BID_MULTIPLIER_SET
+ - PLACEMENT_BID_MULTIPLIER_SET
AdGroupArrayResponse:
type: object
properties:
@@ -11104,7 +12419,7 @@ components:
description: Set a limit to the number of times a promoted pin from this
campaign can be impressed by a pinner within the past rolling 30 days.
Only available for CPM (cost per mille (1000 impressions)) ad groups.
- A CPM ad group has an IMPRESSION billable_event
+ A CPM ad group has an IMPRESSION billable_event
value. This field **REQUIRES** the `end_time` field.
type: integer
example: 100
@@ -11113,13 +12428,13 @@ components:
allOf:
- $ref: '#/components/schemas/TrackingUrls'
description: 'Third-party tracking URLs.
JSON object with the format:
- {"Tracking
- event enum":[URL string array],...}
For example: {"impression":
- ["URL1", "URL2"], "click": ["URL1", "URL2", "URL3"]}.
Up to three tracking
- URLs are supported for each event type. Tracking URLs set at the ad group
- or ad level can override those set at the campaign level. May be null.
- Pass in an empty object - {} - to remove tracking URLs.
For more
- information, see Tracking event enum":[URL
+ string array],...}
For example: {"impression": ["URL1", "URL2"], "click":
+ ["URL1", "URL2", "URL3"]}.
Up to three tracking URLs are supported
+ for each event type. Tracking URLs set at the ad group or ad level can
+ override those set at the campaign level. May be null. Pass in an empty
+ object - {} - to remove tracking URLs.
For more information, see
+ Third-party and dynamic tracking.'
nullable: true
auto_targeting_enabled:
@@ -11132,8 +12447,7 @@ components:
type: string
allOf:
- $ref: '#/components/schemas/PlacementGroupType'
- description: Placement
- group.
+ description: Placement group.
pacing_delivery_type:
type: string
allOf:
@@ -11147,7 +12461,8 @@ components:
$ref: '#/components/schemas/ActionType'
bid_strategy_type:
nullable: true
- description: Bid strategy type
+ description: Bid strategy type. For Campaigns with Video Completion objectives,
+ the only supported bid strategy type is AUTOMATIC_BID.
enum:
- AUTOMATIC_BID
- MAX_BID
@@ -11571,6 +12886,44 @@ components:
nullable: true
required:
- id
+ AdsAnalyticsAdTargetingType:
+ type: string
+ description: Reporting targeting type for ads
+ example: APPTYPE
+ enum:
+ - KEYWORD
+ - APPTYPE
+ - GENDER
+ - LOCATION
+ - PLACEMENT
+ - COUNTRY
+ - TARGETED_INTEREST
+ - PINNER_INTEREST
+ - AUDIENCE_INCLUDE
+ - GEO
+ - AGE_BUCKET
+ - REGION
+ - QUIZ_RESULT
+ - AGE_BUCKET_AND_GENDER
+ AdsAnalyticsCampaignTargetingType:
+ type: string
+ description: Reporting targeting type for campaigns
+ example: APPTYPE
+ enum:
+ - KEYWORD
+ - APPTYPE
+ - GENDER
+ - LOCATION
+ - PLACEMENT
+ - COUNTRY
+ - TARGETED_INTEREST
+ - PINNER_INTEREST
+ - AUDIENCE_INCLUDE
+ - GEO
+ - AGE_BUCKET
+ - REGION
+ - CREATIVE_TYPE
+ - AGE_BUCKET_AND_GENDER
AdsAnalyticsCreateAsyncRequest:
type: object
allOf:
@@ -11676,7 +13029,7 @@ components:
- VIDEO_VIEW
items:
$ref: '#/components/schemas/ObjectiveType'
- maxItems: 6
+ maxItems: 7
minItems: 1
- type: object
properties:
@@ -11802,14 +13155,31 @@ components:
type: string
allOf:
- type: string
- description: Whether to first sort the report by date or by ID. BY_DATE
- is recommended for large requests. BY_DATE for JSON format is currently
- not supported.
+ description: Whether to first sort the report by date or by entity ID
+ of the reporting entity level. Date will be used as the first level
+ key for JSON reports that use BY_DATE. BY_DATE is recommended for
+ large requests.
example: BY_ID
enum:
- BY_ID
- BY_DATE
default: BY_ID
+ start_hour:
+ description: Which hour of the start date to begin the report. The entire
+ day will be included if no start hour is provided. Only allowed for
+ hourly reports.
+ type: integer
+ minimum: 0
+ maximum: 23
+ end_hour:
+ description: Which hour of the end date to stop the report (inclusive).
+ For example, with an end_date of '2020-01-01' and end_hour of '15',
+ the report will contain metrics up to '2020-01-01 14:59:59'. The entire
+ day will be included if no end hour is provided. Only allowed for hourly
+ reports.
+ type: integer
+ minimum: 0
+ maximum: 23
AdsAnalyticsCreateAsyncResponse:
type: object
properties:
@@ -12078,6 +13448,11 @@ components:
$ref: '#/components/schemas/AssetTypeResponse'
permissions:
$ref: '#/components/schemas/PermissionsResponse'
+ asset_group_info:
+ nullable: true
+ description: An object containing all the information specific to the provided
+ asset group. This field will be populated only if asset_type equals 'ASSET_GROUP'.
+ $ref: '#/components/schemas/AssetGroupBinding'
AssetIdToPermissions:
description: |
An object mapping asset ids to lists of business permissions. This can be used to setting/requesting permissions on various assets. If accepting an invite or request, this object would be used to grant asset permissions to the member or partner.
@@ -12098,7 +13473,8 @@ components:
'809944451643622187':
- PROFILE_PUBLISHER
AssetTypeResponse:
- description: Type of asset. Currently we only support AD_ACCOUNT and PROFILE.
+ description: Type of asset. Currently we only support AD_ACCOUNT and PROFILE,
+ and ASSET_GROUP.
example: AD_ACCOUNT
type: string
Audience:
@@ -12472,7 +13848,7 @@ components:
"event_source": {"=": ["web", "mobile"]}, "ingestion_source": {"=": ["tag"]}}
(Retention
days should be 1-540. Retention applies to specific customers.)
ENGAGEMENT:
{"engagement_domain": ["www.entomi.com"], "engager_type": 1}
For more details
- on engagement audiences, see November 2021 changelog.'
properties:
country:
@@ -12743,6 +14119,18 @@ components:
type: string
title: Rule
type: object
+ AudienceShareType:
+ type: string
+ default: SHARED
+ enum:
+ - SHARED
+ - RECEIVED
+ AudienceAccountType:
+ type: string
+ default: AD_ACCOUNT
+ enum:
+ - AD_ACCOUNT
+ - BUSINESS_ACCOUNT
AudienceSharingType:
description: 'Audience sharing type: ["CUSTOM", "SYNDICATED"]'
type: string
@@ -13811,26 +15199,14 @@ components:
Campaign Budget Optimization (CBO) campaigns.
example: 1644023526
nullable: true
- summary_status:
- type: string
- allOf:
- - $ref: '#/components/schemas/CampaignSummaryStatus'
+ is_flexible_daily_budgets:
+ $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets'
CampaignCreateCommon:
type: object
allOf:
- $ref: '#/components/schemas/CampaignCommon'
- type: object
properties:
- status:
- type: string
- default: ACTIVE
- allOf:
- - $ref: '#/components/schemas/EntityStatus'
- is_flexible_daily_budgets:
- type: boolean
- default: false
- allOf:
- - $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets'
default_ad_group_budget_in_micro_currency:
type: integer
description: When transitioning from campaign budget optimization to non-campaign
@@ -13840,16 +15216,28 @@ components:
example: 0
nullable: true
is_automated_campaign:
- type: boolean
- default: false
- allOf:
- - $ref: '#/components/schemas/CampaignIsAutomatedCampaign'
+ $ref: '#/components/schemas/CampaignIsAutomatedCampaign'
CampaignCreateRequest:
type: object
allOf:
- $ref: '#/components/schemas/CampaignCreateCommon'
- type: object
properties:
+ is_flexible_daily_budgets:
+ type: boolean
+ default: false
+ allOf:
+ - $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets'
+ is_automated_campaign:
+ type: boolean
+ default: false
+ allOf:
+ - $ref: '#/components/schemas/CampaignIsAutomatedCampaign'
+ status:
+ type: string
+ default: ACTIVE
+ allOf:
+ - $ref: '#/components/schemas/EntityStatus'
objective_type:
$ref: '#/components/schemas/ObjectiveType'
required:
@@ -13894,19 +15282,19 @@ components:
description: Specifies whether the campaign was created in the automated campaign
flow
example: true
- default: false
+ nullable: true
CampaignIsCampaignBudgetOptimization:
type: boolean
description: Determines if a campaign automatically generate ad-group level
budgets given a campaign budget to maximize campaign outcome. When transitioning
from non-cbo to cbo, all previous child ad group budget will be cleared.
example: true
- default: false
+ nullable: true
CampaignIsFlexibleDailyBudgets:
type: boolean
description: Determine if a campaign has flexible daily budgets setup.
example: true
- default: false
+ nullable: true
CampaignResponse:
type: object
allOf:
@@ -13928,19 +15316,10 @@ components:
type: string
description: Always "campaign".
example: campaign
- is_flexible_daily_budgets:
- type: boolean
- description: Determines if a campaign has flexible daily budgets setup.
- example: true
- nullable: true
is_campaign_budget_optimization:
- type: boolean
- description: Determines if a campaign automatically generate ad-group
- level budgets given a campaign budget to maximize campaign outcome.
- When transitioning from non-cbo to cbo, all previous child ad group
- budget will be cleared.
- example: true
- nullable: true
+ $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization'
+ summary_status:
+ $ref: '#/components/schemas/CampaignSummaryStatus'
CampaignSummaryStatus:
type: string
description: Summary status for campaign
@@ -13958,30 +15337,11 @@ components:
type: object
allOf:
- $ref: '#/components/schemas/CampaignId'
- - $ref: '#/components/schemas/CampaignCommon'
- $ref: '#/components/schemas/CampaignCreateCommon'
- type: object
properties:
is_campaign_budget_optimization:
- type: boolean
- nullable: true
- allOf:
- - $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization'
- is_flexible_daily_budgets:
- type: boolean
- nullable: true
- allOf:
- - $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets'
- is_automated_campaign:
- type: boolean
- nullable: true
- allOf:
- - $ref: '#/components/schemas/CampaignIsAutomatedCampaign'
- status:
- type: string
- nullable: true
- allOf:
- - $ref: '#/components/schemas/EntityStatus'
+ $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization'
objective_type:
type: string
nullable: true
@@ -14057,73 +15417,23 @@ components:
- id
- name
- catalog_type
- CatalogProductGroup:
- description: non-promoted catalog product group entity
- properties:
- id:
- description: ID of the catalog product group.
- example: '2680059592705'
- title: id
- type: string
- merchant_id:
- description: Merchant ID pertaining to the owner of the catalog product
- group.
- example: '2680059592705'
- pattern: ^\d+$
- title: merchant_id
- type: string
- name:
- description: Name of catalog product group
- example: Most Popular
- title: name
- type: string
- filters:
- description: Object holding a list of filters
- example:
- '1':
- - 123chars_title
- title: filters
- type: object
- filter_v2:
- description: Object holding a list of filters
- example:
- '1':
- - 123chars_title
- title: filters
- type: object
- type:
- $ref: '#/components/schemas/Board'
- status:
- $ref: '#/components/schemas/EntityStatus'
- feed_profile_id:
- description: id of the feed profile belonging to this catalog product group
- pattern: ^\d+$
- title: feed_profile_id
- type: string
- created_at:
- description: Unix timestamp in seconds of when catalog product group was
- created.
- example: 1621350033000
- title: created_at
- type: integer
- last_update:
- description: Unix timestamp in seconds of last time catalog product group
- was updated.
- example: 1622742155000
- title: last_update
- type: integer
- product_count:
- description: Amount of products in the catalog product group
- example: 6
- title: product_count
- type: integer
- featured_position:
- description: index of the featured position of the catalog product group
- example: 2
- title: featured_position
- type: integer
- title: CatalogProductGroup
+ CatalogsCreateRequest:
type: object
+ title: catalogs_create_request
+ description: Request object for creating a catalog.
+ additionalProperties: false
+ properties:
+ catalog_type:
+ description: Type of the catalog entity.
+ type: string
+ enum:
+ - HOTEL
+ name:
+ description: A human-friendly name associated to a given catalog.
+ type: string
+ required:
+ - catalog_type
+ - name
CatalogsDbItem:
type: object
title: db_item
@@ -14138,6 +15448,10 @@ components:
type: string
format: date-time
example: '2022-03-14T15:16:34Z'
+ required:
+ - id
+ - created_at
+ - updated_at
CatalogsCreateReportResponse:
type: object
properties:
@@ -14332,7 +15646,7 @@ components:
pattern: ^\d+$
description: Unique identifier of a feed processing result. It can be acquired
from the "id" field of the "items" array within the response of the [List
- processing results for a given feed](https://developers.pinterest.com/docs/api/v5/#operation/feed_processing_results/list).
+ processing results for a given feed](/docs/api/v5/#operation/feed_processing_results/list).
If not provided, default to most recent completed processing result.
required:
- report_type
@@ -14615,6 +15929,26 @@ components:
PREORDER:
type: integer
description: The number of ingested products that are in preorder.
+ CatalogsFeedIngestion:
+ type: object
+ properties:
+ id:
+ type: string
+ example: '01234'
+ feed_id:
+ type: string
+ example: '56789'
+ created_at:
+ type: string
+ format: date-time
+ example: '2022-03-14T15:16:34Z'
+ status:
+ $ref: '#/components/schemas/CatalogsFeedProcessingStatus'
+ required:
+ - id
+ - feed_id
+ - created_at
+ - status
CatalogsFeedIngestionWarnings:
type: object
properties:
@@ -15074,13 +16408,8 @@ components:
type: string
enum:
- COMPLETED
- - COMPLETED_EARLY
- - DISAPPROVED
- FAILED
- PROCESSING
- - QUEUED_FOR_PROCESSING
- - UNDER_APPEAL
- - UNDER_REVIEW
CatalogsFeedProductCounts:
type: object
description: The counts can be null early in the process.
@@ -15455,6 +16784,11 @@ components:
$ref: '#/components/schemas/Country'
default_availability:
$ref: '#/components/schemas/ProductAvailabilityType'
+ status:
+ type: string
+ allOf:
+ - $ref: '#/components/schemas/CatalogsStatus'
+ - default: ACTIVE
required:
- format
- location
@@ -15538,6 +16872,11 @@ components:
$ref: '#/components/schemas/Country'
default_availability:
$ref: '#/components/schemas/ProductAvailabilityType'
+ status:
+ type: string
+ allOf:
+ - $ref: '#/components/schemas/CatalogsStatus'
+ - default: ACTIVE
required:
- format
- location
@@ -15631,6 +16970,11 @@ components:
nullable: true
type: string
pattern: ^\d+$
+ status:
+ type: string
+ allOf:
+ - $ref: '#/components/schemas/CatalogsStatus'
+ - default: ACTIVE
required:
- format
- location
@@ -15765,6 +17109,11 @@ components:
nullable: true
type: string
pattern: ^\d+$
+ status:
+ type: string
+ allOf:
+ - $ref: '#/components/schemas/CatalogsStatus'
+ - default: ACTIVE
required:
- format
- location
@@ -16351,14 +17700,14 @@ components:
example: 595953100599279259-66753b9bb65c46c49bd8503b27fecf9e
type: string
created_time:
- description: 'Time of the batch creation: YYYY-MM-DD''T''hh:mm:ssTZD'
- example: '2020-01-01T20:10:40-00:00'
+ description: 'Date and time (UTC) of the batch creation: YYYY-MM-DD''T''hh:mm:ss'
+ example: '2024-01-01T20:10:40'
type: string
format: date-time
readOnly: true
completed_time:
- description: 'Time of the batch completion: YYYY-MM-DD''T''hh:mm:ssTZD'
- example: '2022-03-10T15:37:10-00:00'
+ description: 'Date and time (UTC) of the batch completion: YYYY-MM-DD''T''hh:mm:ss'
+ example: '2024-01-01T20:20:00'
type: string
format: date-time
readOnly: true
@@ -16384,14 +17733,14 @@ components:
example: 595953100599279259-66753b9bb65c46c49bd8503b27fecf9e
type: string
created_time:
- description: 'Time of the batch creation: YYYY-MM-DD''T''hh:mm:ssTZD'
- example: '2020-01-01T20:10:40-00:00'
+ description: 'Date and time (UTC) of the batch creation: YYYY-MM-DD''T''hh:mm:ss'
+ example: '2024-01-01T20:10:40'
type: string
format: date-time
readOnly: true
completed_time:
- description: 'Time of the batch completion: YYYY-MM-DD''T''hh:mm:ssTZD'
- example: '2022-03-10T15:37:10-00:00'
+ description: 'Date and time (UTC) of the batch completion: YYYY-MM-DD''T''hh:mm:ss'
+ example: '2024-01-01T20:20:00'
type: string
format: date-time
readOnly: true
@@ -16417,14 +17766,14 @@ components:
example: 595953100599279259-66753b9bb65c46c49bd8503b27fecf9e
type: string
created_time:
- description: 'Time of the batch creation: YYYY-MM-DD''T''hh:mm:ssTZD'
- example: '2020-01-01T20:10:40-00:00'
+ description: 'Date and time (UTC) of the batch creation: YYYY-MM-DD''T''hh:mm:ss'
+ example: '2024-01-01T20:10:40'
type: string
format: date-time
readOnly: true
completed_time:
- description: 'Time of the batch completion: YYYY-MM-DD''T''hh:mm:ssTZD'
- example: '2022-03-10T15:37:10-00:00'
+ description: 'Date and time (UTC) of the batch completion: YYYY-MM-DD''T''hh:mm:ss'
+ example: '2024-01-01T20:20:00'
type: string
format: date-time
readOnly: true
@@ -16449,7 +17798,10 @@ components:
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
filters:
$ref: '#/components/schemas/CatalogsItemsPostFilters'
required:
@@ -16482,7 +17834,10 @@ components:
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
operation:
$ref: '#/components/schemas/BatchOperation'
items:
@@ -16505,7 +17860,10 @@ components:
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
operation:
$ref: '#/components/schemas/BatchOperation'
items:
@@ -16526,7 +17884,10 @@ components:
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
operation:
$ref: '#/components/schemas/BatchOperation'
items:
@@ -16547,7 +17908,10 @@ components:
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
operation:
$ref: '#/components/schemas/BatchOperation'
items:
@@ -16569,7 +17933,10 @@ components:
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
operation:
$ref: '#/components/schemas/BatchOperation'
items:
@@ -16588,21 +17955,115 @@ components:
description: Request object to list products for a given product group filter.
type: object
oneOf:
- - description: Request object to list products for a given feed_id and product
- group filter.
- type: object
- additionalProperties: false
- properties:
- feed_id:
- description: Catalog Feed id pertaining to the catalog product group filter.
- example: '2680059592705'
- type: string
- pattern: ^\d+$
- filters:
- $ref: '#/components/schemas/CatalogsProductGroupFilters'
- required:
- - feed_id
- - filters
+ - $ref: '#/components/schemas/CatalogsListProductsByFeedBasedFilter'
+ - $ref: '#/components/schemas/CatalogsVerticalsListProductsByCatalogBasedFilterRequest'
+ CatalogsListProductsByFeedBasedFilter:
+ title: feed based product group
+ description: Request object to list products for a given feed_id and product
+ group filter.
+ type: object
+ additionalProperties: false
+ properties:
+ feed_id:
+ description: Catalog Feed id pertaining to the catalog product group filter.
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ filters:
+ $ref: '#/components/schemas/CatalogsProductGroupFilters'
+ required:
+ - feed_id
+ - filters
+ CatalogsVerticalsListProductsByCatalogBasedFilterRequest:
+ type: object
+ title: catalog based product group
+ description: Request object to list products for a given catalog_id and product
+ group filter.
+ oneOf:
+ - $ref: '#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest'
+ - $ref: '#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest'
+ - $ref: '#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest'
+ discriminator:
+ propertyName: catalog_type
+ mapping:
+ RETAIL: '#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest'
+ HOTEL: '#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest'
+ CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest'
+ CatalogsRetailListProductsByCatalogBasedFilterRequest:
+ type: object
+ title: retail_list_products_by_catalog_based_filter_request
+ additionalProperties: false
+ description: Request object to list products for a given retail catalog_id and
+ product group filter.
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - RETAIL
+ description: Retail catalog based product group is available only for selected
+ partners at the moment. If you are not eligible, please use feed based
+ one.
+ catalog_id:
+ description: Catalog id pertaining to the retail product group.
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ filters:
+ $ref: '#/components/schemas/CatalogsProductGroupFilters'
+ country:
+ $ref: '#/components/schemas/Country'
+ locale:
+ $ref: '#/components/schemas/CatalogsLocale'
+ required:
+ - catalog_type
+ - catalog_id
+ - filters
+ - country
+ - locale
+ CatalogsHotelListProductsByCatalogBasedFilterRequest:
+ type: object
+ title: hotel_list_products_by_catalog_based_filter_request
+ additionalProperties: false
+ description: Request object to list products for a given hotel catalog_id and
+ product group filter.
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - HOTEL
+ catalog_id:
+ description: Catalog id pertaining to the hotel product group.
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ filters:
+ $ref: '#/components/schemas/CatalogsHotelProductGroupFilters'
+ required:
+ - catalog_type
+ - catalog_id
+ - filters
+ CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest:
+ type: object
+ title: creative_assets_list_products_by_catalog_based_filter_request
+ additionalProperties: false
+ description: Request object to list products for a given creative assets catalog_id
+ and product group filter.
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - CREATIVE_ASSETS
+ catalog_id:
+ description: Catalog id pertaining to the creative assets product group.
+ example: '2680059592705'
+ type: string
+ pattern: ^\d+$
+ filters:
+ $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilters'
+ required:
+ - catalog_type
+ - catalog_id
+ - filters
CatalogsLocale:
type: string
enum:
@@ -16654,14 +18115,22 @@ components:
- zh-TW
CatalogsProduct:
type: object
+ description: Catalogs product for all verticals
properties:
- metadata:
- $ref: '#/components/schemas/CatalogsProductMetadata'
- pin:
- $ref: '#/components/schemas/Pin'
+ catalog_type:
+ $ref: '#/components/schemas/CatalogsType'
required:
- - metadata
- - pin
+ - catalog_type
+ oneOf:
+ - $ref: '#/components/schemas/CatalogsRetailProduct'
+ - $ref: '#/components/schemas/CatalogsHotelProduct'
+ - $ref: '#/components/schemas/CatalogsCreativeAssetsProduct'
+ discriminator:
+ propertyName: catalog_type
+ mapping:
+ RETAIL: '#/components/schemas/CatalogsRetailProduct'
+ HOTEL: '#/components/schemas/CatalogsHotelProduct'
+ CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsProduct'
CatalogsVerticalProductGroup:
type: object
title: product_group
@@ -16912,6 +18381,7 @@ components:
filters:
$ref: '#/components/schemas/CatalogsProductGroupFilters'
is_featured:
+ deprecated: true
description: boolean indicator of whether the product group is being featured
or not
type: boolean
@@ -16939,6 +18409,12 @@ components:
type: string
pattern: ^\d+$
nullable: true
+ country:
+ type: string
+ nullable: true
+ locale:
+ type: string
+ nullable: true
required:
- filters
- id
@@ -17060,6 +18536,7 @@ components:
type: string
nullable: true
is_featured:
+ deprecated: true
description: boolean indicator of whether the product group is being featured
or not
type: boolean
@@ -17107,6 +18584,7 @@ components:
- $ref: '#/components/schemas/CustomLabel4Filter'
- $ref: '#/components/schemas/ItemGroupIdFilter'
- $ref: '#/components/schemas/GenderFilter'
+ - $ref: '#/components/schemas/MediaTypeFilter'
- $ref: '#/components/schemas/ProductType4Filter'
- $ref: '#/components/schemas/ProductType3Filter'
- $ref: '#/components/schemas/ProductType2Filter'
@@ -17267,11 +18745,67 @@ components:
default: false
required:
- values
- CatalogsProductGroupProductCounts:
- title: catalogs_product_group_product_counts
+ CatalogsProductGroupProductCountsVertical:
+ type: object
description: Product counts for a CatalogsProductGroup
+ properties:
+ catalog_type:
+ $ref: '#/components/schemas/CatalogsType'
+ required:
+ - catalog_type
+ oneOf:
+ - $ref: '#/components/schemas/CatalogsRetailProductGroupProductCounts'
+ - $ref: '#/components/schemas/CatalogsHotelProductGroupProductCounts'
+ - $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts'
+ discriminator:
+ propertyName: catalog_type
+ mapping:
+ RETAIL: '#/components/schemas/CatalogsRetailProductGroupProductCounts'
+ HOTEL: '#/components/schemas/CatalogsHotelProductGroupProductCounts'
+ CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts'
+ CatalogsHotelProductGroupProductCounts:
+ title: catalogs_hotel_product_group_product_counts
+ description: Product counts for a Hotel CatalogsProductGroup
+ type: object
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - HOTEL
+ total:
+ type: number
+ minimum: 0
+ required:
+ - catalog_type
+ - total
+ CatalogsCreativeAssetsProductGroupProductCounts:
+ title: catalogs_creative_assets_product_group_product_counts
+ description: Product counts for a Creative Assets CatalogsProductGroup
+ type: object
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - CREATIVE_ASSETS
+ total:
+ type: number
+ minimum: 0
+ videos:
+ type: number
+ minimum: 0
+ required:
+ - catalog_type
+ - total
+ - videos
+ CatalogsRetailProductGroupProductCounts:
+ title: catalogs_retail_product_group_product_counts
+ description: Product counts for a Retail CatalogsProductGroup
type: object
properties:
+ catalog_type:
+ type: string
+ enum:
+ - RETAIL
in_stock:
type: number
minimum: 0
@@ -17284,7 +18818,11 @@ components:
total:
type: number
minimum: 0
+ videos:
+ type: number
+ minimum: 0
required:
+ - catalog_type
- in_stock
- out_of_stock
- preorder
@@ -17331,14 +18869,30 @@ components:
type: string
nullable: true
is_featured:
+ deprecated: true
description: boolean indicator of whether the product group is being featured
or not
type: boolean
filters:
$ref: '#/components/schemas/CatalogsProductGroupFiltersRequest'
- CatalogsProductMetadata:
+ CatalogsRetailProduct:
+ type: object
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - RETAIL
+ metadata:
+ $ref: '#/components/schemas/CatalogsRetailProductMetadata'
+ pin:
+ $ref: '#/components/schemas/Pin'
+ required:
+ - catalog_type
+ - metadata
+ - pin
+ CatalogsRetailProductMetadata:
type: object
- description: Product metadata entity
+ description: Retail product metadata entity
properties:
item_id:
description: The user-created unique ID that represents the product.
@@ -17520,11 +19074,16 @@ components:
additionalProperties: false
properties:
catalog_type:
- $ref: '#/components/schemas/CatalogsType'
+ type: string
+ enum:
+ - RETAIL
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
items:
minItems: 1
maxItems: 1000
@@ -17598,9 +19157,6 @@ components:
type: string
enum:
- CREATE
- - UPDATE
- - UPSERT
- - DELETE
attributes:
$ref: '#/components/schemas/ItemAttributesRequest'
required:
@@ -17618,10 +19174,7 @@ components:
operation:
type: string
enum:
- - CREATE
- UPDATE
- - UPSERT
- - DELETE
attributes:
$ref: '#/components/schemas/UpdatableItemAttributes'
update_mask:
@@ -17691,10 +19244,7 @@ components:
operation:
type: string
enum:
- - CREATE
- - UPDATE
- UPSERT
- - DELETE
attributes:
$ref: '#/components/schemas/ItemAttributesRequest'
required:
@@ -17712,9 +19262,6 @@ components:
operation:
type: string
enum:
- - CREATE
- - UPDATE
- - UPSERT
- DELETE
required:
- item_id
@@ -17725,11 +19272,16 @@ components:
additionalProperties: false
properties:
catalog_type:
- $ref: '#/components/schemas/CatalogsType'
+ type: string
+ enum:
+ - HOTEL
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
items:
minItems: 1
maxItems: 1000
@@ -17836,6 +19388,31 @@ components:
description: Required for countries with a postal code system. Postal or
zip code of the hotel.
type: string
+ CatalogsHotelProduct:
+ type: object
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - HOTEL
+ metadata:
+ $ref: '#/components/schemas/CatalogsHotelProductMetadata'
+ pin:
+ $ref: '#/components/schemas/Pin'
+ required:
+ - catalog_type
+ - metadata
+ - pin
+ CatalogsHotelProductMetadata:
+ type: object
+ description: Hotel product metadata entity
+ properties:
+ hotel_id:
+ description: The user-created unique ID that represents the hotel item.
+ example: 123abc
+ type: string
+ required:
+ - hotel_id
CatalogsUpdatableHotelAttributes:
type: object
properties:
@@ -17911,17 +19488,58 @@ components:
guest_ratings:
description: If specified, you must provide all properties
$ref: '#/components/schemas/CatalogsHotelGuestRatings'
+ CatalogsCreativeAssetsProductMetadata:
+ type: object
+ description: Creative assets product metadata entity
+ properties:
+ creative_assets_id:
+ description: The user-created unique ID that represents the creative assets
+ item.
+ example: 123abc
+ type: string
+ visibility:
+ $ref: '#/components/schemas/CreativeAssetsVisibilityType'
+ required:
+ - creative_assets_id
+ - visibility
+ CatalogsCreativeAssetsProduct:
+ type: object
+ properties:
+ catalog_type:
+ type: string
+ enum:
+ - CREATIVE_ASSETS
+ metadata:
+ $ref: '#/components/schemas/CatalogsCreativeAssetsProductMetadata'
+ pin:
+ $ref: '#/components/schemas/Pin'
+ required:
+ - catalog_type
+ - metadata
+ - pin
+ CreativeAssetsVisibilityType:
+ description: Creative assets visibility.
+ nullable: false
+ type: string
+ enum:
+ - VISIBLE
+ - HIDDEN
CatalogsCreativeAssetsBatchRequest:
description: Request object to update catalogs creative assets items
type: object
additionalProperties: false
properties:
catalog_type:
- $ref: '#/components/schemas/CatalogsType'
+ type: string
+ enum:
+ - CREATIVE_ASSETS
country:
$ref: '#/components/schemas/Country'
language:
- $ref: '#/components/schemas/Language'
+ description: We recommend using the CatalogsLocale values.
+ anyOf:
+ - $ref: '#/components/schemas/CatalogsLocale'
+ - $ref: '#/components/schemas/Language'
items:
minItems: 1
maxItems: 1000
@@ -18216,18 +19834,33 @@ components:
additionalProperties: false
properties:
event_name:
- description: "The type of the user event. Please use the right event_name\
- \ otherwise the event won\u2019t be accepted and show up correctly\
- \ in reports.
add_to_cart checkout\
- \ custom lead page_visit\
- \ search signup view_category\
- \ watch_video"
+ description: |
+ The type of the user event. Please use the right event_name otherwise the event won't be accepted and show up correctly in reports. +
add_to_cartcheckoutcustomleadpage_visitsearchsignupview_categorywatch_videoapp_android app_ios web
- offline
+ description: |
+ + The source indicating where the conversion event occurred. +
app_androidapp_iosweboffline<= 2,000 characters
+Hosted link to the product video.
+File types for linked videos must be .mp4, .mov or .m4v.
+File size cannot exceed 2GB.
+ example: https://www.example.com/cat/womens-clothing/denim-shirt-0294.mp4 + type: string + nullable: true - $ref: '#/components/schemas/UpdatableItemAttributes' ItemAttributesRequest: type: object @@ -20716,6 +22496,15 @@ components: - description: The main product image link. type: string nullable: false + video_link: + description: |- +<= 2,000 characters
+Hosted link to the product video.
+File types for linked videos must be .mp4, .mov or .m4v.
+File size cannot exceed 2GB.
+ example: https://www.example.com/cat/womens-clothing/denim-shirt-0294.mp4 + type: string + nullable: true - $ref: '#/components/schemas/UpdatableItemAttributes' ItemBatchRecord: type: object @@ -21019,10 +22808,10 @@ components: title: archived bid: type: integer - minimum: 1 - description: Keyword custom bid in microcurrency - null if inherited from - parent ad group. - example: 200000 + description: Note: bid field has been deprecated. Input + will not be set and field will return null. Keyword custom bid in microcurrency + - null if inherited from parent ad group. + example: null nullable: true title: bid required: @@ -21031,11 +22820,10 @@ components: type: object properties: keywords: - description: 'Keywords to update. Object array. Each object has 3 possible + description: 'Keywords to update. Object array. Each object has 2 possible fields:2023-03-20,
+ Profile visits and Follows will only be available for Idea Pins. These metrics
+ are available for all Pin formats since then. Keep in mind this cannot have
ALL if split_field is set to any value other than NO_SPLIT.
explode: false
in: query
@@ -29042,6 +31597,8 @@ components:
- SAVE_RATE
- TOTAL_COMMENTS
- TOTAL_REACTIONS
+ - USER_FOLLOW
+ - PROFILE_VISIT
- description: Video Pin metric types
type: string
enum:
@@ -29086,9 +31643,6 @@ components:
- ADS_PRODUCT
- ADS_VIDEO
- ADS_IDEA
- - PRODUCT
- - REGULAR
- - VIDEO
type: string
query_pin_order_id:
description: The pin order id associated with the ssio insertino order
@@ -29140,6 +31694,13 @@ components:
required: false
schema:
type: string
+ query_account_type:
+ description: Filter accounts by account type.
+ in: query
+ name: account_type
+ required: true
+ schema:
+ $ref: '#/components/schemas/AudienceAccountType'
query_report_type:
name: report_type
description: Report type.
@@ -29150,6 +31711,18 @@ components:
enum:
- SYNC
- ASYNC
+ query_required_pin_ids:
+ name: pin_ids
+ description: List of Pin IDs.
+ in: query
+ required: true
+ schema:
+ type: array
+ items:
+ type: string
+ pattern: ^\d+$
+ minItems: 1
+ maxItems: 100
query_required_search_query:
description: Search query. Can contain pin description keywords or comma-separated
pin IDs.
@@ -29170,6 +31743,7 @@ components:
enum:
- AD_ACCOUNT
- PROFILE
+ - ASSET_GROUP
default: AD_ACCOUNT
example: AD_ACCOUNT
query_search_query: