Billing and usage

This page covers cost estimation, resource usage reporting, wallets, coupons, rate cards, and billing subject lifecycle management. Several sections are operator-only (staff or system sessions) and are included here for completeness; a normal user token cannot call those endpoints. See shared conventions for authentication, pagination, and error shapes.

All monetary amounts are micro-USD (1 USD = 1,000,000). A balance of 20000000 means $20.00.

Estimates and usage

Estimate a configuration cost

POST/v1/billing/estimateEstimate the hourly rate and monthly price of a configuration

Returns the resolved hourly rate and monthly price for a set of billable parts without creating anything. Available to any authenticated caller; no workspace permission is required.

Request body

Field	Type	Required	Description
region	string	yes	Region to price against, for example NA_01
parts	object[]	yes	Billable line items; each is a discriminated object keyed by type

Each item in parts is one of:

CPU

Field	Type	Description
type	string	CPU
cpu	integer	Number of vCPU cores
service_group	string	Service group qualifier, for example LIGHTNING; omit for any
cpu_model	string	CPU model qualifier; omit for any

MEMORY

Field	Type	Description
type	string	MEMORY
memory_bytes	integer	Memory in bytes

STORAGE

Field	Type	Description
type	string	STORAGE
storage_bytes	integer	Disk size in bytes
storage_backing	string	Backing qualifier, for example ceph or nvme; omit for any

BANDWIDTH

Field	Type	Description
type	string	BANDWIDTH
direction	string	UPLOAD or DOWNLOAD
speed_bytes_sec	integer	Cap in bytes per second

FLOATING_IP

Field	Type	Description
type	string	FLOATING_IP
family	string	IP family: IPv4 or IPv6
ddos	boolean	Whether DDoS protection is included (IPv4 only)

curl -X POST https://api.galaxygate.net/v1/billing/estimate \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "NA_01",
    "parts": [
      { "type": "CPU", "cpu": 2 },
      { "type": "MEMORY", "memory_bytes": 2147483648 },
      { "type": "STORAGE", "storage_bytes": 53687091200 }
    ]
  }'

Returns the cart total and a per-line-item breakdown.

Field	Type	Description
hourly_rate	integer	Total micro-USD per hour
monthly_price	integer	Total micro-USD per month (hourly_rate * 672)
parts	object[]	Per-item cost; each has type, quantity, unit_rate, hourly_rate, monthly_price

Get a user's usage statement

GET/v1/wallet/{uid}/usageUsage statement across all workspaces

Returns the caller's resource usage across every workspace for a time window. Pass @me as uid to address your own account; staff may pass a numeric user ID to view any account.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Query parameters

Name	Type	Required	Description
from	string	yes	Window start, ISO-8601 (inclusive), for example 2026-07-01T00:00:00Z
to	string	yes	Window end, ISO-8601 (exclusive)

curl "https://api.galaxygate.net/v1/wallet/@me/usage?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

Returns a usage summary.

Field	Type	Description
from	string	Window start
to	string	Window end
total_minutes	integer	Total runtime minutes across all workspaces
total_cost	integer	Total cap-aware cost in micro-USD
workspaces	object[]	Per-workspace breakdown; each has workspace_id, workspace_name, total_minutes, total_cost, and a resources array

Each item in resources has:

Field	Type	Description
resource_id	string	Resource ID (serialized as a string)
resource_kind	string	Kind of resource, for example INSTANCE
resource_name	string	Name snapshot from when the subject was created
minutes	integer	Runtime minutes over the window
cost	integer	Cap-aware cost in micro-USD

Get workspace usage

GET/v1/workspaces/{wid}/usageUsage statement for a workspace

Returns resource usage for a single workspace. Requires Read permission on the workspace.

Path parameters

Name	Type	Description
wid	integer	Workspace ID

Query parameters

Name	Type	Required	Description
from	string	yes	Window start, ISO-8601 (inclusive)
to	string	yes	Window end, ISO-8601 (exclusive)

curl "https://api.galaxygate.net/v1/workspaces/42/usage?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

Returns a workspace usage summary with workspace_id, workspace_name, from, to, total_minutes, total_cost, and a resources array in the same shape as the user statement above.

Get a single resource's usage

GET/v1/workspaces/{wid}/usage/{rid}Usage for one resource over a window

Returns usage for a single billable resource. Requires Read permission on the workspace.

Path parameters

Name	Type	Description
wid	integer	Workspace ID
rid	integer	Resource ID

Query parameters

Name	Type	Required	Description
from	string	yes	Window start, ISO-8601 (inclusive)
to	string	yes	Window end, ISO-8601 (exclusive)

Returns a single ResourceUsage object with resource_id, resource_kind, resource_name, minutes, and cost.

Wallet

The wallet endpoints are all under /v1/wallet/{uid}, where uid is a numeric user ID or @me for the current session. Read endpoints (balance, grants, history, movements) resolve to your own wallet, or to any wallet for operator sessions. Write endpoints (top-up, adjust, refund, coupon) require an operator session.

Get wallet balance

GET/v1/wallet/{uid}Wallet balance

Path parameters

Name	Type	Description
uid	string	User ID or @me

curl https://api.galaxygate.net/v1/wallet/@me \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

Returns the wallet balance.

Field	Type	Description
balance	integer	Grants minus usage in micro-USD; may be negative when overdrawn
usage	integer	Spend this billing period in micro-USD
overage	integer	Spend beyond available grants in micro-USD

List credit grants

GET/v1/wallet/{uid}/grantsList top-ups and coupons on a wallet

Lists all credit grants (top-ups, coupons, and adjustments) that have been applied to the wallet. Does not show remaining balance per grant; use history for that.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Returns an array of grant objects.

Field	Type	Description
id	string	Grant ID
type	string	topup, coupon, or adjustment
amount	integer	Original grant amount in micro-USD
effective_at	string	When the grant took effect
expires_at	string	When the unused remainder expires; null for non-expiring grants
code	string	Coupon code that triggered this grant, if applicable
payment_ref	string	Payment reference, if applicable

Get balance history

GET/v1/wallet/{uid}/historyBalance history over a window

Returns a burndown view of the wallet balance broken into segments of a chosen granularity.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Query parameters

Name	Type	Required	Description
from	string	yes	Window start, ISO-8601 (inclusive)
to	string	yes	Window end, ISO-8601 (exclusive)
window	string		Segment granularity: DAY, MONTH, etc. Defaults to DAY

curl "https://api.galaxygate.net/v1/wallet/@me/history?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z&window=DAY" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

Returns an array of history segments.

Field	Type	Description
from	string	Segment start (inclusive)
to	string	Segment end (exclusive)
usage	integer	Spend over this segment in micro-USD
balance	integer	Balance at the end of the segment in micro-USD
grant_balances	object	Remaining micro-USD per grant ID at segment end

List credit movements

GET/v1/wallet/{uid}/movementsPaginated credit movement history

Lists all credit movements (top-ups, coupons, adjustments, and refunds) newest first. This is the ledger of actual money-in / money-out events; it is distinct from usage spend. Supports pagination.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Returns a paged envelope of movement objects.

Field	Type	Description
id	string	Movement ID
type	string	Movement kind: COUPON, TOP_UP, ADJUSTMENT, REFUND
amount	integer	Signed credit change in micro-USD; positive adds credit, negative draws it down
memo	string	Human-readable note; null when not set
reference	string	External reference (payment ref, coupon code, or refund reference); null when not set
created_at	string	When this movement was recorded

Top up a wallet (operator)

POST/v1/wallet/{uid}/topupAdd permanent credit to a wallet

Operator only

This endpoint requires a staff or system session.

Adds a permanent (non-expiring) credit grant to the wallet. The payment_ref field is an idempotency anchor: if the same reference is submitted twice, the second call is a no-op.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Request body

Field	Type	Required	Description
amount	integer	yes	Amount to credit in micro-USD
payment_ref	string		Payment reference (idempotency anchor)

Returns the created grant object in the same shape as the items returned by GET /v1/wallet/{uid}/grants.

Apply a credit adjustment (operator)

POST/v1/wallet/{uid}/adjustApply a signed adjustment to a wallet

Operator only

This endpoint requires a staff or system session.

Applies a signed adjustment to the wallet. A positive amount credits the wallet; a negative amount draws it down the same way as usage.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Request body

Field	Type	Required	Description
amount	integer	yes	Signed amount in micro-USD
memo	string		Reason note

Returns the updated wallet balance in the same shape as GET /v1/wallet/{uid}.

Issue a refund (operator)

POST/v1/wallet/{uid}/refundDraw a refund off a wallet

Operator only

This endpoint requires a staff or system session.

Records a refund against the wallet. A refund draws the balance down by amount and is tagged so that usage reports exclude it from real resource spend.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Request body

Field	Type	Required	Description
amount	integer	yes	Amount to draw down in micro-USD
reference	string		External reference for the refund
memo	string		Reason note

Returns the updated wallet balance in the same shape as GET /v1/wallet/{uid}.

Redeem a coupon into a wallet (operator)

POST/v1/wallet/{uid}/couponRedeem an expiring coupon into a wallet

Operator only

This endpoint requires a staff or system session.

Creates an expiring credit grant on the wallet. Coupon credit burns before any permanent top-up credit. For self-serve code redemption by end users, see Redeem a coupon code below.

Path parameters

Name	Type	Description
uid	string	User ID or @me

Request body

Field	Type	Required	Description
amount	integer	yes	Credit to grant in micro-USD
code	string		Coupon code to associate with the grant
expiry_days	integer		Days until the unused remainder expires; defaults to 30

Returns the created grant object.

Coupons

Redeem a coupon code

POST/v1/coupons/redeemRedeem a coupon code into your account

Redeems a coupon code against the caller's own account. On success the credit is added to the caller's wallet and any workspace flags carried by the coupon are applied to their owned workspaces. A valid session is required.

Request body

Field	Type	Required	Description
code	string	yes	The coupon code to redeem

Returns the redemption result.

Field	Type	Description
amount	integer	Wallet credit added in micro-USD
expires_at	string	When the granted credit expires; null if it does not expire
flags	string[]	Workspace flags applied to the caller's owned workspaces
workspaces	integer	Number of owned workspaces the flags were applied to

List coupons (operator)

GET/v1/couponsList all coupons

Operator only

This endpoint requires a staff or system session.

Lists all coupons with pagination.

Returns a paged envelope of coupon objects.

Field	Type	Description
id	string	Coupon ID
code	string	The redeemable coupon code
amount	integer	Credit granted on redemption in micro-USD
expiry_days	integer	Days until the granted credit expires
flags	string[]	Workspace flags applied on redemption
note	string	Admin memo
max_uses	integer	Total redemptions this coupon allows
uses_remaining	integer	Redemptions still available
created_at	string	When this coupon was minted

Create a coupon (operator)

POST/v1/couponsMint a coupon

Operator only

This endpoint requires a staff or system session.

Request body

Field	Type	Required	Description
amount	integer	yes	Credit granted on redemption in micro-USD
uses	integer	yes	Number of distinct users who may redeem this coupon
code	string		Custom coupon code; auto-generated when omitted
expiry_days	integer		Days until the granted credit expires; defaults to 30
flags	string[]		Workspace flags applied to the redeemer's owned workspaces
note	string		Admin memo

Returns the full coupon entity.

Get a coupon (operator)

GET/v1/coupons/{cid}Fetch a coupon by ID

Operator only

This endpoint requires a staff or system session.

Path parameters

Name	Type	Description
cid	integer	Coupon ID

Returns the full coupon entity.

Delete a coupon (operator)

DELETE/v1/coupons/{cid}Delete an unredeemed coupon

Operator only

This endpoint requires a staff or system session.

Deletes the coupon. Only unredeemed coupons (or those with remaining uses) may be deleted.

Path parameters

Name	Type	Description
cid	integer	Coupon ID

Returns 204 No Content on success.

Rate cards

All rate card endpoints require an operator session. Each rate-card entry is effective-dated: the resolver picks the entry with the latest effective_from that is on or before the billing instant.

List all rate cards (operator)

GET/v1/pricesList the current head of every rate card

Operator only

This endpoint requires a staff or system session.

Returns the most recent entry for every rate card across all types.

Returns an array of rate view objects (see field table under Get a rate card by type).

Get a rate card by type (operator)

GET/v1/prices/{type}Full rate history for a type

Operator only

This endpoint requires a staff or system session.

Returns every effective-dated entry for the given type, latest first.

Path parameters

Name	Type	Description
type	string	Rate card type: CPU, MEMORY, STORAGE, BANDWIDTH, or IP

Returns an array of rate view objects.

Field	Type	Description
id	string	Rate ID
type	string	Rate card type
region	string	Region this rate applies to
service_group	string	Service group qualifier (CPU only); null when unscoped
cpu_model	string	CPU model qualifier (CPU only); null when unscoped
storage_backing	string	Storage backing qualifier (STORAGE only); null when unscoped
direction	string	Bandwidth direction (BANDWIDTH only); null when unscoped
family	string	IP family (IP only); null when unscoped
ddos	boolean	DDoS qualifier (IP only); null when unscoped
unit_rate	integer	Micro-USD per unit per hour
effective_from	string	When this entry takes effect

Create a rate-card entry (operator)

POST/v1/pricesCreate a rate-card entry

Operator only

This endpoint requires a staff or system session.

The body is a discriminated union keyed by type. Common fields across all types:

Field	Type	Required	Description
type	string	yes	Rate card type: CPU, MEMORY, STORAGE, BANDWIDTH, or IP
region	string	yes	Region
unit_rate	integer	yes	Micro-USD per unit per hour
effective_from	string		When this rate takes effect; defaults to now

Additional fields by type:

• CPU: service_group (optional qualifier), cpu_model (optional qualifier)
• STORAGE: storage_backing (optional qualifier)
• BANDWIDTH: direction (optional UPLOAD or DOWNLOAD qualifier)
• IP: family (optional IPv4 or IPv6 qualifier), ddos (optional boolean qualifier)

Responds 201 Created. Returns the created rate view object.

Update a rate-card entry (operator)

PATCH/v1/prices/{type}/{pid}Update a rate-card entry

Operator only

This endpoint requires a staff or system session.

Updates the rate or effective date. The qualifiers (region, service group, and so on) are immutable after creation.

Path parameters

Name	Type	Description
type	string	Rate card type
pid	integer	Rate ID

Request body

Field	Type	Description
unit_rate	integer	New micro-USD per unit per hour
effective_from	string	New effective date

Returns the updated rate view object.

Delete a rate-card entry (operator)

DELETE/v1/prices/{type}/{pid}Delete a rate-card entry

Operator only

This endpoint requires a staff or system session.

Path parameters

Name	Type	Description
type	string	Rate card type
pid	integer	Rate ID

Returns 204 No Content on success.

Billing subjects

A billing subject is the internal metering record that tracks a billable resource's runtime. These endpoints let operators control its lifecycle directly, for example when a resource is removed out-of-band from the normal provisioning flow. Suspend and terminate emit a final tick that bills runtime to the exact instant rather than the next hourly boundary; resume advances the billing cursor to skip the paused gap.

All three endpoints require an operator session and return 204 No Content.

Suspend a billing subject (operator)

POST/v1/billing/subjects/{sid}/suspendSuspend a billing subject

Operator only

This endpoint requires a staff or system session.

Stops metering and bills runtime up to the current instant.

Path parameters

Name	Type	Description
sid	integer	Billing subject ID

Returns 204 No Content.

Resume a billing subject (operator)

POST/v1/billing/subjects/{sid}/resumeResume a suspended billing subject

Operator only

This endpoint requires a staff or system session.

Restarts metering. Advances the billing cursor to now so the time the subject was suspended is not billed.

Path parameters

Name	Type	Description
sid	integer	Billing subject ID

Returns 204 No Content.

Terminate a billing subject (operator)

POST/v1/billing/subjects/{sid}/terminateTerminate a billing subject and its dependents

Operator only

This endpoint requires a staff or system session.

Terminates the billing subject and all of its dependents. Bills runtime up to the current instant for each one.

Path parameters

Name	Type	Description
sid	integer	Billing subject ID

Returns an array of subject references for every subject that was terminated, each with its ID and kind.