# Testing Usage Balances

The Gigs [test provider][test-overview] supports Usage Balances, as described in this page. Simulated usage balance on the `Test` provider updates balances immediately with no delay.

## Simulating Usage Balance Usage vs. Simulating Usage Record Usage

Simulating [Usage Balance][usage-balances] usage requires a _seperate_ request from simulating [Usage Record][usage-records] usage. Simulating usage on one will _not_ appear on the other.

This page describes how to simulate Usage Balances. See [Simulate Subscription Usage][test-subscription-usage] for how to simulate Usage Records.

## Prerequisites

- An active test subscription (using a [test SIM][test-sims], not a production SIM)
- The subscription must have status `active` with at least one allowance on the plan

## Step 1: Verify balances exist

After activating a test subscription, confirm that Usage Balances were created:

<CodeGroup title="Fetch balances for a test subscription">

```bash
curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances?subscription=${SUBSCRIPTION_ID}&subscriptionPeriod=current" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"
```

</CodeGroup>

You should see one Usage Balance per allowance on the plan, each with `used: 0`. If the list is empty, the subscription may not have fully activated yet.

## Step 2: Simulate usage against a balance

Pick a `ubl_` ID from the response and simulate usage against it. This example adds 500 MB of data:

<CodeGroup title="Simulate 500 MB of data usage">

```bash
curl --request "POST" \
  --url "https://api.gigs.com/testing/projects/${GIGS_PROJECT}/subscriptions/${SUBSCRIPTION_ID}/usage" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "usageBalance": "ubl_0SNlurA049MEWV4VxLfwJc3PJtHc",
    "usageBalanceAmount": 500000000
  }'
```

</CodeGroup>

The `usageBalanceAmount` is in base units (bytes for data, seconds for voice, messages for SMS). The amount is incremental: it adds to existing usage rather than replacing it.

<Note type="info">

The `/testing/` prefix is only used for the simulation endpoint. All `GET` endpoints use the standard `/projects/` path.

</Note>

## Step 3: Verify the balance updated

Re-fetch the balance to confirm the simulated usage was applied:

<CodeGroup title="Verify updated balance">

```bash
curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances/${USAGE_BALANCE_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"
```

</CodeGroup>

The response should show `used: 500000000`, `remaining` reduced by that amount, and updated percentages.

## Testing add-on balances

To verify an add-on is working:

1. Start with an active test subscription where the base plan balances are confirmed
2. [Attach an add-on][addons-guide] to the subscription and pay the invoice
3. Fetch all balances with `?subscription={id}` (no period filter, or add-on balances will be excluded)
4. Find the new balance where `source.type` is `"subscriptionAddon"`
5. Simulate usage against the add-on's `ubl_` ID
6. Re-fetch and confirm the add-on balance updated while the base plan balance did not change

## Next Steps

- [Testing Overview][test-overview] - General information about testing with Gigs.
- [Usage Events][usage-events] - Verify that threshold and notification events fire after simulated usage.

[usage-balances]: /docs/core/usage/usage-balances-core-concepts
[usage-records]: /docs/core/usage/usage-records-core-concepts
[test-overview]: /docs/core/testing/overview
[test-sims]: /docs/core/testing/test-sims
[test-subscription-usage]: /docs/core/testing/simulate-usage
[addons-guide]: /docs/core/add-ons
[usage-events]: /docs/core/usage/usage-events