Value-Added Service SolutionMonetization

This topic explains how to implement sales and fulfillment for value-added services in an OEM app: who it is suitable for, what the platform provides, how write-off settlement works, and how to integrate templates and APIs.

For OEM app integration with virtual services, this topic provides a complete configuration path from commercial contract signing, OEM-owned mall activation, quota procurement, subscription product configuration in the mall, channel distribution, and consumer-side integration.

#Applicable scenarios

In smart miniapp and similar scenarios, consider this solution if you need to:

• Offer paid capabilities or content such as subscriptions or unlocks, with a relatively complete purchase and fulfillment process.
• Sell value-added services in an OEM app (using "NetEase Cloud Music" as the example below), collect payments through your own channels, purchase quotas from Tuya, and fulfill services by write-off.

You can use the platform-provided value-added service solution to reduce self-development costs.

#What the platform provides

The platform covers the full loop of service creation -> user purchase -> fulfillment (activation / usage). You mainly focus on product configuration, payment / settlement model, and open API integration.

#Write-off settlement model

Product configuration, contract signing, and billing details are subject to Tuya value-added service and commercial / delivery documents. Align with your business contact before launch.

#Integration flow and configuration

Using "NetEase Cloud Music" as an example, OEM scenarios usually involve two layers of capabilities:

1. Device-side playback authorization: Enable the advanced feature "AI Playback of NetEase Cloud Music" for the product, and include the authorization when purchasing deliverables. For details, see the agent Music Story Skill.
2. Consumer-side value-added service sales and write-off: Configure subscription / trial products in the OEM mall. After users pay in the OEM app, fulfill the service credential and write off quotas with Tuya.

The following sections describe the complete chain in configuration order. Make sure the service and quota are ready before channel distribution, otherwise the service might not be found during fulfillment.

#Service code reference

Using "NetEase Cloud Music" write-off integration as an example, use the following codes when configuring mall products, associating product services, and obtaining products and service credentials on the consumer side:

Notes:

• The contract signing entry is consistent with the service category: https://www.tuya.com/vas/commodity/AI_COMPANION.
• Pass catalogCode: "AI_COMPANION" when querying products or credentials on the consumer side. Align the credential / capability details with the capability code vas_ai_companion_fgv5zu5v2csg.
• For other value-added services, replace the category and capability codes with the codes issued by the integration party. Do not reuse the example values in this table.

flowchart TD
  A[1. Commercial signing and material preparation] --> B[2. Activate OEM mall and shop]
  B --> C[3. Write-off signing and quota procurement]
  C --> D[4. Configure virtual products and subscription plans]
  D --> E[5. Associate products with fulfillment services]
  E --> F[6. Channel distribution in write-off mode]
  F --> G[7. OEM app / miniapp sales integration]
  G --> H[8. Device-side capability and member binding]
  H --> I[9. Credential query and reconciliation]

#1. Commercial signing and material preparation

Align with Tuya business / delivery contacts and complete the following:

• Confirm that the settlement model is write-off (sales through the OEM-owned mall).
• Complete value-added service signing / procurement for write-off through the AI Companion value-added service product page (service category code: AI_COMPANION; follow the page guide to complete signing and capability procurement. Specific SKUs and billing are subject to the page and business confirmation).
• Confirm the NetEase Cloud Music service category AI_COMPANION, capability vas_ai_companion_fgv5zu5v2csg (see the code reference above), and billing and fulfillment rules. Periodic subscriptions are the common model.
• Apply for the material number required for transaction revenue posting, and join the revenue posting collaboration process as required by delivery, such as monthly bill confirmation at the beginning of each month.
• Confirm the data center scope: NetEase Cloud Music capabilities are currently mainly in the China Data Center. Mall sites must be configured according to the data center where the target users are located. Each data center's corresponding country site serves all users under that data center, not only users in that country.

If you have questions about codes or API authorization, confirm through Technical Support / Ticket.

#2. Activate the OEM mall and shop

OEM customers need to purchase and activate their own mall, and then prepare the shop and site in the merchant backend:

1. Activate the OEM mall on the mall package page: Mall activation / package pricing.
2. After activation, log in to the merchant backend (Tuya Smart Developer Center / mall merchant backend).
3. Enter the activated OEM mall space.
4. Switch to the target data center based on the business, and select the corresponding country site / shop for configuration.
5. Confirm the shop payment capabilities. Enable WeChat Pay, Alipay, Apple IAP, Google IAP, and other payment methods as needed, subject to the actual OEM app listing and business activation results.

#3. Write-off signing and quota procurement

The write-off model requires the customer to have service inventory quotas that can be deducted. The inventory dimension is usually merchant IoT account + service category + service item. The quota must be topped up before the OEM app can sell the service.

1. If signing is not complete, first complete write-off signing / procurement through the AI Companion value-added service product page. You can select service SKUs, purchase quantities, and submit a quote request as needed:

2. Purchase write-off inventory quotas for NetEase Cloud Music or the corresponding service category according to the commercial contract.
3. Tuya completes quota management and top-up. During top-up, the customer service credential / contract information must be marked for reconciliation.
4. If the quota is insufficient, orders or fulfillment on the user side might fail. Before launch, align with operations on quota level and alerts.

After procurement and top-up, you can view inventory and change details from the following entries:

VAS-side entry example (Personal Center -> My Orders -> Inventory Management -> click to redirect):

IoT Platform "VAS Inventory Management" example. You can query purchase / usage details and inventory levels:

Use the entries above for daily checks of procurement, top-up, and deduction details. Before launch, align the inventory level. When fulfillment is abnormal, first check whether inventory is insufficient or whether the quota has not been topped up to the corresponding service category / service item.

#4. Configure virtual products and subscription plans

Configure sellable virtual products in the OEM mall shop, such as NetEase Cloud Music monthly cards, yearly cards, or trial packages. The following screenshots come from the mall merchant backend configuration flow. Operate in your own OEM mall.

#4.1 Create a virtual product

1. Go to Products -> Product Library, and click Create Product.

2. If there are multiple specifications such as monthly and yearly packages, it is recommended to select Multiple specifications. Clear "This is a physical product" because selecting it will require a shipping address at checkout.

3. It is recommended to select "Continue selling when inventory is 0" to avoid transaction failures in the app due to insufficient inventory.

4. Configure multiple specifications, such as monthly subscription / yearly subscription. Single specification and multiple specifications cannot be converted into each other. If multiple specifications are needed later, you can only create a new product.

5. Complete the description, save, and publish the product.

#4.2 Configure product plans

In Subscription Recharge -> Product Plans, add plans for the product. For one-time purchase only, you do not need to enable "Sell your product as a subscription". Fill in prices for each specification, and enter Apple IAP / Google IAP Product IDs as needed:

For automatic renewal, enable "Sell your product as a subscription" and create periodic plans, including plan type, order cycle, trial / discount, and similar settings:

Monthly package example: Keep the order cycle and fulfillment cycle consistent, such as 30 days. Keep first-purchase discounts / trials consistent with Apple and Google offers:

Plan list example, such as monthly package + yearly package:

Other configuration notes:

• To "automatically charge and renew after the trial ends", use Offer trial in the subscription plan. Do not use one-time payment as a "fake trial".
• Subscription billing usually happens 1 to 2 calendar days in advance to avoid service interruption.
• If the target object is a device or home, make sure to select the corresponding information in the plan. During checkout, users will select a home / device. If you do not want users to select manually, append parameters such as uuid and devId to the product detail URL. The system preferentially uses link parameters.
• In scenarios where IAP is mandatory, options without Apple / Google IAP configured might be filtered out on the client and become invisible. Complete IAP configuration or adjust according to delivery requirements:

• Sync pricing to the required payment channels, such as PayPal, Stripe, Apple IAP, and Google IAP, before publishing and verification:

Configuration result examples. You can tailor them to your business:

• One-time payment "7-day trial": Grants 7 days of entitlement after payment and closes on expiration, with no automatic renewal.
• Subscription "Monthly package": 30-day cycle. Payment is automatically charged before expiration and a new service order is generated.
• Subscription "Yearly package": 365-day cycle. Payment is automatically charged before expiration and a new service order is generated.

#4.3 Apple / Google IAP

If the OEM app sells subscriptions in iOS / Android app stores:

• Apple: Create subscription groups and subscription items (or non-renewing subscriptions) in App Store Connect. Fill the Product ID back into the mall plan. The current Tuya AM product process does not support upgrade / downgrade within the same subscription group. Do not configure upgrade / downgrade strategies. Purchase items must be in the "Approved" state.
• Google: Configure by the "Subscription -> Base plan -> Offer" structure. Align and activate the subscription ID / base plan cycle with the mall plan.

Apple-side key interface examples:

Store-side details are subject to Apple / Google official documentation and the delivery checklist.

#5. Associate products with fulfillment services

After product display and payment configuration are complete, you must configure "Product Service"; otherwise, the platform will not know which capability to activate after the user pays:

1. In Subscription Recharge -> Product Services, click Manage Service for the target product.

2. Select the service category associated with the product, which corresponds to the NetEase Cloud Music category / catalogCode, and configure the fulfillment service and single period for each package.

3. Confirm again: fulfillment period = plan billing period, such as monthly subscription -> 30 days and yearly subscription -> 365 days.

#6. Channel distribution

The order is fixed: associate services first, and then distribute channels.

OEM write-off distribution entry: Sales Channel -> OEM App Channel -> miniapp / device panel, and add the product effective scope:

For device panel distribution, you can bind PID, product, and tags, and specify the effective app:

Product tag configuration example:

#7. Sales integration

After the mall and distribution are ready, integrate sales and entitlement checks in the OEM app, panel, or business miniapp.

#Option 1: Redirect to the generic purchase page

Call getVasSpuList to get basic product information and commodityUrl, and redirect to the generic purchase page to complete checkout.

Key parameters: catalogCode, bindingObjectType (APP / PID / miniapp), bindingObjectCode, bindingTags (if any), needSkuList, and clientInfo.appScheme.

#Option 2: Custom purchase flow

1. Query mall information - getMallInfoV2
2. Query SKU list - getSkuListV2
3. Query payment information - getSkuPayment
4. Create order - createOrderV2
5. Initiate prepayment - getPrepay

For getPrepay, pass contact information according to the fulfillment object: home-level code: '3' (such as groupId) and device-level code: '4' (such as devId / uuid).

#Query user credentials

Call getCredentialList. Use catalogCode to determine whether the service has been activated, and pay attention to effectiveEndDate, quotaUsage.leftQuantity, and similar fields.

In write-off mode, after users pay through your channel, you need to complete quota deduction and credential activation through the fulfillment / write-off open capabilities provided by the integration party. Some open APIs are not publicly self-service. Apply through a ticket before joint debugging, and do not guess production APIs.

#9. Device-side capability and member content

Completing mall sales alone is not enough. To let devices use this capability, you also need to:

1. Enable AI Playback of NetEase Cloud Music during product development, and purchase deliverables while the feature is enabled. The authorization follows the device. If deliverables are purchased before the feature is enabled, the device will not have authorization.
2. Add the "Music Story Skill" to the agent and distribute it to the PID.
3. The panel can call getPanelAgentConfigNetEaseCloudMusic to query supportEnableNetEaseCloudMusic / enableNetEaseCloudMusic.
4. To play the member library: the device owner binds a NetEase account in "Third-Party Content Authorization" in the China-region panel. The manufacturer must have purchased the advanced capability.

#10. Launch checklist

#Custom purchase flow development template

The template helps you quickly build paywall / in-app purchase pages. Capabilities include:

• Product and SKU display
• Apple / Google in-app purchase (IAP)
• PayPal, Stripe, Alipay, WeChat Pay, and other third-party payments depending on actual activation
• Built-in Mock mode: When no backend is available or copy has not been delivered, you can simulate the purchase flow locally for development and demos

Template entry: Service Purchase Template (ServicePurchase)

UI examples:

#Before you start

• You have registered a Tuya developer account, created a miniapp application, and obtained the miniAppId.
• You have completed OEM mall product creation / write-off distribution as described above, or the integration party has provided test products.
• You have enabled in-app purchase and other related capabilities on the platform.
• To debug real-device payments, you need to understand Apple IAP and Google Play listing and payment configurations. Store rules are subject to official requirements.

#Required changes before connecting to the real environment

In src/constants/index.ts:

If you do not yet have a CATEGORY_CODE, apply through Technical Support / Ticket.

#Main pages in the template

#Case

See the case page for details: Top-Up Subscription