Skip to main content

​
Product Data Format

ACP’s product data model has two layers: Product (the item) and Variant (specific SKUs). Each Product must contain at least one Variant.

​
2.1 Feed Header (Data Source Identifier)

Every data file or API call must include a Feed Header identifying the data source:
FieldTypeRequiredDescription
feed_idstringYesUnique identifier for the data feed
account_idstringYesMerchant account ID
target_merchantstringYesTarget merchant identifier
target_countrystringYesTarget country (ISO 3166-1 alpha-2, e.g., “US”, “GB”)

​
2.2 Product Object

FieldTypeRequiredDescription
idstringYesUnique product identifier — must remain stable throughout its lifecycle
titlestringNoProduct title
descriptionDescriptionNoProduct description (supports multiple formats)
urlURI stringNoProduct page URL
mediaMedia[]NoProduct images/videos
variantsVariant[]YesAt least 1 variant
ID stability: Product IDs must remain unchanged throughout their entire lifecycle. Changing an ID causes ChatGPT to lose all historical data and recommendation records for that product.

​
2.3 Variant Object

Each Variant represents a specific configuration of a product (e.g., a color/size combination):
FieldTypeRequiredDescription
idstringYesUnique variant identifier, must be stable
titlestringYesVariant title
descriptionDescriptionNoVariant-specific description
urlURI stringNoVariant-specific page URL
barcodesBarcode[]NoBarcodes (GTIN, etc.)
pricePriceNoCurrent selling price
list_pricePriceNoOriginal / strikethrough price
unit_priceUnitPriceNoUnit price (by weight/volume, etc.)
availabilityAvailabilityNoStock status
categoriesCategory[]NoProduct categories
conditionstring[]NoProduct condition: new or secondhand
variant_optionsVariantOption[]NoSpecification options (color, size, etc.)
mediaMedia[]NoVariant-specific images (first one is the primary image)
sellerSellerNoSeller information (for marketplace merchants)

​
2.4 Price Object

All prices use ISO 4217 minor currency units (cents): 
{
  "amount": 7999,
  "currency": "USD"
}
FieldTypeRequiredConstraint
amountintegerYesGreater than or equal to 0, in minor currency units
currencystringYesISO 4217 three-letter code (e.g., “USD”, “EUR”)
Note: $79.99 is represented as 7999 in ACP. Japanese yen and other zero-decimal currencies use the face value directly.

​
2.5 Description Object

Provide at least one format. Plain text is recommended:
FieldTypeDescription
plainstringPlain text format (recommended)
htmlstringHTML format
markdownstringMarkdown format

​
2.6 Availability Object

FieldTypeValues
availablebooleantrue/false
statusstringin_stock / backorder / preorder / out_of_stock / discontinued
Delisting a product: Set is_eligible_search=false or omit the product from the next full catalog snapshot.

​
2.7 Media Object

FieldTypeRequired
typestringYes (image or video)
urlURI stringYes
alt_textstringNo
widthintegerNo (pixels)
heightintegerNo (pixels)
The first image is the primary image: In the media array, the first entry with type: "image" will be used as the primary image displayed by ChatGPT.

​
2.8 Category Object

FieldTypeDescription
valuestringCategory name
taxonomystringClassification system: merchant / google_product_category / shopify
Supported classification systems:
  • merchant: Merchant-defined custom categories
  • google_product_category: Google Product Category standard
  • shopify: Shopify category standard

​
2.9 VariantOption Object

Used to describe user-facing specification dimensions of a variant: 
{
  "name": "Color",
  "value": "Black"
}
Common options: Color, Size, Material, Capacity, etc.

​
2.10 Seller Object (for Marketplace Merchants)

FieldTypeDescription
namestringSeller name
linksLink[]Seller-related links
The Link object type enum: privacy_policy / terms_of_service / refund_policy / shipping_policy / faq Use durable public URLs: Seller links must be stable, long-lived public URLs.

​
2.11 Barcode Object

{
  "type": "gtin",
  "value": "0123456789012"
}

​
2.12 Complete Product Example

{
  "id": "prod_running_shoe_001",
  "title": "Classic Running Shoe",
  "description": {
    "plain": "Lightweight running shoe designed for daily training and short-distance races"
  },
  "url": "https://store.example.com/products/running-shoe-001?utm_medium=feed",
  "media": [
    {
      "type": "image",
      "url": "https://store.example.com/images/shoe-main.jpg",
      "alt_text": "Classic Running Shoe front view"
    }
  ],
  "variants": [
    {
      "id": "var_shoe_001_black_10",
      "title": "Classic Running Shoe - Black Size 10",
      "price": {
        "amount": 7999,
        "currency": "USD"
      },
      "list_price": {
        "amount": 9999,
        "currency": "USD"
      },
      "availability": {
        "available": true,
        "status": "in_stock"
      },
      "variant_options": [
        { "name": "Color", "value": "Black" },
        { "name": "Size", "value": "10" }
      ],
      "categories": [
        { "value": "Running Shoes", "taxonomy": "google_product_category" },
        { "value": "Athletic/Running Shoes", "taxonomy": "merchant" }
      ],
      "barcodes": [
        { "type": "gtin", "value": "0123456789012" }
      ]
    }
  ]
}
Next chapter: File Upload Integration — SFTP push specifications, file format requirements, and sharding strategy