Webshop catalog schema reference

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

Read time 3 minutes

Last updated 22 days ago

A webshop renders the products in your project's In-App Purchasing (IAP) 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; to author products, refer to Create a catalog in the Editor.

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.
`pricing`	array	Yes	Per-currency prices. Refer to 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,

is 9.99. Set prices through your catalog tooling rather than by hand — refer to Create a catalog in the Editor.

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:


{  "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}

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

In-App Purchasing

IAP Client API

IAP SDK API

Webshop Admin API

Webshop Client API

In-App Purchasing

Webshop catalog schema reference

Product fields

Field

Type

Required

Description

Localized product details

Field

Type

Required

Description

Pricing

Field

Type

Required

Description

Webshop extension fields

Field

Type

Required

Description

Example