Testing Usage Balances

The Gigs test provider 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 requires a seperate request from simulating Usage Record usage. Simulating usage on one will not appear on the other.

This page describes how to simulate Usage Balances. See Simulate Subscription Usage for how to simulate Usage Records.

Prerequisites

• An active test subscription (using a test SIM, 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:

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}"

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:

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
  }'

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.

Step 3: Verify the balance updated

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

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

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 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 - General information about testing with Gigs.
• Usage Events - Verify that threshold and notification events fire after simulated usage.