# Webshop catalog schema reference

> Find the catalog fields you can use to control how your products appear in a webshop.

A webshop renders the products in your project's [In-App Purchasing (IAP)](/iap.md) catalog. Each product is a standard IAP catalog item that you can extend with webshop-specific fields — categories, high-resolution images, a promotion treatment, a display order, and a per-product badge — that control how the product appears in the shop.

This reference lists the fields the webshop reads for each product: the base catalog fields that every IAP product has, and the webshop extension fields. The webshop extension fields apply only to products you include in your webshop catalog. For information about where the catalog comes from and how product display works, refer to [Catalog and payments in webshops](./catalog-and-payments.md); to author products, refer to [Create a catalog in the Editor](/iap/create-catalog-in-editor.md).

## Product fields

These are the base fields of every catalog product.

| Field              | Type   | Required | Description                                                                                                          |
| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `uSKU`             | string | Yes      | The product's unique identifier (SKU).                                                                               |
| `type`             | string | Yes      | The product type: `Consumable`, `NonConsumable`, or `Subscription`.                                                  |
| `imageUrl`         | string | No       | URL of the product image shown on the product card.                                                                  |
| `productDetails`   | array  | Yes      | Localized display details, one entry per language. Refer to [Localized product details](#localized-product-details). |
| `pricing`          | array  | Yes      | Per-currency prices. Refer to [Pricing](#pricing).                                                                   |
| `storeIdOverrides` | array  | No       | Alternate store-specific product IDs. Each entry has a `store` (`apple` or `google`) and a `value`.                  |

## Localized product details

Each entry in `productDetails` describes the product in one language.

| Field         | Type   | Required | Description                                                                                                                                                                                                 |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `language`    | string | Yes      | The language this entry applies to.                                                                                                                                                                         |
| `title`       | string | Yes      | The product's display name.                                                                                                                                                                                 |
| `description` | string | Yes      | The player-facing product description.                                                                                                                                                                      |
| `subtitle`    | string | No       | An optional secondary line shown with the title.                                                                                                                                                            |
| `badge`       | object | No       | A chip shown on the product card. Contains `text` (required, up to 32 characters) and an optional `imageUrl` for an icon shown beside the text. Any product can carry a badge, whether or not it's on sale. |

## Pricing

Each entry in `pricing` sets the price in one currency. The array must include at least one entry in `USD`.

| Field          | Type    | Required | Description                                                                        |
| -------------- | ------- | -------- | ---------------------------------------------------------------------------------- |
| `currencyCode` | string  | Yes      | The ISO 4217 currency code, for example `USD` or `GBP`.                            |
| `amount`       | integer | Yes      | The amount charged for the product.                                                |
| `webshopPrice` | integer | No       | The price shown on the webshop. Set this to give the product a web-specific price. |

Amounts are integers in micros, where 1,000,000 is one unit of the currency. For example, `9990000` is 9.99. Set prices through your catalog tooling rather than by hand — refer to [Create a catalog in the Editor](/iap/create-catalog-in-editor.md).

## Webshop extension fields

These fields extend a base catalog product with webshop-specific display options. They take effect only for products in your webshop catalog.

| Field        | Type             | Required | Description                                                                                                                                                                       |
| ------------ | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `categories` | array of strings | No       | The category IDs the product belongs to (up to 16, unique). Each must match a category you've defined for your webshop.                                                           |
| `hdImages`   | array            | No       | High-resolution images for the product detail dialog (up to 8). Each entry has a `url` (required) and an optional `altText`.                                                      |
| `promotion`  | object           | No       | A promotion treatment for the card. `type` is `Sale`, `Bonus`, or `Limited`. The optional `startsAt` and `endsAt` fields (RFC 3339 date-times) schedule when the treatment shows. |
| `sortIndex`  | integer          | No       | The product's display order across the shop. Lower values appear first.                                                                                                           |

## Example

The following product carries both base catalog fields and webshop extension fields:

```json
{
  "uSKU": "com.example.gems.medium",
  "type": "Consumable",
  "imageUrl": "https://cdn.example.com/gems-medium.png",
  "productDetails": [
    {
      "language": "en",
      "title": "Medium Gem Pack",
      "description": "A handy stash of gems to spend in game.",
      "subtitle": "500 gems",
      "badge": { "text": "Best value", "imageUrl": "https://cdn.example.com/gem-icon.png" }
    }
  ],
  "pricing": [
    { "currencyCode": "USD", "amount": 9990000, "webshopPrice": 7990000 }
  ],
  "categories": ["gems"],
  "hdImages": [
    { "url": "https://cdn.example.com/gems-medium-hd.png", "altText": "A pile of gems" }
  ],
  "promotion": { "type": "Sale", "endsAt": "2026-07-01T00:00:00Z" },
  "sortIndex": 10
}
```