# The expected income-tax advance (מקדמות צפויות) for a period

`GET /businesses/{bid}/reports/advances`

Requires the `export` scope.

The figures the Tax Authority's advance form asks for, from the ledger: the period's turnover (a VAT dealer's tax invoices before VAT, a credit note subtracting; a עוסק פטור's receipts with the withholding added back), the advance rate, the advance it comes to, the withholding customers took off the period's receipts, and what is left to pay. Withholding beyond the advance is `excessWithholding`, never a negative payment. The rate is the business's own (`advanceRateBp`, set with `PATCH /businesses/{bid}` `advanceRate`) unless `rate` is passed; with neither, the amounts are null and the turnover still answers. An EXPECTED figure: what is owed is what the business reports to the Tax Authority. `format=pdf` answers the דוח מקדמות צפויות on the business's stationery and `format=xlsx` a workbook (a summary sheet and every document behind the figures); `lines=1` adds those documents to the JSON as `lines`. Nothing is written or stored.

## Path parameters

| Name | Type | | Description |
|---|---|---|---|
| `bid` | string | **required** | Business id, from `POST /businesses`. |

## Query parameters

| Name | Type | | Description |
|---|---|---|---|
| `period` | string | **required** | YYYY-MM: the last month of the period. Bi-monthly, an even month (2026-02 is January and February). |
| `months` | integer |  |  One of: `1`, `2`. Default `1`. |
| `rate` | string |  | A percent (`5`, `4.3`) to use for this answer instead of the business's own. |
| `format` | string |  |  One of: `json`, `pdf`, `xlsx`. Default `json`. |
| `lines` | string |  | With `format=json`: add the documents behind the figures as `lines`. One of: `1`. |

## Response

`200`: raw `application/pdf` bytes.

Errors: `400`, `401`, `403`, `404`, `429`. Every failure answers `{ "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }`: branch on `reason`, and read `hint` for what to change (https://docs.billos.co.il/errors.md).

## Examples

### cURL

```bash
curl -X GET "$BASE/businesses/$BID/reports/advances?period=&months=&rate=" \
  -H "X-Api-Key: $KEY"
  -o document.pdf
```
### Node

```node
const res = await fetch(`${BASE}/businesses/${BID}/reports/advances`, {
  method: 'GET',
  headers: {
    'X-Api-Key': KEY,
  },
})
const pdf = Buffer.from(await res.arrayBuffer())
```
### Python

```python
import requests
res = requests.get(
    f"{BASE}/businesses/{BID}/reports/advances",
    headers={"X-Api-Key": KEY},
)
open("document.pdf", "wb").write(res.content)
```