Documentation

In-App Purchasing

Client API

SDK API

In-App Purchasing

Catalog schema

Find the fields you can use to define listings in your catalog, including localized content, pricing, and webshop display metadata.
Read time 2 minutesLast updated 13 hours ago
The catalog schema defines the structure of a catalog listing in your IAP catalog. Each listing describes its core identity, localized display content, pricing, and optional store metadata. Not all fields apply to every listing. If you sell through a webshop, you can extend a listing with additional display options. Refer to the webshop extension fields.

Listing schema

Refer to the following fields that are available to you when you create a catalog listing:

catalogListingId

string
required
A unique identifier for this listing, distinct from the 
uSKU
. Allows unique listings for the same in-game item.

uSKU

string
required
The product's unique identifier (SKU). 1–141 characters, limited to letters, numbers, and the 
.
, 
_
, and 
-
characters.

type

string
required
Product type. One of 
Consumable
, 
NonConsumable
, or 
Subscription
.

imageUrl

string
Absolute HTTPS URL of the listing's standard image asset.

productDetails

object[]
required
Localized content for the listing, with one entry per supported language. Must contain at least one entry.

language

string
required
BCP 47 language tag for this entry (e.g. 
en-US
, 
es-ES
).

title

string
required
Localized listing title. Up to 50 characters.

subtitle

string
Localized listing subtitle. Up to 50 characters.

description

string
Localized listing description shown to the player. Up to 250 characters.

badge

object
Promotional badge displayed on the listing.

text

string
required
Badge label text (e.g. 
+125
, 
25% OFF
).

imageUrl

string
Absolute HTTPS URL of the badge image asset.

pricing

object[]
required
Pricing entries for each supported currency. Must contain at least one entry, and must include an entry in 
USD
.

currencyCode

string
required
ISO 4217 currency code (for example, 
USD
, 
EUR
).

amount

integer
required
The amount charged for the product, in micros (1,000,000 micros = 1 unit of currency). For example, 
9990000
is 9.99. Must be greater than 0.

webshopPrice

integer
The price shown on the webshop, in micros. Set this to give the product a web-specific price.

storeIdOverrides

object[]
Store-specific product IDs that override the 
uSKU
for native stores.

store

string
required
The store this override applies to. One of 
apple
or 
google
.

value

string
required
The store-specific product identifier.

Example catalog

The following catalog listing carries both base catalog fields and webshop extension fields. Prices are expressed in micros, where 1,000,000 is one unit of the currency. 
[  {    "catalogListingId": "gems_medium_default",    "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  }]

Additional resources