Documentation

In-App Purchasing

Client API

SDK API

In-App Purchasing

Troubleshooting webshops

Solve common issues with creating, theming, publishing, and integrating Unity Webshops.
Read time 7 minutesLast updated 11 hours ago
This page collects the most common issues administrators and game developers hit while working with Unity Webshops, grouped by symptom. Each entry names the most likely cause and the dashboard or code change that fixes it.

Creating webshops

Slug rejected as already in use

Cause

Slugs are unique within a studio. Another webshop in your organization already uses the slug.

Resolution

Pick a different slug, or change the slug of the existing webshop first if you intend to repurpose the URL. For the full slug rule, refer to Webshop limits reference.

Studio name rejected during create

Cause

Studio names are globally unique across Unity. Another organization has already claimed the name. The dialog shows the following inline error message: 
Studio name already taken. If you own this trademark, contact trademarks@unity3d.com to claim it.

Resolution

Pick a different name. There is no automatic transfer flow between organizations. If you hold a registered trademark for the taken name, email 
trademarks@unity3d.com
to request a release; the team reviews trademark claims and frees the name when appropriate. If you're trying to rename an existing studio you already own, do it from Organization settings rather than from the Create webshop dialog.

Studio field is disabled in the Create webshop dialog

Cause

Your organization already has at least one webshop, so the studio name is set and reused. The Create dialog only accepts a new studio name when no webshop exists yet in the organization.

Resolution

To rename the studio, close the Create dialog, navigate to Monetization > Settings > Organization, and edit the Studio name field. The rename runs the same uniqueness check and changes the URL of every webshop in your organization, so update external links accordingly.
Note
If you're using the legacy Unity Dashboard, open the Account menu and select Manage organization.

Cannot create a second webshop for the same project

Cause

Each Unity Cloud project can have exactly one webshop.

Resolution

Either edit the existing webshop or create a new Unity Cloud project for the second shop.

Publishing

Publish button is missing or disabled

Cause

You're editing a non-production environment. Only the production environment can publish; non-production environments are draft-only and show Save draft in place of Publish.

Resolution

Either switch the environment selector at the top of the Edit view to production and publish from there, or use Apply to production on the non-production environment's Customize theme section to copy the draft into production, then switch to production and publish. For the publish model, refer to Introduction to webshops.

Shop URL returns a not-found response

Cause

Either the webshop has never been published, the webshop was unpublished, the studio name in the URL is wrong, or the slug is wrong.

Resolution

Confirm the studio and slug match the Dashboard. Then check the publication status of the production environment. If the shop is unpublished, publish from the production environment. If you recently renamed the studio, the old URL is no longer valid — use the new URL shown in the Dashboard.

Live shop still shows old branding after publishing

Cause

The content delivery network has cached the previous version, or the Dashboard reported success before propagation completed.

Resolution

Wait a short period and retry. If the live shop still shows the old version after several minutes, confirm the publish action completed successfully in the Dashboard (the row in the Webshop list shows a recent publish timestamp under View logs), then retry.

Branding and media

Branding upload rejected

Cause

The upload exceeded a file size limit or was not in an accepted format.

Resolution

Re-export the asset within the limits in Webshop limits reference and retry. Source uploads can be PNG, JPEG, or WebP; the server converts to lossless WebP for delivery.

Hero banner looks cropped on the live shop

Cause

The uploaded source had a different aspect ratio than the rendered banner. The hero banner is scaled and cropped server-side to 1920 × 384 px, so anything wider or taller is cropped to fit.

Resolution

Re-upload at the rendered aspect ratio (32:10) or higher resolution with the same aspect ratio. Refer to Webshop limits reference.

Theming

AI theme generation failed

Cause

The Dashboard couldn't reach the app-store URL, the scrape returned no usable assets, or the generation step failed.

Resolution

Confirm the app-store URL is publicly accessible. Retry the generation — most transient failures resolve on the next attempt. If generation still fails, edit the theme manually in the Customize theme section. For the generation procedure, refer to Generate a webshop theme with AI.

Theme generated in a non-production environment isn't live

Cause

Non-production environments cannot publish on their own. A theme saved in a non-production environment lives only in that environment's draft.

Resolution

Select Apply to production in the Customize theme section to copy the theme into production's draft. Then switch the environment selector to production and select Publish.

Catalog and payments

Shop renders without product cards

Cause

The parent project's IAP catalog is empty or has no published products. The Preview pane also renders empty when Mock catalog is off and no real catalog is connected.

Resolution

In the IAP section of the Dashboard, confirm the project has at least one product in its catalog. Refer to Create a catalog in the Editor. If you only want to preview the theme without connecting a real catalog, turn on the Mock catalog toggle in the Catalog & payment provider section.

Mock catalog items appear in the player's shop

Cause

This is not possible — mock products only render in the Dashboard's Preview pane. If a player reports seeing them, they're looking at the Dashboard preview, not the public URL.

Resolution

Confirm the player is opening the public 
shop.unity.com/{studio}/game/{slug}
URL, not a Dev preview URL.

A test purchase in the Dev preview charged a real card

Cause

The Dev preview URL renders the draft against your real catalog and your real IAP payment provider. There is no sandbox boundary at the webshop layer — testing modes are controlled at the IAP payment provider.

Resolution

Use the payment provider's sandbox account or test card for end-to-end purchase testing. Refer to Catalog and payments in webshops for the preview-versus-test behavior, and refer to the relevant provider's documentation in Payment providers for the sandbox setup.

Product prices don't match the game

Cause

Currency or locale parameters weren't passed when opening the shop, so the shop fell back to the browser locale and default currency.

Resolution

Pass 
locale
and 
currency
as URL parameters when opening the shop from your game. Refer to Integrate a webshop into a Unity game.

Return to game button doesn't appear on the success dialog

Cause

One of the following preconditions wasn't met: the session was opened directly (not via a deep link from your game), the player is on desktop, or no return deep link is configured.

Resolution

Confirm the player opened the shop from a deep link in your game (not by typing the URL), and that they are on a mobile device. Then check that the Deeplink URL is set in the Dashboard's Catalog & payment provider section. For the full set of preconditions, refer to Deep links and the return flow.

Players from a shared link see a landing page instead of the shop

Cause

This is expected. The shop renders an unauthenticated landing page when a player arrives without auth context, which is the case for any URL opened directly in a browser rather than via a deep link from your game. The landing page shows a Connect to game button that uses your configured deep-link scheme to reverse-launch the game.

Resolution

No fix required if Connect to game works — the round-trip authenticates the player and lands them in the shop. If the button shows a message telling the player to launch the store from within the game, rather than launching the game, no return deep link is configured. Set the Deeplink URL in the Edit view's Catalog & payment provider section. For the full flow, refer to The unauthenticated landing page.

Connect to game opens the game but the shop still shows the landing page after re-entry

Cause

The game received the inbound 
{scheme}://
deep link but did not re-open the shop with auth parameters. Your 
Application.deepLinkActivated
handler likely either ignored the link (no 
status
parameter) or hit an error before calling 
OpenShop
.

Resolution

Confirm the handler dispatches on the absence of 
status
and calls your 
OpenShop
method with the current 
sessionToken
, 
projectId
, and 
environment
parameters. Refer to the dispatch logic in Integrate a webshop into a Unity game.

Player taps Return to game but the game doesn't reopen

Cause

The deep-link scheme isn't registered on the device, or the Dashboard's configured scheme doesn't match the scheme the game listens for.

Resolution

Confirm the deep-link scheme is declared in your Android manifest or iOS 
Info.plist
and that the Dashboard's scheme uses the same string. Re-install the game after changing the manifest so the operating system picks up the new scheme. For the integration code, refer to Integrate a webshop into a Unity game.

Game opens but doesn't see the purchase result

Cause

The 
Application.deepLinkActivated
handler isn't parsing the 
status
query parameter, or the handler was subscribed too late for a cold-start launch.

Resolution

Confirm your handler reads the 
status
query parameter (the only value the shop sends is 
success
) and, on startup, also processes 
Application.absoluteURL
to handle the cold-start case. Refer to Integrate a webshop into a Unity game.

Cause

Custom URL scheme deep links are delivered by the operating system to an installed app. The Unity Editor isn't a registered handler, so a link opened from the browser never reaches Play mode. WebGL builds don't use a custom scheme either.

Resolution

Test the return flow against a built player: a device build (iOS or Android) or a standalone build with the scheme registered in Player > Other Settings > Supported URL schemes. Refer to Handle inbound deep links.

Studio name disappeared after deleting a webshop

Cause

Deleting the last webshop in an organization releases the studio name back to the global pool. The next time you try to create a webshop in that organization, the Create dialog treats it as a fresh studio claim and either accepts your previous name (if it's still available) or rejects it as taken.

Resolution

If the name is still available, claim it back from the Create webshop dialog. If another organization has already claimed it, pick a different name. Going forward, keep at least one webshop in the organization (unpublished is fine) to hold the studio name. For the broader studio model, refer to Introduction to webshops; for the row-action menu, refer to the Webshop list actions reference.