X Shopping Manager
Product specifications guide
X Shopping Manager is your single, central one-stop-shop for merchant onboarding and product catalog management tools. Use this guide below to help you properly structure and upload your CSV product catalog file into X Shopping Manager. You can manually upload up to a 100 MB file to X Shopping Manager or use a Scheduled Feed to automatically send a file that can be up to 8 GB.
These products will be used to create your product sets and set up your shopping presence, including Shop Spotlight, X Shops, Live Shopping, and Dynamic Product Ads.
Jump to: Required specs || Optional specs
Required specs
Please ensure that all of the fields below are included in your CSV file when uploading to X Shopping Manager.
Product attribute and type
Description
Product attribute and type
id
Type: string
Description
Max character limit: 100
Unique ID for the item. Use the SKU if possible. If there are multiple instances of the same ID, all instances will be ignored.
Example value:
- TWSHOES-22
Product attribute and type
title
Type: string
Description
Max character limit: 150
The name of the product. Should be the same name as the product from the landing product page given through link or mobile_link attributes.
Example value:
- X Blue Sneakers
Product attribute and type
description
Type: string
Description
Max character limit: 5,000 (open-text)
The description of the product. This field does not support HTML and must be in plain text.
Example value:
- The first of its kind at X, the X Blue Sneaker is a sleek, fashionable athletic sneaker. Made of breathable soft cotton. Comes in the blue color, matching X’s brand.
Product attribute and type
availability
Type: string
Description
Current availability of your item. Select one of the possible values from the list below.
Possible values:
- in stock
- available for order
- preorder
- out of stock
- discontinued
Product attribute and type
condition
Type: string
Description
Condition of the item being sold. Select one of the possible values from the list below.
Possible values:
- new
- used
- refurbished
Product attribute and type
price
Type: string
Description
Price of the item. Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency. Use a period (".") as the decimal point.
Example values:
- 99.99 USD
- 20.00 CAD
Product attribute and type
link
Type: string
Description
URL of the product page specific to the product where people can buy the item. If a user is on a mobile device, and a mobile_link is included, the viewing user will be sent to the URL provided via the mobile_link attribute.
We will validate the URL according to RFCs. Specifically it must include “https” or “http”.
Example value:
- https://www.x.com/medium_tshirt
Product attribute and type
image_link
Type: string
Description
URL for the primary image of your item. If you change the image later, the new image must use a different URL or the image will not update.
Image specifications:
- All images must be in JPG, GIF, WEBP, or PNG format.
- We highly recommend product images are in square (1:1) format.
- The minimum image size is 500 x 500 px.
- Image file size limit: 5 MB.
Example value:
- https://t.co/demin_jeans_452.jpg
Product attribute and type
brand, gtin, and/or mpn
Type: string
Description
Only one (1) of brand, gtin, and/or mpn attributes are required, however all are encouraged to include if available.
Max character limit for all: 100
- Brand refers to the brand name of the item. Example value: X
- gtin refers to the Global Trade Item Number (unique universal product identifier) of the item. Enter the item's UPC, EAN, JAN, or ISBN. Example value: 012345678901
- mpn refers to the Manufacturer Part Number of the item. Example value: TW123456TTER
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Optional specs
All of the fields below are optional to include in your CSV file when uploading to X Shopping Manager, but in many cases are recommended to provide additional context to your products showcased on X.
Product attribute and type
Description
Product attribute and type
mobile_link
Type: string
Description
URL of a mobile optimized version of the product page specific to the product where people can buy the item. If a user is on a mobile device, the viewing user will be sent to the URL provided via the mobile_link attribute.
We will validate the URL according to RFCs. Specifically it must include “https” or “http”.
Example value:
- https://lite.x.com/twtr_blue
Product attribute and type
additional_image_link
Type: string
Description
To add more images of your item, use additional_image_link. URLs should be separated by commas. Follow the same specifications as mentioned in the image_link attribute. You can include up to 10 additional images.
Example value:
- https://t.co/jeans_1.jpg, https://t.co/jeans_2.jpg, https://t.co/demin_jeans_3.jpg
Product attribute and type
google_product_category
Type: string
Description
The category of the item, according to Google's product taxonomy. Use the category's taxonomy path or its category ID number. Note that in some cases, this category will be shown to X users.
Example values:
- Electronics > Video Game Consoles
- 1294
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Product attribute and type
product_type
Type: string
Description
The category the item belongs to, according to your business' custom product taxonomy, if you have one. You can also enter a Google product category (google_product_category). Subcategories must be sent separated by " > ". The > must be wrapped by spaces. Note that in some cases, this category will be shown to X users.
Example value:
- Clothing > Men’s > Pants > Denim
Product attribute and type
inventory
Type: integer
Description
Must be >= 0
The quantity of this item that you have available to sell on X. If included, an item’s inventory value must be 1 or higher when its availability field is set to in stock for the item to be shown to users. Otherwise, this value could be greater than or equal to 0 when its availability field is set to available for order, or preorder for the item to be shown to users.
Example value:
- 10000
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Product attribute and type
sale_price
Type: string
Description
Must be >= 0
The discounted price of the item. Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency. Use a period (".") as the decimal point. The sale_price must be lower than the price. If there is no sales price, please leave this optional field blank instead of entering the same value as “price”.
Example values:
- 89.99 USD
- 15.00 CAD
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Product attribute and type
sale_price_effective_date
Type: one or two ISO-8601 timestamps
Description
Time range for the item’s sale period, including the date, time, and time zone when your sale starts and ends. If sale dates aren’t entered, any items with a sale_price will remain on sale until you remove their sale price.
It is possible to provide just a start date without an end date, in which case the sale price will remain on sale from the start date until the sale price is removed.
Format: YYYY-MM-DDT23:59+00:00Z/YYYY-MM-DDT23:59+00:00Z
Start date must be before end date.
Detailed instructions:
- Type the start date as YYYY-MM-DD.
- Type "T" after the start date.
- Type the start time in a 24-hour format (00:00 to 23:59), followed by the UTC time zone (-12:00 to +14:00), and a "Z" at the end.
- Type a "/" and then repeat the same format for the item’s sale end date and time.
The example below uses the PST time zone (-08:00).
Example value:
- 2020-06-28T09:00-08:00Z/2020-07-28T23:59-08:00Z
Product attribute and type
item_group_id
Type: string
Description
Max character limit: 100
Use the item_group_id attribute to group product variants together. Variants are a group of similar items that only differ from one another by product details like size, color, age_group, and gender. This field is required if your product has variants.
Example value:
- xshoes1234_12
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Product attribute and type
gender
Type: string
Description
Determines gender for item sizing. Select one of the possible values from the list below.
Possible values:
- female
- male
- unisex
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Product attribute and type
color
Type: string
Description
Max character limit: 100
The primary color of the product. Use one or more words to describe the color. Don’t use the hex code.
Example values:
- blue
- forest green
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Product attribute and type
size
Type: string
Description
Max character limit: 100
Size of the item written as a word, abbreviation, or number.
Example values:
- medium
- M
- 6
Product attribute and type
age_group
Type: string
Description
The associated age group of the item. Select one of the possible values from the list below.
Possible values:
- adult
- all ages
- teen
- kids
- toddler
- infant
- newborn
Note: This field is highly recommended when uploading product catalogs for Dynamic Product Ads campaigns.
Product attribute and type
custom_label
Type: string
Description
Up to five custom fields (custom_label_0, custom_label_1, custom_label_2, custom_label_3, custom_label_4) for any additional information you want to filter items by when you create filter-based product sets.
For example, you could use a custom label field to indicate all products that are part of a summer sale, and then filter those products into a product set. These fields support any string value.
Example:
- Holiday Sale