Batching modifications to catalog items helps save time and resources. You can use different methods for managing catalog items:
Set up a static feed, uploading batch data on a scheduled basis, which works well for smaller catalogs that do not change as frequently.
Use the Pinterest API to make real-time programmatic changes, which works well for large, more dynamic catalogs.
Combine these methods, using a feed for regular, bulk changes and the API for attributes that change frequently throughout the day, such as price or availability.
How batch requests work with the API
When you submit a batch request, the endpoint returns a status and a
batch_id
for tracking purposes, whether the request has completed, failed, or is still in progress.
Make sure you have business access to any catalog you want to see or modify.
Make sure you have business access to any catalog you want to see or modify.
Select an operation type
Select an operation type
Set the
operation
parameter to a value that supports what you want to do:
Batch operations
Operation
Action
Notes
Available with feed?
CREATE
Add new items.
Use if you are certain that items do not exist.
Best for real-time additions.
No
UPDATE
Change attributes for existing items.
Use if you are certain that items exist. Best for real-time item modifications.
You can modify specific attributes while leaving other attributes unchanged.
Yes
DELETE
Remove items, including Pins and metadata.
Removes all merchant data from the existing item.
Yes
UPSERT
Add or change items.
Use if you are uncertain whether certain items exist.
You must include all attributes in the API request, even if you are only modifying a subset.
No
Working with different catalog types
Data requirements for batch modifications vary depending on the type of catalog you are modifying:
Catalog types
Catalog type
Use case
RETAIL
Retail businesses manage and promote product inventory, creating product Pins for shopping ads.
HOTEL
Hotel businesses manage room inventory and promote their offerings.
CREATIVE_ASSETS
Businesses manage creative content for use in various advertising formats.
See the endpoint for the full set of requirements for each catalog type.
Try out batch operations in Sandbox
Use the Sandbox to try running batch operations in a non-production environment. This enables you to understand how API calls are structured and proactively address any issues with batch modifications before you run these operations for a catalog in production.
How Sandbox differs from production
As you test batching operations in Sandbox, be aware of certain limitations and differences from the production environment:
To use Sandbox, you need a Sandbox access token, which is different from the OAuth token you use to call endpoints in production. See Step 1 below.
The structure of API calls in Sandbox is identical to those in production, except that every Sandbox endpoint path includes
Any catalogs you create in Sandbox do not transfer to production, so you will need to create new catalogs in production. You can use the exact same code, except for removing
-sandbox
from the endpoint URL paths.
Data updates in Sandbox do not occur on a regular basis as they do in production. Your product count and product lists by product group calls may not not always return accurate, up-to-date results. Make sure to test these product group endpoints in production.
See the Sandbox guide to understand all capabilities and limitations.