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 upload up to a 100 MB file at any time to X Shopping Manager. 

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 Twitter 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:

  1. Type the start date as YYYY-MM-DD.
  2. Type "T" after the start date.
  3. 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.
  4. 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

Ready to get started?