Advance sandbox
LogsPOST /sandbox/advance
Settle pending simulated payments and optionally generate readings
Available only in sandbox tenants. Moves pending simulated payment sessions of the caller's tenant to an outcome, as a real connector would report it: confirmed (the default) records the payment against its invoice and emits the same events as a live confirmation; failed and expired close the session. Without payment_id every pending simulated session of the tenant is advanced. With readings set to true the call also generates one new cycle of meter readings for the tenant's meters, recorded as the caller, so the caller also needs the meter and reading scopes the meter service checks (business:meters:read, business:readings:read and business:readings:create). Requires the payments:write scope, and business:readings:create as well when readings is true. A live tenant or a missing scope returns 403, an unknown outcome or malformed body returns 400.
Body application/json
payment_idReference of one pending simulated payment session to advance; when omitted, all pending sessions of the tenant are advanced.
outcomeOutcome to apply to the selected sessions.
one of
confirmed,failed,expiredreadingsAlso generate one new cycle of meter readings.
Returns
200 Sessions advanced and readings generated
Show attributes
advanced_paymentsSimulated payment sessions moved by this call; empty when none were pending.
Show child attributes
referenceReference of the simulated payment session.
invoice_idInvoice the session pays, when it pays one.
statusone of
confirmed,failed,expiredtransaction_idSimulated transaction reference, set when confirmed.
generated_readingsMeter readings generated; 0 unless readings was
true.
Permissions payments:write · Roles: admin, billing_clerk, finance, owner
curl -X POST "$BUSINESS_API/sandbox/advance" \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
"outcome": "confirmed",
"readings": false
}'
examplectl sandbox advance --json
const res = await fetch("$BUSINESS_API/sandbox/advance", {
method: "POST",
headers: {
Authorization: "Bearer sk_test_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
"outcome": "confirmed",
"readings": false
})
});
const data = await res.json();
import requests
res = requests.post(
"$BUSINESS_API/sandbox/advance",
headers={
"Authorization": "Bearer sk_test_..."
},
json={
"payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
"outcome": "confirmed",
"readings": false
}
)
data = res.json()
body := strings.NewReader(`{
"payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
"outcome": "confirmed",
"readings": false
}`)
req, _ := http.NewRequest("POST", "$BUSINESS_API/sandbox/advance", body)
req.Header.Set("Authorization", "Bearer sk_test_...")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
{
"advanced_payments": [
{
"reference": "REF-2026-000142",
"invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
"status": "confirmed",
"transaction_id": "tra_2uKL9uwRlmQRRWCNVk2NTMiTDU2"
}
],
"generated_readings": 1342
}