Before you can set up Catalogs, you need to complete these steps. Click a link below to jump to the section you need:
Is Catalogs for you?
Catalogs is a feed-ingestion tool designed for businesses who sell products on their websites. Using Catalogs requires:
- A Pinterest business account
- A data source- a file that contains a list of your products and their corresponding attributes, may also be called a product catalog or product feed
- A claimed website
- A website that meets our Merchant Guidelines, with a clear and easy-to-find shipping policy, refund policy, and contact details
- Data source hosting- a way to consistently host and store a data source of your products that you can send to Pinterest daily
If you don’t meet these conditions and you want to create Shopping Pins, you can partner with an e-commerce website to format your products for Pinterest. So far, we have integrations with GoDataFeed and Productsup. You can also promote your content in other ways on Pinterest.
Data source overview
What's a data source?
A data source (also commonly known as a product catalog, product feed, or data feed) is a file with a list of your products and their corresponding attributes structured in a specific way. This file is processed daily to dynamically create Pins from your products.
How a data source works
To submit a data source to Pinterest, you provide a URL link to where we can access your data source file. We'll validate the file and create a product Pin for each item that passes our validation. See more about Data Source Specifications.
Maintaining a data source
Hosting a data source starts an ongoing effort to provide updated information about the products you have available. Pinterest will ingest your data source daily, and alert you to any errors. It's important to review and fix errors as quickly as possible to make sure your product info is accurate and up-to-date.
Depending on the error type, an error can mean your whole feed doesn't update, some items on your feed don't update, or you need to make some changes to align with best practices. Learn more about troubleshooting error messages.
More about data sources:
- Update daily. We ingest your data source once every 24 hours. Make your updated full data source available daily to keep your product details up-to-date. We don't support scheduling or on-demand ingestion.
- Host your data source. Host your own data source on an FTP/SFTP server or with an HTTP/HTTPS direct-download link. This needs to be accessible by a user-agent, and can't require IP or SSH key whitelisting. If you're using a direct download link, there can't be any extra navigation required for Pinterest to access the file. We don't provide data source hosting.
- Max 5 million products. We can process up to 5 million products per account. If your data source has more than 5 million products, we'll process the first 5 million rows.
- One data source per business account.
Have a claimed website on Pinterest
All destination URLs in your data source must have a web domain that is registered as a claimed website on Pinterest. A business can claim multiple domains, but each domain can only be claimed by a single Pinterest business account. Learn how to claim your website.
Prepare your data source
Before you can set up your feed, you have to create a data source—a file that contains a list of your products and their corresponding attributes.
Catalogs data source hosting requirements
You must provide your own hosting on an FTP/SFTP server, or set up an HTTP/HTTPS direct download link. Pinterest does not provide hosting for users. Your data source location should be accessible by a user-agent, and not require any IP or SSH key whitelisting. If you are using a direct download link in the form of HTTP/HTTPS, your link must not have any additional navigation required for Pinterest to access the file.
Catalogs data source format requirements
Supported formats:
- Tab separated (tsv) (Download TSV example)
- Comma separated (csv) (Download CSV example)
- XML (RSS 2.0) (Download XML example)
Formatting tips:
- If you're using a csv, we wrap your values in double quotes to avoid any possible parsing issues
- Additional floating delimiter (comma, tab) can result in the item or file not processing properly
- Ensure delimiters for all your columns and rows are correctly set up by checking to make sure you have the same number of delimiters in each row.
- The specifications for the feed must follow standardized American English for the required and set values.
- For tab delimited or comma delimited files, data source file must be plain text, UTF-8 or Latin1 encoded.
Product data requirements
Make sure you follow our Merchant Guidelines. We may remove products or accounts that violate these guidelines.
Required and optional fields
There are 7 required fields. If any of these fields are missing, or are not properly formatted, your entire feed will fail ingestion.
Required fields:
- id
- title
- description
- link
- image_link
- price
- availability
There are also optional fields you can add to help Pinterest better map your products to Pinners. The more information you provide, the more relevant your Pins will be to the Pinners who see them. We strongly recommend adding our optional fields as well to add more detail to your feed and improve relevancy.
Required fields
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
| id |
The user-created unique ID that represents the product. Only Unicode characters are accepted. |
Max 127 characters | DS0294-L | required |
| title | The name of the product. Must be the same name as the product from the landing page. Include the variant details, such as color and size. | Max 500 characters | Women’s denim shirt, large | required |
| description | Description of the product. This field does not support HTML and must be in plain text for optimal experience. | Max 10,000 characters | Casual fit denim shirt made with the finest quality Japanese denim. | required |
| link | The landing page for the product. The link must lead directly to the same product and showcase the same data. We recommend against hardwalls. The URL must start with http:// or https:// | Max 511 characters | https://www.example.com/cat/womens-clothing/denim-shirt-0294 | required |
| image_link |
The link to the product image. The URL must be accessible by a user-agent, and send the accurate image. Please make sure there are no template or placeholder images at the link. Must start with http:// or https:// Commas must be encoded or removed if they are part of the image link, as currently we are unable to process image links containing commas. |
https://scene.example.com/image/image.jpg | required | |
| price | The price of the product. The price should include currency in ISO-4217 if it is not US dollars. If the currency is not included, we default to US dollars. We accept currency after the numeric price value, with or without space. Currency should follow the standard ISO-4217 code. We do not accept 0 values for price. Do not use currency symbols. |
<numeric> <ISO 4217> |
24.99 USD 24.99USD 24.99 24.99 GBP |
required |
| availability | The availability of the product. Must be one of the following values: ‘in stock’, ‘out of stock’, ‘preorder’. | in stock out of stock preorder |
in stock | required |
Optional general attributes
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
| product_type | The categorization of your product based on your custom product taxonomy. Subcategories must be sent separated by “ > “. The > must be wrapped by spaces. We do not recognize any other delimiters such as comma or pipe. |
L0 > L1 > L2 > L3 > L4 Max 1000 characters |
Clothing > Women’s > Shirts > Denim | optional |
| additional_image_link |
The links to additional images for your product. Separate each additional image with comma. We recommend enclosing the whole string with quotes. Must begin with http:// or https://
Commas must be encoded or removed if they are part of the image link, as currently we are unable to process image links containing commas. We will create a new pin for every additional image link sent. |
"https://scene.example.com/image/image_v2.jpg, https://scene.example.com/image/image_v3.jpg" | optional | |
| mobile_link | The mobile-optimized version of your landing page. Must begin with http:// or https:// | https://m.example.com/cat/womens-clothing/denim-shirt-0294 | optional | |
| sale_price | The discounted price of the product. The sale_price must be lower than the price. Include currency in the same setup as price. It should include currency in ISO-4217 if it is not US dollars. If the currency is not included, we default to US dollars. We accept currency after the numeric price value, with or without space. We do not accept 0 values. Do not use currency symbols. |
<numeric> <ISO 4217> |
14.99 USD 14.99USD 14.99 14.99 GBP |
optional |
Optional product identifier
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
| item_group_id | The parent ID of the product. | Max 127 characters | DS0294 | required for items with multiple variants |
|
brand |
The brand of the product. | Josie’s Denim | optional | |
| gtin | The unique universal product identifier. | Numeric | 3234567890126 | optional |
| mpn | Manufacturer Part Number are alpha-numeric codes created by the manufacturer of a product to uniquely identify it among all products from the same manufacturer. | Alphanumeric | "mpn": "PI12345NTEREST" |
optional |
Optional product characteristics
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
|
color |
The primary color of the product | blue | optional | |
| gender | The gender associated with the product. Must be one of the following values if sent: ‘male’, ‘female’, ‘unisex’ | male female unisex |
female | optional |
| age_group | The age group to apply a demographic range to the product. Must be the one of the following values: ‘newborn’, ‘infant’, ‘toddler’, ‘kids’, ‘adult’ | newborn infant toddler kids adult |
adult | optional |
| material | The material used to make the product. | cotton | optional | |
| pattern | Description of the pattern used for the product. | plaid | optional | |
| size | The size of the product. | M | optional | |
| size_type | Additional description for the size. Must be one of the following values if sent: ‘regular’, ‘petite’, ‘plus’, ‘big_and_tall’, ‘maternity’ | regular petite plus big_and_tall maternity |
regular | optional |
| size_system | Indicates the country’s sizing system in which you are submitting your product. | Country code |
US |
optional |
Optional tax and shipping data
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
| tax | Each tax attribute group can consist of 4 sub-attributes: country:region:rate (required):tax_ship All colons, even for blank values, are required. |
country:region:rate(required):tax_ship | US:1025433:6.00:y | optional |
| shipping | Each delivery attribute group can consist of 4 sub-attributes: country, region, service, and price (required). All colons, even for blank values, are required. |
country:region:service:price(required) |
US:CA:Ground:0 USD US::Express:13.12 |
optional |
|
shipping_weight |
The weight of the product. Ensure there is a space between the numeric string and the metric. | <numeric> <metric> | 3 kg 5 lbs |
optional |
| shipping_width | The width of the package needed to ship the product. Ensure there is a space between the numeric string and the metric. | <numeric> <metric> | 16 in | optional |
| shipping_height | The height of the package needed to ship the product. Ensure there is a space between the numeric string and the metric. | <numeric> <metric> | 12 in | optional |
Optional adult product flag
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
| adult | Set this attribute to TRUE if you are submitting items that are considered “adult”. These will not be shown on Pinterest. | TRUE FALSE |
true | optional |
Optional custom labels
Custom grouping of products. These can be used for a variety of purposes such as seasonal, promotions, best sellers. We accept up to 5 different custom labels.
You will be able to create product groups in Catalogs using custom labels.
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
| custom_label_0 | Custom grouping of products. | Max 1000 characters |
Best sellers Summer promotion |
optional |
| custom_label_1 | Custom grouping of products. | Max 1000 characters | optional | |
| custom_label_2 | Custom grouping of products. | Max 1000 characters | optional | |
| custom_label_3 | Custom grouping of products. | Max 1000 characters | optional | |
| custom_label_4 | Custom grouping of products. | Max 1000 characters | optional |
Optional shopping ad fields
| Column name | Description | Syntax/supported values | Example | Requirement |
|---|---|---|---|---|
| ad_link | Allows advertisers to specify a separate URL that can be used to track traffic coming from Pinterest shopping ads. Must send full URL including tracking, do not send tracking parameters only. At this time we do not support impression tracking. Must begin with http:// or https:// | string URL | https://www.example.com/cat/denim-shirt/item012?utm_source=Pinterest | optional |
| condition | The condition of the product. Must be one of the following values: ‘new’, ‘used’, ‘refurbished’. | new used refurbished |
new | optional |
| google_product_category | The categorization of the product based on the standardized Google Product Taxonomy. This is a set taxonomy. Both the text values and numeric codes are accepted. | Full taxonomy | Apparel & Accessories > Clothing > Shirts & Tops 212 |
optional |
Set up the Pinterest tag
The Pinterest tag is a piece of JavaScript code you put on your website to gather conversion insights and build audiences to target based on actions they’ve taken on your site.
Be sure to send shopping-specific fields through the Pinterest tag.
- Must have the Pinterest tag implemented with the following conversion types:
PageVisits,AddToCart, andCheckouts - Must pass event data for “product_id” as an attribute for
PageVisit,AddToCart, andCheckouts.- Product_id must pass under a line item (won’t be visible in Conversions view page).
- Please use the Tag Helper Chrome Extension to double-check that you have product IDs passing back on product detail pages.
- The product_id data passed in the tag must match the "item_group_id" or "id" provided in the data source
- Minimum of a combined 100K PageVisit and AddtoCart events in the last 7 days passing back product IDs
What's the next step?
See our Data source ingestion guide to learn how to connect your product feed to Pinterest.