The short answer: the API reads your invoices, credit, orders and quotes, downloads the PDF, pays invoices from your account credit, changes the cycle of the next renewal and records cancellation requests. It only charges your credit: to pay any other way, use Meu Interweb or the url of each invoice.
The permissions
| To |
Permission |
| Read invoices, orders and quotes, see cycles and get the upgrade link |
billing:read |
| Change the cycle of the next renewal |
billing:write |
| Pay with credit |
billing:pay (sensitive) |
| Request the cancellation of a service |
services:cancel (sensitive) |
Reading invoices and downloading the PDF
GET /v1/invoices returns your invoices, most recent first, in pages; ?status=unpaid shows only unpaid ones. GET /v1/invoices/{id} also returns the lines.
| Field |
What it is |
| total |
The invoice total, including what was paid with credit. |
| credit_applied |
What was paid with credit. |
| balance_due |
What is still to pay. |
GET /v1/invoices/{id}/pdf returns the PDF in content, in base64. Sometimes it cannot come through the API: pdf_available is false, reason says why and url leads to the invoice in Meu Interweb. Your credit and transactions are in GET /v1/billing/credit and GET /v1/billing/transactions.
Paying an invoice with credit
curl https://api.interweb.co.mz/v1/invoices/3127/pay -X POST \
-H "Authorization: Bearer $RLX_API_KEY" \
-H "Idempotency-Key: 0f8fad5b-d9cb-469f-a165-70867728950e"
| 1 |
Always send Idempotency-Key: retrying with the same key does not charge again.
|
|
| 2 |
If the credit is not enough, it answers 402 and nothing is charged.
|
|
| 3 |
The total counts towards the key's spending limit. If it goes over, it answers 403 spending_limit_exceeded, before charging.
|
|
| 4 |
Check status and amount_charged. If the invoice had been paid in the meantime, amount_charged is 0.
|
|
To top up your credit, or pay with another method, see how to pay your invoice.
Changing the cycle of the next renewal
| 1 |
See the cycles on sale and the price of each with GET /v1/services/{id}/billing-cycles. Nothing changes here.
|
|
| 2 |
Request the change with PUT /v1/services/{id}/billing-cycle, with the cycle and the price you saw in expected_amount. If the price has changed, it answers 409 price_changed and nothing is altered.
|
|
The change applies to the next renewal: nothing is charged now and the due date stays the same. It cannot be changed through the API if that service has an unpaid invoice (invoice_open), on a VPS or server (vps_not_supported) or on a service with its own price (custom_price). In those cases can_change is false and blocked_reason says why.
Orders, quotes, upgrades and cancellations
| Operation |
What it does |
| GET /v1/orders, /v1/orders/{id} |
Your orders and what each one contained. |
| GET /v1/quotes, /v1/quotes/{id} |
The quotes sent to you, with the proposal and lines. |
| GET /v1/services/{id}/upgrade-link |
The link to Meu Interweb, where you pick the new plan and see the amount before paying. |
| POST /v1/services/{id}/cancellation |
Records the cancellation for the end of the paid period, never immediately. It takes reason and, in confirm, the service domain (or the plan name). |
|
Cancellation is not immediate: the service stays active until the service_ends_at date, and unpaid invoices for that service may be cancelled. A service with no paid period running, such as a free one or one in arrears, answers 409 no_period_end: in that case, talk to support.
|
|
A practical idea: a daily script lists invoices with ?status=unpaid, compares the balance_due with the credit from GET /v1/billing/credit and pays the ones that fit, using a key that only has billing:read and billing:pay and a sensible spending limit.
|
|
Want to pay invoices from your own system? See the API page and test with a Sandbox key, which tells you whether the payment would go through without charging.
See the API page
|
Português
English
