> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add seats and charge the difference

> Review the key fields for charging a current-period Subscription top-up.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.