Billing

See Resource references for accepted reference kinds, lookup scopes, canonical identities and exact list filters. Billing answers what you have consumed and what you have been charged. It is global — one endpoint, one bill, no region segment:

https://billing.basaltic.sh

One bill covers your whole organization. Usage from every account inside it rolls up into a single monthly invoice, so there is no X-Account-Id on these calls — the organization you authenticated as is the whole scope.

The billing API is read-only, deliberately. Every operation here answers a question; none of them moves money. Settling an invoice, adding or changing a payment method, and billing configuration are console flows at console.basaltic.sh and have no API equivalent. If you are looking for an endpoint to pay an invoice programmatically, there is not one.

Prices

Public and unauthenticated — the whole catalogue, identical for everyone.

Usage and invoices

What is accruing now, and what has already been billed.

Credits

How grants are consumed and where they show up on an invoice.

The collection timeline

Retry days, past due, and what non-payment eventually costs you.

The public price catalogue

GET /v1/prices takes no credentials. Like region discovery, the price catalog is public and does not require a selected account.

curl https://billing.basaltic.sh/v1/prices?service=compute

{
  "prices": [
    {
      "sku": "compute.instance.s1.medium",
      "service": "compute",
      "resource_type": "instance",
      "name": "s1.medium",
      "description": "2 vCPU, 4 GB RAM",
      "unit": "hour",
      "unit_price": "0.085",
      "currency": "BRL",
      "metadata": { "class": "shared", "vcpus": 2, "memory_gb": 4 }
    }
  ],
  "as_of": "2026-08-31T14:02:11Z"
}

It is public because there is nothing tenant-specific in it. There are no account-level rates, discounts or committed-use terms in this table — every caller gets the same numbers, which is precisely why it is safe to publish and useful to read. It exists so that a pricing page or a cost estimator reads the rate billing will actually charge, instead of keeping its own copy that drifts the next time something is repriced.

Because it takes no credentials, the budget is counted per client IP: 100 requests per minute. Read X-RateLimit-Remaining and X-RateLimit-Reset rather than hard-coding that; on a 429, wait Retry-After seconds, since retrying early extends the window. Responses carry Cache-Control: public, max-age=300 — the catalogue changes when something is repriced, not per request, so caching it for five minutes costs you nothing.

Filters

Parameter	Effect
`service`	Only SKUs billed by one service, e.g. `compute`
`resource_type`	Only one resource type, e.g. `instance`
`sku`	Exactly one SKU
`family`	Only SKUs whose `metadata.family` matches
`at`	Read the catalogue as of an RFC 3339 instant instead of now

family is how the managed products are told apart from the general compute flavors they share a resource_type with — load balancer replicas and database cluster nodes are billed as instances, but they are their own family. at is what you use to explain a past invoice: pass the invoice’s period_start and you get the rates that were in force then. as_of in the response echoes the instant the rows were selected as of, so a client can say which revision of the catalogue it is holding.

Money is a decimal string, never a JSON number, everywhere in this API. "0.085" survives a round trip through any language’s JSON parser exactly; a float does not. The quoted rate is the one that will be charged, so it cannot be allowed to round differently on the way out.

There is no pagination on this endpoint. The catalogue is the whole answer — a client that had to page it could observe half of one revision and half of the next.

Additional block-volume performance

Provisioned volume performance has separate IOPS-month and MiB/s-month prices under resource_type=volume-performance. Only the sustained allocation above a volume’s included allowance is charged. Rates are prorated over the actual UTC month from when a change is applied, including time detached or stopped. Returning to the included settings or deleting the volume ends the extra allocation. Performance usage appears after its UTC hour has completed.

Snapshot storage

Snapshot billing uses measured retained logical data, with shared data counted once per volume’s snapshot chain. The snapshot page explains the effective date, hourly calculation and how missing measurements are handled. The source volume is billed separately by provisioned capacity.

Month-to-date usage

GET /v1/usage

Returns unbilled usage accrued so far in the current UTC month, with a per-SKU breakdown ordered by cost:

{
  "amount": "42.87",
  "period_start": "2026-08-01T00:00:00Z",
  "items": [
    { "sku": "compute.instance.m1.small", "description": "m1.small",
      "quantity": "412.5", "unit": "hour", "amount": "26.8125" }
  ],
  "included_usage": []
}

Line amount carries four decimal places while the total carries two. That is not inconsistency — early in a month a line can be worth a fraction of a cent, and rounding it to two places would render it as 0.00 and make it look like nothing is accruing. The total, and every figure on an invoice, stays at the ledger’s two.

Included internet transfer

Every billing organization receives 1 TB per UTC calendar month. All its accounts and regions share one pool. Running instances add the allowance shown for their flavor on the pricing page. Load balancer replicas and database nodes contribute through their billed instance-hours too. A plan’s monthly allowance accrues in proportion to billed hours divided by the actual number of hours in that UTC month. Two instances add their contributions. Stopping or deleting an instance stops further accrual; allowance already earned remains available until month end. Unused allowance does not roll over. Metered internet egress from instances, load balancers, databases and buckets uses this same pool. Buckets do not receive an additional grant. Inbound traffic and private-endpoint traffic do not consume it. Storage capacity and requests retain their separate prices. Only overage is charged, currently R$0.05 per GiB. Allowances use decimal TB (1 TB = 1,000,000,000,000 bytes); a GiB is 1,073,741,824 bytes. The legacy egress SKU still returns the unit token GB, which represents GiB for this SKU. Monetary credits apply after included usage has reduced the billable amount. The console’s usage page shows consumed allowance, total earned allowance, remaining transfer and overage. The included_usage array from GET /v1/usage reports each pool separately. Its base, contributed, total, used, included_used, remaining and overage quantities are decimal strings in unit. Usage lines show net billable quantities. Uninvoiced overage can decrease as more instance allowance accrues; issued invoices remain unchanged. The counted_from timestamp is the beginning of eligible usage. Usage before activation retains its original charges. Each public price’s included_usage quotes the plan’s full-month monthly_quantity and the organization’s monthly_base; the base grant is counted once, not once per plan.

Invoices

An invoice is generated on the 1st of each month, covering the previous UTC calendar month, one per organization.

GET /v1/invoices              # one page, no line items
GET /v1/invoices/{invoice_id} # the invoice with its line items

The list response contains invoices and pagination meta. The detail response wraps the invoice and its line items in invoice. period_start is the first day of the billed month and period_end is exclusive — the first day of the following month. Late-arriving usage from older months sweeps into the next invoice generated rather than reopening a closed one, so an invoice’s line items are not always confined to its labelled period. The arithmetic is subtotal - credits_applied = total. Usage lines carry kind: "usage"; credit lines carry kind: "credit" and a negative amount.

items is populated only on the detail endpoint. GET /v1/invoices returns the invoice documents without line items, because a list of a year’s invoices with every line expanded is a large response nobody asked for.

Statuses

Status	Meaning
`open`	Issued and unpaid. Collection is in progress.
`paid`	Settled. Also how a written-off invoice reads — see below.
`past_due`	The retry schedule ran out without collecting.
`uncollectible`	Given up on.
`void`	Cancelled; nothing is owed.

due_at equals issued_at. An invoice is due when it is issued, and the first charge attempt happens immediately — the days that follow are retries, not a grace period.

Small invoices are written off rather than charged. A total below 1.00 in the invoice currency is written off at generation, and the invoice reads paid without any payment ever having been attempted. The cost of collecting a sub-unit amount exceeds the amount.

The PDF statement

GET /v1/invoices/{invoice_id}/pdf

Rendered on demand from the invoice’s current state, under the same authorization as the invoice document — there is no stored file to drift out of sync with the status it shows. The pdf_url field on an invoice is the path to this endpoint, not a pre-signed link you can hand to someone else.

Billing profile

Read your billing details with GET /v1/profile. Both this response and a successful PUT /v1/profile response wrap the profile in billing_profile. The update request contains the profile fields directly. Keep your billing email and tax details current so fiscal invoices can be issued and delivered.

Fiscal invoices

Fiscal invoices (NFS-e) document confirmed payments. GET /v1/fiscal-invoices returns only issued invoices under fiscal_invoices, with pagination meta. Use limit and the returned meta.marker to read further pages. To select one billing invoice, pass its CRN in the invoice query parameter. Each fiscal invoice includes its own id and crn, amount, number, verification_code, url, issued_at and created_at. The payment field is a resource reference; invoice is a reference or null when no invoice identity is recorded. References contain id, crn and an optional display name. Internal issuance status, delivery state and errors are not part of this response. Download the XML with GET /v1/fiscal-invoices/{id}/xml, or use the returned document URL to view and print it. On an invoice detail page, Fiscal invoices (NFS-e) shows issued documents and their issue dates. Use Refresh to check for newly issued documents, Load More for older entries, and Download XML to save a document.

Credits

GET /v1/credits

A credit grant carries the amount it was issued for and the remaining balance, plus a source — promo, coupon, adjustment or migration — and an optional expires_at. Grants are consumed at invoice generation, soonest-expiring first, until the subtotal is covered. Each consumed slice becomes its own negative line on the invoice and its own credit_applied entry in the ledger, so you can always trace which grant paid for what.

Credits are applied automatically. There is no endpoint to apply one to a particular invoice, and none to redeem a code — a code is redeemed in the console, which is what creates the grant.

Transactions and payments

GET /v1/transactions
GET /v1/payments

GET /v1/transactions is the ledger: payment, refund, adjustment, credit_grant and credit_applied entries.

Transaction amount is always positive. The direction lives in type, not in the sign. Summing amounts without reading types gives you a number that means nothing.

Ledger references

A transaction’s description and reference are independent and can each be null. A non-null reference is a ResourceRef with id, crn and an optional display name. It identifies the related invoice, payment or credit grant. The transaction’s own crn identifies the ledger entry. Invoice references use the invoice number as name; credit references use the credit description. A deleted target keeps its identity, with name omitted. Manual entries and entries without a supported target return reference: null. For example, these illustrative ledger rows show all three target kinds and an entry without a target:

{
  "transactions": [
    {
      "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440010",
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "type": "payment",
      "amount": "10.00",
      "description": "Invoice settlement",
      "reference": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "crn": "crn:billing:::invoice/550e8400-e29b-41d4-a716-446655440000",
        "name": "INV-2026-000042"
      },
      "created_at": "2026-09-01T00:00:00Z"
    },
    {
      "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440011",
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "type": "refund",
      "amount": "10.00",
      "description": "Payment refund",
      "reference": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "crn": "crn:billing:::payment/550e8400-e29b-41d4-a716-446655440000"
      },
      "created_at": "2026-09-01T00:00:00Z"
    },
    {
      "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440012",
      "id": "550e8400-e29b-41d4-a716-446655440012",
      "type": "credit_grant",
      "amount": "10.00",
      "description": "Promotional credit",
      "reference": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "crn": "crn:billing:::credit/550e8400-e29b-41d4-a716-446655440000",
        "name": "Promotional credit"
      },
      "created_at": "2026-09-01T00:00:00Z"
    },
    {
      "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440013",
      "id": "550e8400-e29b-41d4-a716-446655440013",
      "type": "adjustment",
      "amount": "10.00",
      "description": null,
      "reference": null,
      "created_at": "2026-09-01T00:00:00Z"
    }
  ],
  "meta": {
    "has_more": false,
    "limit": 20
  }
}

Follow the kind in reference.crn, rather than inferring it from type: a payment settlement or credit application can reference an invoice directly.

Reference kind	Exact lookup
`invoice`	`GET /v1/invoices?crn=crn:billing:::invoice/{id}`
`payment`	`GET /v1/payments?crn=crn:billing:::payment/{id}`
`credit`	`GET /v1/credits?crn=crn:billing:::credit/{id}`

Replace {id} with the UUID from the reference and URL-encode the crn query value. These filters select the collection item’s own CRN. For example, GET /v1/transactions?crn=crn:billing:::transaction/{id} selects one ledger entry; it does not find every transaction associated with an invoice. All lookups stay within your authenticated organization. A valid but unmatched reference returns an empty collection; malformed references return INVALID_INPUT. For a payment reference, read the matching payment’s invoice reference. When present, use invoice.id with GET /v1/invoices/{invoice_id} to read the invoice and its line items. When invoice is null, no invoice identity is recorded; the payment’s status, amount, attempt and dates remain available. Resolving payments requires billing:ListPayments; an empty or denied lookup does not change the ledger entry or its reference. In the console’s transactions page, Description and Reference appear separately, with - for absent values. Invoice references open invoice details. Click View payment to resolve a payment reference to its invoice or payment details. Credit and unrecognized references remain text.

Payment attempts

GET /v1/payments lists charge attempts. Each row carries attempt, a 1-based counter within the collection schedule for its invoice, and a status of pending, processing, succeeded, failed or refunded. Several rows against one invoice is the normal shape of a retry sequence, not a sign of duplicate charges. Each payment includes invoice as a ResourceRef containing id, crn and an optional name with the current invoice number. Fetch the invoice separately for its status, totals, PDF or line items. If the target has been deleted, the reference retains its identity and omits name; fetching that invoice returns 404. An explicit null means no invoice identity is recorded. For example, a response with one available invoice and one deleted invoice:

{
  "payments": [
    {
      "crn": "crn:billing:::payment/550e8400-e29b-41d4-a716-446655440001",
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "invoice": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "crn": "crn:billing:::invoice/550e8400-e29b-41d4-a716-446655440000",
        "name": "INV-2026-000042"
      },
      "amount": "108.40",
      "status": "succeeded",
      "attempt": 1,
      "completed_at": "2026-09-01T00:01:00Z",
      "created_at": "2026-09-01T00:00:00Z"
    },
    {
      "crn": "crn:billing:::payment/550e8400-e29b-41d4-a716-446655440002",
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "invoice": {
        "id": "550e8400-e29b-41d4-a716-446655440099",
        "crn": "crn:billing:::invoice/550e8400-e29b-41d4-a716-446655440099"
      },
      "amount": "108.40",
      "status": "succeeded",
      "attempt": 1,
      "completed_at": "2026-09-01T00:01:00Z",
      "created_at": "2026-09-01T00:00:00Z"
    }
  ],
  "meta": {
    "has_more": false,
    "limit": 20
  }
}

What happens to an unpaid invoice

Collection runs on a fixed schedule from the moment the invoice is issued: If none of the three attempts collects, the invoice moves to past_due.

Non-payment eventually costs you your resources. At day 7 the organization is suspended. At day 15 it is terminated, and its resources are deleted after that. Every step re-checks the invoice first, so settling it at any point stops the sequence immediately.

Settle a past_due invoice from the console. That is also where you fix the payment method that caused the declines — the API has no path to either.

Pagination

GET /v1/invoices, /v1/credits, /v1/transactions, /v1/payments and /v1/fiscal-invoices all page the same way: pass limit (default 20, maximum 100) and echo back meta.marker from the previous page.

A limit above the maximum is clamped, not rejected, so a page shorter than the one you asked for is normal. Page until meta.has_more is false — not until a page looks short.

Permissions

Action	Endpoint
`billing:GetCurrentUsage`	`GET /v1/usage`
`billing:GetBillingProfile`	`GET /v1/profile`
`billing:UpdateBillingProfile`	`PUT /v1/profile`
`billing:ListInvoices`	`GET /v1/invoices` and `GET /v1/fiscal-invoices`
`billing:GetInvoice`	`GET /v1/invoices/{id}` and its PDF; `GET /v1/fiscal-invoices/{id}/xml`
`billing:ListCredits`	`GET /v1/credits`
`billing:ListTransactions`	`GET /v1/transactions`
`billing:ListPayments`	`GET /v1/payments`

GET /v1/prices needs no permission, because it needs no identity.

Billing policies cannot be scoped to a resource. Every billing action authorizes against * — the organization boundary is the whole tenant fence here, since there is one bill and it belongs to the organization rather than to any account inside it. A policy granting billing:GetInvoice grants it for every invoice; there is no way to narrow it to one.Grant billing read access at the group level to the people who need it, not broadly. See policies.

Rate limits

How the X-RateLimit-* headers work, and signing every other request.

Policies

Who in your organization can read the bill.

Regions

Why billing has no region segment.

API reference

Every billing operation, with request and response schemas.

Get started

Products

Platform

Help

Prices

Usage and invoices

Credits

The collection timeline

The public price catalogue

Filters

Additional block-volume performance

Snapshot storage

Month-to-date usage

Included internet transfer

Invoices

Statuses

The PDF statement

Billing profile

Fiscal invoices

Credits

Transactions and payments

Ledger references

Payment attempts

What happens to an unpaid invoice

Permissions

Next

Rate limits

Policies

Regions

API reference

Prices

Usage and invoices

Credits

The collection timeline

​The public price catalogue

​Filters

​Additional block-volume performance

​Snapshot storage

​Month-to-date usage

​Included internet transfer

​Invoices

​Statuses

​The PDF statement

​Billing profile

​Fiscal invoices

​Credits

​Transactions and payments

​Ledger references

​Payment attempts

​What happens to an unpaid invoice

​Pagination

​Permissions

​Next

Rate limits

Policies

Regions

API reference

The public price catalogue

Filters

Additional block-volume performance

Snapshot storage

Month-to-date usage

Included internet transfer

Invoices

Statuses

The PDF statement

Billing profile

Fiscal invoices

Credits

Transactions and payments

Ledger references

Payment attempts

What happens to an unpaid invoice

Pagination

Permissions

Next