Documentation

Create a catalog in the Editor

Create and configure Unity IAP catalog listings using the IAP Catalog window.
Read time 6 minutesLast updated 4 days ago

IAP Catalog

The IAP Catalog is a Unity Editor window that provides a codeless, visual interface to define and manage your catalog.
Important
Starting in version 5.4.4, the IAP Catalog window is available only to projects that already have a local catalog, and catalog authoring has moved to the Remote Catalog. If your project has one, you can keep using the window, but the recommended best practice is to migrate your catalog.
The catalog is the required method for implementing Codeless IAP and provides a central location in the Unity Editor to configure listing attributes, pricing, and store-specific information.
Important
The IAP Catalog defines listings, but does not manage inventory. You must implement the logic to deliver purchased content to the user after a successful transaction.
Note
For a Direct-to-Consumer (D2C) payment provider, you need to create a remote catalog.
Note
You can also use a catalog created in the Editor with coded IAP. Refer to Fetch products from a catalog created in the Editor for more information.

Prerequisites

Before you begin, complete the steps in the Get started guide.

Add listings to your catalog

Important
These steps use an Editor menu item that version 5.4.4 makes available only to projects that already have a local catalog. If your project has one, you can still follow these steps. Otherwise, define your catalog in the Remote Catalog.
To add listings to your catalog, use the IAP Catalog:
  1. In the Unity Editor, select Services > In-App Purchasing > IAP Catalog.
  2. Select Add Product to create a new listing.
  3. Enter a unique Product ID, select the appropriate Product type (Consumable, Non-Consumable, or Subscription), and provide a display name.
  4. Set attributes such as price, payout, and store-specific IDs. For information on each setting, refer to the IAP Catalog window reference.
Repeat these steps for each listing you want to offer.

Migrate your catalog to the Remote Catalog

Starting in version 5.4.4, you can convert a local 
IAPProductCatalog.json
file into a catalog CSV file that you deploy to the Remote Catalog. Unity IAP doesn't modify your local file, which continues to work as it did before.
You can keep your catalog in the Editor, but the recommended best practice is to migrate it. A Remote Catalog lets you change your products and your prices without your players having to update your application. It also lets you configure your product information once, instead of once for each payment provider.
Important
Deploying the migrated file doesn't change what your application serves. Codeless IAP and 
ProductCatalog.LoadDefaultCatalog
both read the local catalog, so your players keep getting the products in that file. To serve the Remote Catalog, fetch it with 
RemoteCatalogProvider
 in your scripts and release a new build.
The migration options appear only when your project has a local catalog that holds at least one listing with an ID.
The Remote Catalog has no equivalent for payouts, screenshot paths, or pricing templates, so the migration doesn't carry them over. Your local file still holds these values, and Codeless IAP keeps reading them, but they aren't available to an application that serves the Remote Catalog. For the full list, refer to Fields that the migration converts.
Important
A local catalog records no currency, because Google Play stores a plain price value and the Apple App Store stores a price tier. Unity IAP therefore sets 
CurrencyCode
to 
USD
for every price that it converts. Always check the currency in the generated file before you deploy it.
To migrate your catalog from the Project Settings window, follow these steps:
  1. In the Unity Editor, select Project Settings > Services > In-App Purchasing.
  2. Under Legacy Catalog, select Migrate to Remote Catalog.
  3. In the Project window, review the 
    MigratedCatalog.catalog.csv
    file that Unity IAP highlights, including the 
    CurrencyCode
    column.
To migrate from the IAP Catalog window instead, select Migrate to Remote Catalog near the top of the window. Unity IAP saves any pending changes to your local catalog before it converts them.
Unity IAP writes the CSV file to the folder that's selected in the Project window. If that folder already holds a file with the same name, Unity IAP appends a number to the new file name.
Every catalog item must include a pricing row in 
USD
. Otherwise, Unity IAP won’t deploy the item. To price an item in another currency, follow these steps:
  1. Correct the amount in the item’s USD row. Don’t change its 
    CurrencyCode
    .
  2. Duplicate the row.
  3. In the new row, enter the appropriate 
    CurrencyCode
    and 
    Amount
    . Use the same 
    CatalogListingId
    for both rows.
After you review the file, deploy it from the Deployment window in the same way as any other catalog CSV file. For the columns that the file uses, refer to Author catalog items in a CSV file.

Fields that the migration converts

The following table describes what happens to each part of a local catalog listing.

Local catalog field

Result

IDBecomes the 
Sku
, and the catalog listing ID becomes 
catalog/
followed by that value.
TypeBecomes the 
ProductType
.
Title and Description, including translationsBecome one CSV row per locale.
Price in the Google configurationBecomes the 
Amount
. The 
CurrencyCode
is always 
USD
.
AppleAppStore, GooglePlay, and MacAppStore ID overridesBecome store ID overrides.
PayoutsNot converted.
Screenshot pathNot converted.
Pricing TemplateNot converted.
Price Tier in the Apple configurationNot converted. A listing that only has an Apple price tier converts with no price, so set a price for it in the generated file.
ID overrides for any other storeNot converted. The Remote Catalog has no equivalent for stores such as WinRT.

Console messages during migration

Unity IAP reports the result of a migration in the Console window. The following table describes each message and how to respond to it.

Message

Meaning

Action

Migrated the legacy catalog to <path>. Review it, then deploy it from the Deployment Window.
The migration succeeded.Review the file at that path, then deploy it.
No products found in the legacy catalog, so nothing was migrated.
Your local catalog holds no listings, or none of them have an ID.Add at least one listing with an ID, then migrate again.
The migrated catalog has items the Remote Catalog will reject on deploy. Fix them in the generated file: ...
A local catalog allows values that the Remote Catalog rejects. For example, a Google Play title can hold up to 55 characters in a local catalog, but the Remote Catalog allows 50.Correct the listings that the message names, then deploy.
These legacy catalog fields have no Remote Catalog equivalent and were not migrated. The original file still holds them: ...
The message names each field that the migration skipped, each listing that has only an Apple price tier, and the assumed currency if at least one listing has a Google price.Set a price for each listing that has only an Apple price tier. The skipped fields need no action. Check the 
CurrencyCode
column too, because a catalog with no prices migrates as 
USD
with no message.

Additional resources