# Get invoices

`GET /v2/billing/invoices`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobpay.co.za`
- Production: `https://api.bobpay.co.za`

**Authentication:** Bearer token required. Obtain one via `POST /login` (see the Authentication page).

## Example request

```bash
curl -X GET "https://api.sandbox.bobpay.co.za/v2/billing/invoices" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

This endpoint retrieves invoice data for specified invoice IDs, with options for PDF/CSV export and filtering by status.

---

### Request

**Method:** GET
**URL:** `https://api.sandbox.bobpay.co.za/v2/billing/invoices`

---

#### Query parameters

| Key | Description | Type | Required |
| --- | --- | --- | --- |
| id | Filter for a specific invoice ID. | integer | Conditional (if pdf=true) |
| ids | A comma-separated list or array of invoice IDs to retrieve. | integer or array | No |
| account_id | The unique identifier of the account whose invoices are being requested. | integer | No |
| pdf | Boolean flag to return a PDF download link instead of the invoice data. Only takes effect when `id` is specified. | boolean | No |
| start_date | Start date for the time period (format: YYYY-MM-DD HH:MM:SS). | string (date/time) | No |
| end_date | End date for the time period (format: YYYY-MM-DD HH:MM:SS). | string (date/time) | No |
| status | Filter invoices by their payment status (paid, partially-paid, unpaid). | string | No |
| csv | Boolean flag. If true, the CSV is generated in the background and emailed to the authenticated user. | boolean | No |

---

### Response

**Status code:** 200 OK
**Content-Type:** application/json

---

#### Response body (invoices array)

```json
{
    "invoices": [
        {
            "id": 108,
            "account_id": 3,
            "invoice_date": "2022-10-29T00:00:00+02:00",
            "sub_total": 0.09,
            "vat": 0,
            "vat_percentage": 15,
            "total_amount": 0.09,
            "outstanding_amount": 0,
            "status": "paid",
            "time_created": "2022-10-29T00:02:45.346762+02:00",
            "time_modified": "2022-10-29T00:02:49.811339+02:00",
            "metadata": {},
            "invoice_items": [],
            "payment_date": "2022-10-29T00:02:49.811341+02:00",
            "validated": ""
        }
    ],
    "count": 1
}
```

---

#### Response body (download PDF URL)

```json
{
    "invoices": null,
    "download_url": {
        "url": "https://payments-backend-dev-infra-billing.s3.af-south-1.amazonaws.com/pdfs/invoice_108.pdf?...",
        "filename": "pdfs/invoice_108.pdf",
        "bucket": "payments-backend-dev-infra-billing",
        "file_size": 57925
    },
    "count": 1
}
```

---

### Response fields

| Key | Description | Type |
| --- | --- | --- |
| invoices | An array containing the retrieved invoice objects, or null when a PDF is requested. | array of objects |
| id | The unique identifier for the invoice. | integer |
| account_id | The account associated with the invoice. | integer |
| invoice_date | The date the invoice was issued. | string (datetime) |
| sub_total | The subtotal amount before VAT/tax. | float |
| vat | The VAT amount charged. | float |
| vat_percentage | The VAT percentage rate applied. | float |
| total_amount | The total amount of the invoice. | float |
| outstanding_amount | The outstanding (unpaid) amount on the invoice. | float |
| status | The payment status of the invoice (`paid`, `partially-paid`, `unpaid`). | string |
| time_created | Timestamp when the invoice was created. | string (datetime) |
| time_modified | Timestamp when the invoice was last modified. | string (datetime) |
| metadata | Object containing additional information (issuer details, billing info, etc). | object |
| invoice_items | Array of items included in the invoice. | array of objects |
| payment_date | The date and time the invoice was paid. | string (datetime) |
| validated | Additional validation status or information. | string |
| download_url | Object containing download link and metadata if pdf=true. | object |
| count | The total number of invoices returned in the response. | integer |

---

**Note:**

- The `metadata` object contains issuer, account, and billing info, while `invoice_items` lists each billed item and its details.
- When requesting a PDF (`pdf=true`), the `download_url` object is returned in place of the invoices array.