> ## 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.