Publish Subscription Plans and Store Items

This guide explains how to partner with the Oncade team to provision subscription plans, confirm the payout wallet that will receive renewals, and expose those plans in the store item editor. It also covers how to test the full subscriber journey once your plan is enabled.

Prerequisites

• An Oncade developer account with access to the business you are configuring.
• Business Settings
• Clarity on the subscription you want to offer (name, pricing, and the payout wallet it should use).

Request a subscription plan

1. Gather the required plan details listed below and confirm your business payout wallet is ready. Sharing the exact values upfront speeds up provisioning.
2. Reach out to your Oncade partner contact (or the support channel you normally use) with the plan request. Include the data points in a short summary or JSON snippet like the example below.
3. The team will enable the plan and confirm once it is available in the item editor.

{
  "planName": "Founders Pass",
  "priceUsdCents": 1500,
}

Oncade will generate the internal plan code for you, so there is no need to include one in the request.

Confirm the plan in the item editor

1. Once Oncade confirms the plan is live, open /store/manage/items/[id]/edit (or create a new item) in the workspace where you plan to sell it.
2. Switch the Type selector to Subscription. The Subscription Plan dropdown lists every plan the team enabled for your business.
3. If the plan does not appear, refresh the page to ensure you are in the correct environment and then reply to the Oncade team so they can double-check the configuration.

Attach the plan to a store item

1. Select the plan from the Subscription Plan dropdown.
2. Review the auto-filled price and payout wallet. These values come directly from the plan and cannot be edited on the item.
3. Complete the remaining item metadata (name, description, media) and save.
4. Publish the item when you are ready to start accepting subscribers.

PUT /api/store/items/[id] — Disabling subscription VC top-up

When updating a store item via PUT /api/store/items/[id], subscription VC top-up is only cleared whenboth grant fields are explicitly cleared together. This avoids inconsistent states (e.g. currency without amount or amount without currency).

• To disable subscription VC top-up, send both: grantVirtualCurrencyId as '' or null, and grantAmount as null.
• Accepted clear values: grantVirtualCurrencyId: '' or null; grantAmount: null.
• Partial clears are ignored: If only one of the two fields is sent (e.g. grantVirtualCurrencyId: '' but grantAmount omitted), the request is treated as a normal update and the other field is left unchanged. Sending only one clear value is not enough to disable top-up.

The devportal item editor sends both fields when disabling top-up. API consumers (scripts, integrations) must send both to clear the grant.

Test the subscription flow end-to-end

1. Use the View in Store button on the item detail page to open the storefront listing in a new tab.
2. Sign in as a test user, click Subscribe, and complete the checkout flow (Base Sepolia in the test environment). Confirm the confirmation screen shows the correct plan name and price.
3. Return to the item editor and open the Subscribers tab to verify the test user now appears with the expected plan details and start date.
4. If you need to reset the scenario, contact the Oncade team to cancel the subscription before running another test purchase.

Subscription webhook events

Oncade fires webhook events throughout the subscription lifecycle so your game server can respond to subscription changes in real time. Configure your webhook endpoint in Business Settings to receive these events.

See the Webhooks guide for full payload examples and integration details.