Data Source specification

The columns must be titled exactly as listed below for Pinterest to recognize the data.
For any columns that require set values, All values must follow the correct syntax listed in the specifications; otherwise they will not be recognized and may result in item-level rejections.

Columns sent in the file that are not listed in Pinterest’s data source specifications below will be ignored, and we will still ingest the rest of the file. We will surface file errors for you to fix.

Download the below example files to get started building your feed. You can use either a .tsv or .csv file type.

Download TSV example
Download CSV example

Product title and description

Accurate product title and description are recommended for optimal experience on Pinterest. Having relevant key keywords in the product title and description will also help with distribution and performance, both organically and as promoted content.

Be concise with your product title. Maximum character count is 128 characters, but we recommend shorter titles under 60 characters to avoid truncation in  mobile experiences. Description is max 500 characters. Anything over 500 characters will be cut off. Do not send any HTML encoding in descriptions, as any HTML will display as plain text.

In the event that an item has multiple color choices, we recommend that the color in the product title match the primary image for that product.

Product variants

If the product variants do not have different image variations (image_link, additional_image_link) and landing page experience, we recommend you send one primary ” product as a single line in the data source instead of sending multiple variants that share the same image and landing page experience.

If product variants have different images and landing pages, place the variants within the data source with their appropriate image links and landing pages, and group them together using item_group_id.

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 128 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 500 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://   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
condition The condition of the product. Must be one of the following values: ‘new’, ‘used’, ‘refurbished’. new
used
refurbished
new required
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
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 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:// 

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:// Max 511 characters 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
identifier_exists Required when unique product identifiers (GTIN or MPN) do not exist. When the attribute is not specified, the default value will be TRUE. true
false
yes
no
true 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
UK

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.  

Best sellers

Summer promotion

optional
custom_label_1 Custom grouping of products.     optional
custom_label_2 Custom grouping of products.     optional
custom_label_3 Custom grouping of products.     optional
custom_label_4 Custom grouping of products.     optional

Optional shopping ad fields

Column name Description Syntax/supported values Example Requirement
adwords_redirect 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
Still need help?
Contact us