Operate on item batch
Changed onThis 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:
- 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 or via the Help Center to get assistance.
Request
- Base URLhttps://api.pinterest.com/v5
- Auth
- OAuth 2Authorization codehttps://www.pinterest.com/oauth/Token URLhttps://api.pinterest.com/v5/oauth/tokenScopescatalogs:read, catalogs:write
- or OAuth 2Client credentialsToken URLhttps://api.pinterest.com/v3/oauth/access_token/Scopescatalogs:read, catalogs:write
- TypeScriptA function with typed inputs. Its response is checked against the schema.
Query parameters
Unique identifier of an ad account.
Request body
Example request
{
"items": [
{
"attributes": {
"ad_image_0_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_0_tag": "black friday",
"ad_image_10_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_10_tag": "black friday",
"ad_image_11_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_11_tag": "black friday",
"ad_image_12_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_12_tag": "black friday",
"ad_image_13_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_13_tag": "black friday",
"ad_image_14_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_14_tag": "black friday",
"ad_image_15_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_15_tag": "black friday",
"ad_image_16_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_16_tag": "black friday",
"ad_image_17_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_17_tag": "black friday",
"ad_image_18_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_18_tag": "black friday",
"ad_image_19_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_19_tag": "black friday",
"ad_image_1_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_1_tag": "black friday",
"ad_image_2_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_2_tag": "black friday",
"ad_image_3_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_3_tag": "black friday",
"ad_image_4_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_4_tag": "black friday",
"ad_image_5_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_5_tag": "black friday",
"ad_image_6_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_6_tag": "black friday",
"ad_image_7_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_7_tag": "black friday",
"ad_image_8_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_8_tag": "black friday",
"ad_image_9_link": "https://www.example.com/image/image_v2.jpg",
"ad_image_9_tag": "black friday",
"ad_link": "https://www.example.com/cat/denim-shirt/item012?utm_source=Pinterest",
"ad_video_0_link": "https://www.example.com/video/video_v2.mov",
"ad_video_0_tag": "black friday",
"ad_video_1_link": "https://www.example.com/video/video_v2.mov",
"ad_video_1_tag": "black friday",
"ad_video_2_link": "https://www.example.com/video/video_v2.mov",
"ad_video_2_tag": "black friday",
"adult": true,
"age_group": "newborn",
"ai_disclosures": [
{
"url": "https://scene.example.com/image/image_v3.jpg",
"disclosure": [
"ai_modified"
]
}
],
"android_deep_link": "pinterest://item/1234567890",
"availability": "in stock",
"average_review_rating": 5,
"brand": "Josie's Denim",
"color": "blue",
"condition": "new",
"custom_label_0": "Best sellers",
"custom_label_1": "Summer promotion",
"custom_label_2": "Winter sales",
"custom_label_3": "Woman dress",
"custom_label_4": "Man hat",
"custom_number_0": 10,
"custom_number_2": 1520000000,
"custom_number_3": 4294967295,
"custom_number_4": 50,
"description": "Casual fit denim shirt made with the finest quality Japanese denim.",
"free_shipping_label": true,
"free_shipping_limit": "35 USD",
"gender": "unisex",
"google_product_category": "Apparel & Accessories > Clothing > Shirts & Tops",
"id": "DS0294-L",
"installment_price": "10:10.00 USD",
"ios_deep_link": "pinterest://item/1234567890",
"item_group_id": "DS0294",
"last_updated_time": 1641483432072,
"link": "https://www.example.com/cat/womens-clothing/denim-shirt-0294",
"material": "cotton",
"min_ad_price": "19.99 USD",
"mobile_link": "https://m.example.com/cat/womens-clothing/denim-shirt-0294",
"mpn": "PI12345NTEREST",
"number_of_ratings": 10,
"number_of_reviews": 10,
"pattern": "plaid",
"price": "24.99 USD",
"product_type": "Clothing > Women's > Shirts > Denim",
"promotion_id": "promotion_1",
"sale_price": "14.99 USD",
"sale_price_effective_date": "2025-01-01T00:00:00.000000Z/2025-01-07T00:00:00.000000Z",
"shipping": "US:CA:Ground:0 USD",
"shipping_height": "12 in",
"shipping_weight": "3 kg",
"shipping_width": "16 in",
"size": "M",
"size_system": "US",
"size_type": "regular",
"tax": "US:1025433:6.00:y",
"title": "Women's denim shirt, large",
"unit_pricing_base_measure": "10 ML",
"unit_pricing_measure": "10 ML",
"variant_names": [
"Color",
"Size"
],
"variant_values": [
"Red",
"Small"
]
},
"item_id": "DS0294-M"
}
],
"language": "EN"
}Response
The request has succeeded.
Example response
{
"completed_time": "2024-01-01T20:20:00Z",
"created_time": "2024-01-01T20:10:40Z",
"items": [
{
"errors": [
{
"attribute": "title",
"code": 106,
"message": "Title is missing from product metadata."
}
],
"item_id": "DS0294-M",
"status": "SUCCESS",
"warnings": [
{
"attribute": "title",
"code": 106,
"message": "Title is missing from product metadata."
}
]
}
],
"status": "PROCESSING"
}Changes
- breaking
added to the
/////request propertyallOflist - breaking
added to the
/////request propertyallOflist - breaking
added to the
/////request propertyallOflist - breaking
removed from the
//////request propertyanyOflist - breaking
removed from the
//////request propertyanyOflist - breaking
removed from the
//////request propertyanyOflist - breaking
removed the enum value
CREATEof the request property///// - breaking
removed the enum value
CREATEof the request property///// - breaking
removed the enum value
CREATEof the request property///// - breaking
removed the enum value
CREATEof the request property///// - breaking
removed the enum value
DELETEof the request property///// - breaking
removed the enum value
DELETEof the request property///// - breaking
removed the enum value
DELETEof the request property///// - breaking
removed the enum value
DELETEof the request property///// - breaking
removed the enum value
DELETE_DISCONTINUEDof the request property///// - breaking
removed the enum value
DELETE_DISCONTINUEDof the request property///// - breaking
removed the enum value
DELETE_DISCONTINUEDof the request property///// - breaking
removed the enum value
DELETE_DISCONTINUEDof the request property///// - breaking
removed the enum value
UPDATEof the request property///// - breaking
removed the enum value
UPDATEof the request property///// - breaking
removed the enum value
UPDATEof the request property///// - breaking
removed the enum value
UPDATEof the request property///// - breaking
removed the enum value
UPSERTof the request property///// - breaking
removed the enum value
UPSERTof the request property///// - breaking
removed the enum value
UPSERTof the request property///// - breaking
removed the enum value
UPSERTof the request property///// - breaking
removed
subschema #2from the////////request propertyoneOflist - breaking
the
/////request property type changed fromstringto no type - breaking
the
/////request property type changed fromstringto no type - breaking
the
/////request property type changed fromstringto no type - breaking
the
//////request property type changed from no type toobject - breaking
the
////response's property type changed fromstringto no type for status - breaking
the
////response's property type changed fromstringto no type for status - breaking
the
////response's property type changed fromstringto no type for status - breaking
removed the required property
from the response with the status - warning
removed
subschema #1subschema #3from the///////request propertyallOflist - warning
removed
subschema #1subschema #3from the///////request propertyallOflist - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - warning
the
////////request property's maxLength was set to2000 - warning
the
////////request property's maxLength was set to511 - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added to the
//////request propertyoneOflist - info
added to the
//////request propertyoneOflist - info
added to the
//////request propertyoneOflist - info
added to the
////////request propertyoneOflist - info
removed the pattern
^\d+$from the request property///// - info
removed the pattern
^\d+$from the request property///// - info
removed the pattern
^\d+$from the request property///// - info
added the non-success response with the status
- info
added the non-success response with the status
- info
the response optional property
////became not read-only for the status - info
the response optional property
////became not read-only for the status - info
the response optional property
////became not read-only for the status - info
the response optional property
////became not read-only for the status - info
the response optional property
////became not read-only for the status - info
added to the
////response propertyallOflist for the response status - info
added to the
////response propertyallOflist for the response status - info
added to the
////response propertyallOflist for the response status - info
removed the
CREATIVE_ASSETSenum value from the////response property for the response status - info
removed the
CREATIVE_ASSETSenum value from the////response property for the response status - info
removed the
HOTELenum value from the////response property for the response status - info
removed the
HOTELenum value from the////response property for the response status - info
removed the
RETAILenum value from the////response property for the response status - info
removed the
RETAILenum value from the////response property for the response status - info
the response required property
////became not read-only for the status
- breaking
- breaking
the response property
////became nullable for the status - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
/////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
//////////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
///////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
//////////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
added the new optional request property
///////// - info
the request property
/////////////////became nullable - info
the request property
/////////////////became nullable - info
the request property
/////////////////became nullable - info
the request property
/////////////////became nullable - info
the request property
/////////////became nullable - info
the request property
/////////////became nullable - info
the request property
/////////////became nullable - info
the request property
/////////////became nullable - info
the request property
/////////////////became nullable - info
the request property
/////////////////became nullable - info
the request property
/////////////////became nullable - info
the request property
/////////////////became nullable - info
the response property
////became required for the status
- breaking