Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Manage with a feed

Create and manage a catalog via a feed, with your feed you can:
  • Make updates to your catalog such as adding or removing products and modifying price or availability
Pinterest supports feeds for products, hotel inventory, and creative assets. A feed is a file that lists items and their attributes. More details about feeds:
  • They may be referred to as a product feed, data source, or catalog feed.
  • You can have up to 50 feeds.
  • Pinterest ingests your feed every 24 to 48 hours to update your entire catalog.

Before getting started

  • To manage catalogs, you must first have a business account on Pinterest.
  • Catalog management supports Business access permissions. Review our guide on using Business access with the API to ensure you can complete requests and avoid getting authorization errors.

Manage Your Catalog Feed

List feeds

Get a list of owned feeds.
  1. Make a request to
    GET
    List feeds
    .
  2. Specify an
    ad_account_id
    if using business access.
    ad_account_id
    is not needed if operating on your own account.
  3. Use
    catalog_id
    if you'd like to filter for a given catalog ID. If not given, all catalogs are returned.

Sample request

This example request returns:
  • a list of up to 15 feeds
  • since no bookmark value is provided, the list will begin at the beginning
GET /v5/catalogs/feeds?page_size=15

Sample response

The response contains:
  • a list of feeds and their attributes
  • a bookmark that can be used to request the next page of items
{
  "items": [
    // a list of feeds and their attributes
    {
      "country": "US",
      "default_availability": "IN_STOCK",
      "default_currency": "USD",
      "name": "string",
      "format": "TSV",
      "default_locale": "en_US",
      "credentials": {
        "password": "pa$$word",
        "username": "string"
      },
      "location": "string",
      "preferred_processing_schedule": {
        "time": "02:59",
        "timezone": "Africa/Abidjan"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "status": "ACTIVE",
      "catalog_type": "RETAIL"
    }
  ],
  "bookmark": "string"
}

Errors

  • If the tokened user does not have read access to any feeds, you'll receive an authorization error.
  • If either the
    page_size
    or
    bookmark
    parameter are invalid, you'll receive an invalid parameter error.

Get feed

Get a single feed by making a request to
GET
Get feed
.

Sample request

GET /v5/catalogs/feeds/{feed_id}

Sample response

{
  "country": "US",
  "default_availability": "IN_STOCK",
  "default_currency": "USD",
  "name": "string",
  "format": "TSV",
  "default_locale": "en_US",
  "credentials": {
    "password": "pa$$word",
    "username": "string"
  },
  "location": "string",
  "preferred_processing_schedule": {
    "time": "02:59",
    "timezone": "Africa/Abidjan"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "status": "ACTIVE",
  "catalog_type": "RETAIL"
}
  • If the tokened user does not have read access to the feed, you'll receive an authorization error.
  • If the
    feed_id
    parameter is invalid, you'll receive an invalid parameter error.

Create feed

Create a new feed by making a request to
POST
Create feed
.

Sample request

{
  "country": "US",
  "default_availability": "IN_STOCK",
  "default_currency": "USD",
  "name": "string",
  "format": "TSV",
  "locale": "en_US",
  "credentials": {
    "password": "pa$$word",
    "username": "string"
  },
  "location": "string",
  "preferred_processing_schedule": {
    "time": "02:59",
    "timezone": "Africa/Abidjan"
  }
}
  • POST requests must have a body. Include in the request body all the required feed information.
  • This example passes the name and location of the file to be used as the catalog feed, as well as specifies the processing schedule and access credentials.

Sample response

A successful response returns the
id
for the newly created feed.
{
  "country": "US",
  "default_availability": "IN_STOCK",
  "default_currency": "USD",
  "name": "string",
  "format": "TSV",
  "default_locale": "en_US",
  "credentials": {
    "password": "pa$$word",
    "username": "string"
  },
  "location": "string",
  "preferred_processing_schedule": {
    "time": "02:59",
    "timezone": "Africa/Abidjan"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "status": "ACTIVE",
  "catalog_type": "RETAIL"
}
The response returns:
  • Feed information that was part of the request
  • id
    of the new feed
  • Date and time when the feed was created
  • Date and time of any update (for a new feed, this will be the same as the date and time created)
  • Status of the feed
The values returned should match the values submitted except for
created_at
id
updated_at
and
status
.

Update feed

Update an existing feed owned by the operating user_account by calling
PATCH
Update feed
.

Sample request

  • PATCH requests must have a body.
  • The request URL must include the
    feed_id
    for the feed to be updated.
In this example, the request is updating the
default_availability
default_currency
feed name
feed format
credentials
location
and
preferred_processing_schedule
.
{
  "default_availability": "IN_STOCK",
  "default_currency": "USD",
  "name": "string",
  "format": "TSV",
  "credentials": {
    "password": "pa$$word",
    "username": "string"
  },
  "location": "string",
  "preferred_processing_schedule": {
    "time": "02:59",
    "timezone": "Africa/Abidjan"
  }
}

Sample response

A successful response will return all of the feed's updated information, including details which weren't changed in the request.
{
  "country": "US",
  "default_availability": "IN_STOCK",
  "default_currency": "USD",
  "name": "string",
  "format": "TSV",
  "default_locale": "en_US",
  "credentials": {
    "password": "pa$$word",
    "username": "string"
  },
  "location": "string",
  "preferred_processing_schedule": {
    "time": "02:59",
    "timezone": "Africa/Abidjan"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "id": "string",
  "updated_at": "2019-08-25T14:35:53Z",
  "status": "ACTIVE",
  "catalog_type": "RETAIL"
}

Errors

  • If the operation user_account does not have permission to create the feed, you'll receive a 403 authorization error with code of 2625.
  • If the
    feed_id
    provided in the request is invalid, you'll receive a 404 error with a 4161 code.
  • Invalid requests will receive a 400 error.

Delete feed

Make a request to
DELETE
Delete feed
to remove an owned feed.

Sample request

DELETE /v5/catalogs/feeds/(feed_id)

Sample response

Response: 204 Feed deleted successfully.

Errors

  • If the operating user_account does not have permission to delete the feed, you'll receive a 403 authorization error with a 2625 code.
  • If the
    feed_id
    is invalid, you'll receive a 404 error with a 4161 code.
  • If the feed you are attempting to delete includes a product group with active promotions, you'll receive a 409 error with a code of 4162.

List processing results for a feed

Check the processing status of a feed by making a request to
GET
List feed processing results
. The user token must have the
catalogs_read
scope.

Sample request

GET /v5/catalogs/feeds/{feed_id}/processing_results

Sample response

The response will include the following details:
  • Ingestion details such as:
  • Image download error
  • Image download connection timeout
  • Image format unrecognized
  • Line level internal error, and/or indexed product count large delta failure
  • Info counts for in stock, out of stock, preorder, and unavailable items
  • Ingestion status
  • Product counts or the number of items in the feed before processing
  • Validation details including errors and warnings
{
  "items": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "ingestion_details": {
        "errors": {
          "image_download_error": 0,
          "image_download_connection_timeout": 0,
          "image_format_unrecognize": 0,
          "line_level_internal_error": 0,
          "indexed_product_count_large_delta_failure": 0
        },
        "info": {
          "in_stock": 0,
          "out_of_stock": 0,
          "preorder": 0,
          "unavailable": 0
        }
      },
      "status": "COMPLETED",
      "product_counts": {
        "original": 0
      },
      "validation_details": {
        "errors": {
          "fetch_error": 0,
          "fetch_inactive_feed_error": 0,
          "encoding_error": 0,
          "delimiter_error": 0,
          "required_columns_missing": 0,
          "image_link_invalid": 0,
          "itemid_missing": 0,
          "title_missing": 0,
          "description_missing": 0,
          "product_category_invalid": 0,
          "product_link_missing": 0,
          "image_link_missing": 0,
          "availability_invalid": 0,
          "product_price_invalid": 0,
          "link_format_invalid": 0,
          "parse_line_error": 0,
          "adwords_format_invalid": 0,
          "product_category_missing": 0,
          "internal_service_error": 0,
          "no_verified_domain": 0,
          "adult_invalid": 0,
          "invalid_domain": 0,
          "feed_length_too_long": 0,
          "link_length_too_long": 0,
          "malformed_xml": 0,
          "redirect_invalid": 0,
          "price_missing": 0,
          "feed_too_small": 0,
          "condition_invalid": 0,
          "shopify_no_products": 0,
          "max_items_per_item_group_exceeded": 0,
          "item_main_image_download_failure": 0,
          "pinjoin_content_unsafe": 0,
          "blocklisted_image_signature": 0
        },
        "warnings": {
          "title_length_too_long": 0,
          "description_length_too_long": 0,
          "gender_invalid": 0,
          "age_group_invalid": 0,
          "size_type_invalid": 0,
          "link_format_warning": 0,
          "duplicate_products": 0,
          "duplicate_links": 0,
          "sales_price_invalid": 0,
          "product_category_depth_warning": 0,
          "adwords_same_as_link": 0,
          "duplicate_headers": 0,
          "fetch_same_signature": 0,
          "adwords_format_warning": 0,
          "additional_image_link_warning": 0,
          "image_link_warning": 0,
          "shipping_invalid": 0,
          "tax_invalid": 0,
          "shipping_weight_invalid": 0,
          "expiration_date_invalid": 0,
          "availability_date_invalid": 0,
          "sale_date_invalid": 0,
          "weight_unit_invalid": 0,
          "is_bundle_invalid": 0,
          "updated_time_invalid": 0,
          "custom_label_length_too_long": 0,
          "product_type_length_too_long": 0,
          "too_many_additional_image_links": 0,
          "multipack_invalid": 0,
          "indexed_product_count_large_delta": 0,
          "item_additional_image_download_failure": 0,
          "optional_product_category_missing": 0,
          "optional_product_category_invalid": 0,
          "optional_condition_missing": 0,
          "optional_condition_invalid": 0,
          "ios_deep_link_invalid": 0,
          "android_deep_link_invalid": 0,
          "availability_normalized": 0,
          "condition_normalized": 0,
          "gender_normalized": 0,
          "size_type_normalized": 0,
          "age_group_normalized": 0,
          "utm_source_auto_corrected": 0,
          "country_does_not_map_to_currency": 0,
          "min_ad_price_invalid": 0
        }
      }
    }
  ],
  "bookmark": "string"
}

Errors

If the operating user_account does not have permission to access the feed, you'll receive an authorization error 403 with a 29 code If the feed_id is invalid, you'll receive a 404 error with a 4161 code If the request includes a parameter error, such as page_size is invalid, you'll receive a 400 error with information on the bad parameter.

Trigger an ingestion on demand for a given feed

Manually trigger the ingestion of a feed by making a request to
POST
Ingest feed items
. This will start the ingestion automatically unless there is already an ongoing ingestion or if the daily trigger ingestion limit is reached. Utilize this request when you would like to update your feed on your own cadence or you cannot wait for the next scheduled update.

Sample request

POST https://api.pinterest.com/v5/catalogs/feeds/{feed_id}/ingest

Feed parameters and attributes

  • bookmark: Value returned with a paginated request, to be used to request the next page of results.
  • country: ISO code for the feed's country.
  • created_at: Timestamp of when the feed was created.
  • credentials: Object containing the username and password required to access the data source for the feed.
  • default_availability: Value for items in this feed that do not have availability specified.
  • default_currency: Default value for currency of items in this feed that do not have currency specified, using the ISO currency codes.
  • feed_id: Unique identifier for the feed, returned when a new feed is created.
  • format: Format of the data source for the feed: TSV, CSV, or XML.
  • ingestion_details: List and count of errors, such as download, connection, or format errors and info on the number of items that are in stock, out of stock, preorder, or unavailable.
  • locale: ISO locale code to use for this feed.
  • location: Where the data source can be accessed by Pinterest for ingestion.
  • name: Name of the feed.
  • page_size: Number of items to return per page if a list is requested.
  • password: Include the password if credentials are required in the credentials object.
  • preferred_processing_schedule: Object that includes the preferred processing start time and timezone for the feed.
  • product counts: Object that includes the original product count and how many valid products Pinterest found in the feed that you sent us.
  • status: Status of the feed.
  • updated_at: Timestamp for the most recent feed update.
  • username: Include the username if credentials are required in the credentials object.
  • validation_details: Object that includes a list and count of errors and warnings that were returned during ingestion.
Was this page helpful?