Docs

In-App Purchases

Generate revenue with in-app purchases (IAP) which allow users to buy digital goods and virtual currency within your application. There are two IAP methods that you can set up: TikTok Beans for one-time purchases, and subscriptions.

This guide explains the integration process for subscriptions, which are recurring charges for packages within your mini drama.

Prerequisites

Before setting up in-app ads for your mini game or mini drama, you must have completed the following:

Enabled in-app purchases for your mini game or mini drama
Configured silent login for your mini drama
Configured the payment webhook callback address on your app page

Make sure you also meet the following technical preconditions:

Your app has completed integration with the TikTok Minis SDK
SDK initialization has been correctly completed in HTML

<head>
  <script src="https://connect.tiktok-minis.com/drama/sdk.js"></script>
  <script>
    TTMinis.init({
      clientKey: 'your_client_key',
    });
  </script>
</head>

The current project can be successfully launched locally and meets the following basic requirements:

The project root directory exists package.json
package.json must provide at least dev or start startup script
The project root directory contains minis.config.json

Your backend already has the following capabilities:

Complete silent login to replace token
Create a pre-payment order via open_id and access_token
Receive and verify the payment success webhook
Perform idempotent shipment based on the order

IAP setup for subscriptions

Configuring subscriptions for your mini drama requires you to use methods from both TikTok Minis SDK and TikTok Minis Server API. You can complete two methods:

Create a new subscription
Renew an existing subscription

Create a new subscription

To create a new subscription, you must first query whether or not the user has a subscription. Subsequently, your platform will display a subscription tier list and then create a subscription order according to the package the user chooses. Optionally, you can provide coupons to first-time subscribers.

Note: Each user may have no more than one active subscription within your app.

Step 1: Query user's subscription status

Call https://open.tiktokapis.com/v2/minis/subscription/get_active_list/ to retrieve the user's subscription status.

If the return value is empty, then the user has no valid subscription. Proceed to step two.
If the return value is not empty, this indicates that the user has a subscription.

If a user has a subscription, their status may be active, cancel, or onhold. Two key fields that determine the subscription's state:

is_subscription_rights_valid: Whether the user currently has active subscription benefits.
is_renewal_normal: Whether auto-renewal is active and functioning normally.

Status	Has benefits?	Auto-renewing?	Allowed actions	Description
Active	Yes ✅	Yes ✅	Change	The user is actively subscribed and paying. If needed, you can offer them options to upgrade to a longer billing period.
Cancel	Yes ✅	No ❌	Reactivate	The user canceled, but their paid time hasn't run out yet. They keep their benefits until the expiration date. During this time, they can only reactivate their subscription.
OnHold	No ❌	No ❌	None	The user's automatic payment failed. This status lasts 1-2 months. During this time, they must update their payment info in the Apple or Google Store. They cannot create a new subscription while on hold.

When a subscription payment fails, TikTok sends a minis.subscription.onhold webhook. This onhold status lasts 1-2 months.

During this time, the following rules apply:

User action required: Users cannot create a new subscription. Use a toast notification to remind them to resolve their current subscription (either renew or cancel) in the Apple or Google Store.
Active benefits: An onhold status does not mean the user's benefits have expired, because auto-renewals are attempted one day before expiration. To verify if benefits are still active, check the expiration date or the is_subscription_rights_valid field.
Resolution webhooks: Once the status is resolved, TikTok will send minis.subscription.renew (if successfully renewed) or minis.subscription.expire (if the subscription becomes entirely inactive).

Step 2: Show surface coupon

To offer introductory discounts to first-time subscribers, use showSurfaceCoupon to display the promotion to the user before they view your products.

Step 3: Show tier list

Display your product page with the available subscription tier list on your frontend. Your promotion from the surface coupon will be displayed as a banner at the top of the screen.

Let the user choose their target tier then subsequently create the subscription order.

Note: When the user leaves your product page, ensure you close the promotional banner by calling hideRibbon.

Step 4: Create subscription order

To create a subscription for a user:

Your server calls the subscription creation API to generate a trade_order_id.
Your client calls TTMinis.createSubscription with the trade_order_id to open the payment screen.
After the user completes payment, TikTok sends a minis.subscription.create webhook to your server to confirm activation.

Reactivate subscription

Note: A subscription can be reactivated ONLY when is_renew_normal=false.

Step 1: Query user's subscription status

Call https://open.tiktokapis.com/v2/minis/subscription/get_active_list/ to retrieve the user's subscription status.

If a user has a subscription, their status may be active, cancel, or onhold. Two key fields that determine the subscription's state:

is_subscription_rights_valid: Whether the user currently has active subscription benefits.
is_renewal_normal: Whether auto-renewal is active and functioning normally. Subscriptions can only be reactivated if this value is false.

Status	Has benefits?	Auto-renewing?	Allowed actions	Description
Active	Yes ✅	Yes ✅	Change	The user is actively subscribed and paying. If needed, you can offer them options to upgrade to a longer billing period.
Cancel	Yes ✅	No ❌	Reactivate	The user canceled, but their paid time hasn't run out yet. They keep their benefits until the expiration date. During this time, they can only reactivate their subscription.
OnHold	No ❌	No ❌	None	The user's automatic payment failed. This status lasts 1-2 months. During this time, they must update their payment info in the Apple or Google Store. They cannot create a new subscription while on hold.

When a subscription payment fails, TikTok sends a minis.subscription.onhold webhook. This onhold status lasts 1-2 months.

During this time, the following rules apply:

User action required: Users cannot create a new subscription. Use a toast notification to remind them to resolve their current subscription (either renew or cancel) in the Apple or Google Store.
Active benefits: An onhold status does not mean the user's benefits have expired, because auto-renewals are attempted one day before expiration. To verify if benefits are still active, check the expiration date or the is_subscription_rights_valid field.
Resolution webhooks: Once the status is resolved, TikTok will send minis.subscription.renew (if successfully renewed) or minis.subscription.expire (if the subscription becomes entirely inactive).

Step 2: Allow user to reactivate subscription

A user can reactivate their subscription only if they don't already have an active subscription.

Step 3: Reactivate subscription

To create a subscription for a user:

Your server calls the subscription reactivation API to generate a trade_order_id.
Your client calls TTMinis.reactivateSubscription with the trade_order_id to open the payment screen.
After the user completes payment, TikTok sends a minis.subscription.reactivate webhook to your server to confirm activation.

Test subscriptions with sandbox

Before going live, test your subscription integration using the provided sandbox tier IDs. The following concepts apply when testing integrations with sandbox tier IDs:

No real payments: Sandbox subscriptions will not trigger the payment panel. We assure you that you will receive notifications and webhooks just like in the production environment
Automatic renewals: Subscriptions renew every 5 minutes (12 times total). After 12 renewals or cancellation, an expiry event will be triggered.
Same webhooks: You'll receive the same notifications as production.
Blocked reactivations: You may not reactivate within 2 minutes of renewal. In production, this period is typically one day.
In the sandbox, these actions can be executed: create, change, cancel, reactivate, onhold, onhold recover.

Sandbox tier IDs

When calling subscription APIs, use the following tier IDs in your request body parameters. This will automatically trigger sandbox mode:

Tier ID	Description
`sandbox_499_1M`	$4.99 per month
`sandbox_1347_3M`	$13.47 per quarter
`sandbox_699_1M`	$6.99 per month
`sandbox_1887_3M`	$18.87 per quarter

For production, use the tier IDs generated from the subscription SKUs you configured on the organization level.

Debugging recommendations

After configuring IAPs, we recommend conducting joint debugging in the following order:

First, ensure that the silent login link is available
Confirm that the backend can create trade_order_id
The front end successfully launched TTMinis.pay()
Confirm that the backend has received the webhook
Confirm that the backend shipment was successful
Confirm that the frontend polling status update was successful

If you need to speed up joint debugging, you can enable payment Mock and identify is_sandbox in the backend.

Frequently Asked Questions

Must explicit authorization be performed first before accessing payment?

No, it's not necessary. The core of the payment process relies on user identity, which is obtained through silent login:

open_id
access_token

Users are not required to authorize their avatar and nickname first.

Frontend callback succeeded. Can we ship the product immediately?

No, it cannot. The only reliable basis should be:

The developer backend receives a payment success webhook
Complete signature verification and idempotence check

Can the same trade_order_id be paid repeatedly?

No, it cannot. If the payment for this order fails or the user cancels, a new trade_order_id should be recreated when initiating payment again.

How to prevent duplicate shipments

The developer backend must be based on:

trade_order_idor business order_id

Perform an idempotence check.

Why does the payment panel display "An error occurred, please try again later"?

Common causes include:

Payment is not supported in the current region
Store account location does not match
IP/device environment does not meet the requirements
The platform's payment capability has not yet been truly activated

Was this document helpful?