Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Work with catalogs and product groups

The Pinterest API helps developers, merchants and advertisers manage the shopping experience. It allows you to:
  • Manage your product catalogs on Pinterest using a regularly scheduled catalog feed or near-real-time bulk updates
  • Manage product groups that can be displayed on your Shop Tab and can be promoted together as part of a campaign
  • Generate catalog diagnostic reports
  • Create and manage shopping ads and the associated campaigns, ad groups, and product groups

Before getting started

To manage catalogs, you must first have a business account on Pinterest.
Merchants are required to claim their domain to have full access to shopping capabilities.

Permissions and access levels

In order to access shopping features via the API you will need to request the
catalogs:read
and
catalogs:write
scopes during your OAuth flow. The API will respect the business access permissions of the tokened user.
If you need assistance, please reach out via the Pinterest Help Center.

Catalog management features

Included in the Catalog Management suite are these endpoints:
  1. DELETE
    Delete product groups
  2. PATCH
    Update single product group
  3. GET
    List product groups
  4. POST
    Create product group
  5. GET
    List feeds
  6. POST
    Create feed
  7. GET
    Get feed
  8. PATCH
    Update feed
  9. DELETE
    Delete feed
  10. GET
    List feed processing results
  11. POST
    Ingest feed items

Is an app ID linked to a merchant account ID?

An app is not linked to a merchant account ID. As long as the app has requested the correct scopes during the OAuth flow:
  • Any Pinterest user who has the right permissions on the merchant account will be able to access these features.
  • An owning developer who has authenticated as has feeds, can operate on its own account for testing or production purposes.

Manage catalog feed

Using a feed lets you schedule regular updates to your entire catalog. Pinterest will ingest the feed, process the information, and update the items in your catalog.
Manage a feed with these endpoints:
  • GET
    List feeds
  • GET
    Get feed
  • POST
    Create feed
  • PATCH
    Update feed
  • DELETE
    Delete feed

Retail partners

For Retail partners, all endpoints are supported. For more details on account requirements and how retail catalogs work we recommend you review our Help Center article: Get started with Catalogs.

Hotel partners

For Hotel partners, all endpoints are supported.

Manage catalog items in batch

You can create, manage, update, and delete specific items or groups of items in your catalog in batch. This is a good solution for merchants whose product attributes change frequently throughout the day, for example if a product's price fluctuates during the day.
Use these endpoints:
  • POST
    Get catalogs items (POST)
  • POST
    Operate on item batch

Manage product groups for your feed

You can create product groups that contain items based on a filter, which can be grouped together on the Shop tab on your Pinterest profile and/or be promoted together as part of a campaign.
Use:
  • GET
    List product groups
  • POST
    Create product group
  • PATCH
    Update single product group
  • DELETE
    Delete product group
Product groups can be data source agnostic and a set of filters that define the products to be included. Changes made to a product group only affect that specific product group, not the individual products within it.

Create a shopping ad

A shopping ad is a single image ad that promotes a product relevant to people's interests. Learn more about shopping ads.
Shopping ads use the Catalog sales objective. To create a shopping ad via the API, use the following steps:
  1. Set up a product catalog via a feed or API
  2. Manage product groups
  3. Create the campaign with
    POST
    Create campaigns
    and set
    objective_type
    =
    CATALOG_SALES
  4. Create the ad group with
    POST
    Create ad groups
  5. Add the product groups you want to use in the shopping ad to the ad group using
    POST
    Create product group promotions
The items in the promoted product group are your shopping ads.

Ads reporting and analytics

Detailed information on ads reporting and analytics can be found under Ads Reporting. If you are using targeting, see Set up targets for your ads.
To get analytics about specific ads, use the
GET
Get ad analytics
endpoint. You will need to provide the
ad_account_id
and can additionally request multiple
ad_ids
that you want the analytics for. You can get similar analytics for a given ad group, product group, campaign, or for your ad account as a whole, as detailed in our Ads Reporting guide.
If you want a report with a large number of different metrics or historical data, we recommend using the asynchronous reports under Ads Analytics.

Resources

  • Feed optimization playbook
  • Help Center: Claim your website
  • Help Center: Shopping ads
NEXT
Manage with a feed
Was this page helpful?