# Create an expense

`POST /businesses/{bid}/expenses`

Requires the `expenses` scope.

Opens a draft, or records in one call when the body is complete. `amountIncVat` is the GROSS (Israeli prices include VAT) and `vatAmount` is the portion inside it. Never add the two.

## Path parameters

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

## Headers

| Name | Type | | Description |
|---|---|---|---|
| `Idempotency-Key` | string |  | Your own stable id for this call. A retry returns the same row with `deduped: true` instead of creating a duplicate. Interchangeable with `externalRef` in the body. |

## Body

| Field | Type | | Description |
|---|---|---|---|
| `supplierName` | string |  |  |
| `supplierTaxId` | string |  |  |
| `documentDate` | string |  |  |
| `documentNumber` | string |  |  |
| `amountIncVat` | integer |  | Gross, VAT included. Integer agorot (₪1 = 100). |
| `vatAmount` | integer |  | The portion inside the gross. Integer agorot (₪1 = 100). |
| `deductibleVatBp` | integer |  | Basis points; 10000 = fully deductible. |
| `currency` | string |  | ISO 4217, default ILS. |
| `amountIls` | integer |  | Required to record a non-ILS expense. Integer agorot (₪1 = 100). |
| `fxRate` | number |  | Rate used for `amountIls`. |
| `categoryKey` | string |  |  |
| `externalRef` | string |  | Idempotency key. |
| `record` | boolean |  | Record immediately instead of leaving a draft. |

## Response

`201`: `{ "ok": true, … }`

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `expense` | Expense | **required** | The purchase side of the ledger. A recorded expense is immutable; correct it with a storno. |
| `deduped` | boolean |  |  |

Errors: `400`, `401`, `403`, `404`, `429`. Every failure answers `{ "error": …, "reason": … }`. Branch on `reason`.

## Examples

### cURL

```bash
curl -X POST "$BASE/businesses/$BID/expenses" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "order-8812"
  }'
```
### Node

```node
const res = await fetch(`${BASE}/businesses/${BID}/expenses`, {
  method: 'POST',
  headers: {
    'X-Api-Key': KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalRef": "order-8812"
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.post(
    f"{BASE}/businesses/{BID}/expenses",
    headers={"X-Api-Key": KEY},
    json={
      "externalRef": "order-8812"
    },
)
data = res.json()
```