Documentation

In-App Purchasing

Client API

SDK API

In-App Purchasing

Webshop catalog schema reference

Find the catalog fields you can use to control how your products appear in a webshop.
Read time 3 minutesLast updated 11 hours 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
stringYesThe product's unique identifier (SKU).
type
stringYesThe product type: 
Consumable
, 
NonConsumable
, or 
Subscription
.
imageUrl
stringNoURL of the product image shown on the product card.
productDetails
arrayYesLocalized display details, one entry per language. Refer to Localized product details.
pricing
arrayYesPer-currency prices. Refer to Pricing.
storeIdOverrides
arrayNoAlternate 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
stringYesThe language this entry applies to.
title
stringYesThe product's display name.
description
stringYesThe player-facing product description.
subtitle
stringNoAn optional secondary line shown with the title.
badge
objectNoA 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
stringYesThe ISO 4217 currency code, for example 
USD
or 
GBP
.
amount
integerYesThe amount charged for the product.
webshopPrice
integerNoThe 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.

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 stringsNoThe category IDs the product belongs to (up to 16, unique). Each must match a category you've defined for your webshop.
hdImages
arrayNoHigh-resolution images for the product detail dialog (up to 8). Each entry has a 
url
(required) and an optional 
altText
.
promotion
objectNoA 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
integerNoThe 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}