catalog_items
Operate on item batch
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:
- 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.
post/catalogs/items/batch
Query parameters
ad_account_idstring
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"
}