Billing
14 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.
Low-balance thresholds and whether the wallet is under them
GET/v1/billing/low-balance
Thresholds GIEP staff set per currency. below is true from the moment a fee took the wallet under the threshold until a top-up or credit brings it back. Readable while blocked.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/billing/low-balance" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Set statement and billing-notice recipients (empty = owners)
PUT/v1/billing/recipients
Email addresses for weekly statements and billing notices. An empty list sends them to the owners. Requires billing:manage. Audited.
- Authentication
- API key (Bearer)
- Permission
billing:manage- Idempotency-Key
- Required
- Success
200
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
emailsarray<string> · emailrequiredmax 10 items
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X PUT "$GIEP_API_URL/v1/billing/recipients" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-recipients-v1" \
-H "Content-Type: application/json" \
-d '{
"emails": [
"ana@example.com"
]
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Service restriction state and the estimate behind it
GET/v1/billing/service-restriction
Whether you opted in, any staff override, and per currency the wallet balance against the estimated fees of the next subscription billing run. While restricted is true new renewal runs pause with reason insufficient_balance; hosted checkout and refunds are never blocked. Readable while blocked.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/billing/service-restriction" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Opt in or out of pausing renewal runs on insufficient balance
PUT/v1/billing/service-restriction
Owners and admins only. When enabled and the wallet cannot cover the estimated fees of the next billing run, new renewal runs pause until you top up. Audited.
- Authentication
- API key (Bearer)
- Permission
billing:manage- Idempotency-Key
- Required
- Success
200
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
enabledbooleanrequired
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X PUT "$GIEP_API_URL/v1/billing/service-restriction" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-service-restriction-v1" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Billing status: amounts owed, overdue, block state and how to pay
GET/v1/billing/status
Readable while the merchant is blocked for non-payment (MON-012), like the wallet and statements.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/billing/status" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Usage for a month and the GIEP fees posted for it
GET/v1/billing/usage
Payments, subscription renewals, alerts, messages sent (Module 6, messages: deliveries handed to the provider) and AI calls (Module 8, aiCalls: model attempts) in the calendar month (?month=YYYY-MM, UTC, default this month), and the fees posted per kind from the ledger (integer minor units with currency).
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/billing/usage" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Fee schedules that apply to you
GET/v1/fee-schedules
The fee schedule versions that apply to the merchant (transaction, alert, refund and platform fees per currency: basis points, fixed, minimum, maximum, effective from). Set by GIEP staff; read-only here.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/fee-schedules" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}The GIEP Payments application (status `none` before a draft exists)
GET/v1/giep-payments/application
Business details, owners, document references, expected volume, partner reference, decision and status history.
- Authentication
- API key (Bearer)
- Permission
processor:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/giep-payments/application" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Save the application draft (while draft or needs info)
PUT/v1/giep-payments/application
Documents are object-storage references (s3://...), never files. Ownership in basis points may not exceed 100%. Audited.
- Authentication
- API key (Bearer)
- Permission
processor:manage- Idempotency-Key
- Required
- Success
200
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Request body · application/jsonrequired
businessobjectrequiredFields: 6 fields
legalNamestringrequiredmin 2 chars · max 200 charsregistrationNumberstringmax 100 charscountrystringrequiredpattern ^[A-Z]{2}$websitestring · urimax 300 charsdescriptionstringmax 2000 charsmccstringpattern ^\d{4}$
ownersarray<object>requiredmax 10 itemsEach item has 3 fields
namestringrequiredmin 2 chars · max 200 charsownershipBpsintegerrequiredmin 0 · max 10000countrystringrequiredpattern ^[A-Z]{2}$
documentsarray<object>requiredmax 20 itemsEach item has 2 fields
kindstringrequiredmax 50 charsrefstringrequiredpattern ^s3:\/\/[\w./-]+$
expectedMonthlyVolumeobjectFields: 2 fields
amountintegerrequiredgreater than 0currencystringrequired3 chars
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X PUT "$GIEP_API_URL/v1/giep-payments/application" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-application-v1" \
-H "Content-Type: application/json" \
-d '{
"business": {
"legalName": "string",
"country": "US"
},
"owners": [
{
"name": "string",
"ownershipBps": 1,
"country": "US"
}
],
"documents": [
{
"kind": "string",
"ref": "1042"
}
]
}'// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Submit the application to the acquiring partner
POST/v1/giep-payments/application/submit
Idempotent at the partner (one key per application and submission round): a retried submit is the same partner application. The decision arrives later by a signed partner webhook. 503 while no partner is configured.
- Authentication
- API key (Bearer)
- Permission
processor:manage- Idempotency-Key
- Required
- Success
200
Headers
Idempotency-KeystringrequiredRequired with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422
idempotency_key_reused; while the first is still running 409request_in_progress. Signed-in workspace sessions may omit it.min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X POST "$GIEP_API_URL/v1/giep-payments/application/submit" \
-H "Authorization: Bearer $GIEP_API_KEY" \
-H "Idempotency-Key: order-1042-submit-v1"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Export ledger postings (CSV or NDJSON, streamed)
GET/v1/ledger/export
Your wallet and receivable postings with their entries, one consistent snapshot. account is wallet or receivable. Audited.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Query parameters
formatstringOne ofcsvndjsonDefaultcsvfromanytoanycurrencystring3 charsaccountstringmin 1 chars · max 200 chars
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/ledger/export" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}List weekly statements
GET/v1/statements
Weekly statements, newest first, optionally for one currency: period, opening and closing wallet balance, fees by kind and amount owed. Readable while the account is paused for non-payment.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Query parameters
currencystring3 chars
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 422Validation failed (invalid_request) Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/statements" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "invalid_request",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Retrieve a statement
GET/v1/statements/{id}
One statement with its wallet and receivable movements. Readable while the account is paused for non-payment.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Path parameters
idstringrequired
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/statements/d75ce063-5d0b-48fd-a934-a300-567" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}Wallet balances
GET/v1/wallet
Wallet (prepaid balance for GIEP fees) and receivable (fees owed to GIEP) balances per currency, and recent ledger postings. Readable while the account is paused for non-payment.
- Authentication
- API key (Bearer)
- Permission
billing:read- Idempotency-Key
- Not used
- Success
200
Responses
- 200Success
- 401Missing or invalid credentials Body is an
errorobject withcodeandmessage. - 403Role not permitted Body is an
errorobject withcodeandmessage. - 429Rate limited (rate_limited); see Retry-After Body is an
errorobject withcodeandmessage.
The 200 response is a JSON object. The OpenAPI document does not describe its fields.
curl -X GET "$GIEP_API_URL/v1/wallet" \
-H "Authorization: Bearer $GIEP_API_KEY"// JSON object. The OpenAPI document does not list its fields.{
"error": {
"code": "unauthorized",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "forbidden",
"message": "Human-readable explanation"
}
}{
"error": {
"code": "rate_limited",
"message": "Human-readable explanation"
}
}