Bills Service

Manages customer bills and billing information.

List Bills

GET /v1/customers/{id}/bills

Retrieves all bills for a customer with pagination.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID (pattern: usr_*)

Query Parameters:

Parameter	Type	Default	Description
page_size	integer	50	Max results per page (max: 100)
page_token	string	-	Token for next page

Response:

{
  "object": "list",
  "data": [
    {
      "id": "bill_abc123",
      "business_name": "EDM - Electricidade de Mocambique",
      "amount": 1500.00,
      "possible_amounts": [500.00, 1000.00, 1500.00],
      "currency": "MZN",
      "bill_number": "EDM-2025-001234",
      "due_on": "2025-02-15T00:00:00Z",
      "bill_date": "2025-01-15T00:00:00Z",
      "customer_name": "John Doe",
      "business_category": "Utilities",
      "type": "invoice",
      "business_logo": {
        "file_id": "file_logo_edm",
        "file_bucket": "logos",
        "file_link": "/files/logos/file_logo_edm"
      },
      "status": "PENDING"
    }
  ],
  "has_more": false,
  "next_page_token": null
}

Bill Types

Type	Description	Amount Behavior
invoice	Payment due for a service	Amount is fixed; do not specify amount when paying
recharge	Prepaid service top-up	Amount must be specified from possible_amounts

Bill Status Values

Status	Description
PENDING	Bill created, not yet paid
COMPLETED	Bill has been paid in full
CANCELLED	Bill has been cancelled
FAILED	Payment attempt was unsuccessful