Add seats and charge the difference

This page introduces the current-period top-up use case for an active Subscription and the key fields you need to handle. Call POST /api/v1/subscription/update to update future billing and create an immediate top-up order for the current period in one request.

Key request field	Purpose
`subscriptionRequest` or `subscriptionId`	Identify the Subscription to update
`amount` or `productInfo`	Update billing information starting from the next billing period
`topupInfo`	Create an immediate current-period top-up order; omit it to update future billing only
`topupInfo.topupRequest`	Identify the top-up request; use a unique value for each top-up to preserve idempotency
`topupInfo.topupAmount`	Set the current-period amount to charge immediately

Key response field	Purpose
`previousAmount`	Amount before the update
`newAmount`	New amount used from the next billing period
`nextEffectivePeriod`	Billing period when the new billing information takes effect
`topupInfo.acquiringOrderId`	Immediate top-up order ID used to query the payment result
`topupInfo.topupStatus`	Current top-up order status
`topupInfo.topupAction`	Action information returned when user authorization is required

Behavior rules

topupAmount charges only the current-period difference.
The updated amount or productInfo takes effect from the next billing period.
The immediate top-up does not change the Subscription billing dates or period sequence.
When topupStatus is AUTHORIZATION_REQUIRED, parse topupAction as a JSON string and redirect the user to its webUrl.
Use the Payment order notification as the payment source of truth. If the notification is delayed or lost, call POST /api/v1/order/inquiry with acquiringOrderId.
Do not treat a browser redirect as proof of payment success.

Getting Started

Core Concepts

Integration

Webhook

SDK

Tools & Reference

Point Topup API

Add seats and charge the difference

Behavior rules

​Behavior rules

Behavior rules