# Update a draft

`PATCH /businesses/{bid}/documents/{id}`

Requires the `documents` scope.

Drafts only. An issued document answers `409 not_draft`; it is immutable at the database engine.

## Path parameters

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

## Body

| Field | Type | | Description |
|---|---|---|---|
| `docType` | integer | **required** | 305 / 320 / 400. A 330 is created only through the credit-note endpoint. One of: `305`, `320`, `400`. |
| `party` | object |  | `{partyId}` to reference a saved party, or an inline `{name, taxId?, phone?, email?, address?}`. Omit entirely for an anonymous cash receipt. |
| `party.partyId` | string |  |  |
| `party.name` | string |  |  |
| `party.taxId` | string |  |  |
| `party.phone` | string |  |  |
| `party.email` | string |  |  |
| `party.address` | string |  |  |
| `priceMode` | string |  | `net` (the default: line prices are ex-VAT) or `gross` (line prices include VAT; the total anchors to the gross sum and VAT is derived). Gross is what a consumer-facing price list wants. One of: `net`, `gross`. Default `net`. |
| `lines` | array of DocumentLine |  | Required for 305/320. |
| `payments` | array of Payment |  | Required for 320/400. |
| `note` | string |  | ≤500 chars. |
| `documentDate` | string |  | Defaults to today, Asia/Jerusalem. |
| `valueDate` | string |  | Defaults to today. |
| `discountAmount` | integer |  | Document-level discount. Integer agorot (₪1 = 100). |
| `withholdingAmount` | integer |  | ניכוי במקור. Integer agorot (₪1 = 100). |
| `allocationNumber` | string |  | מספר הקצאה, when you already hold one. |
| `externalRef` | string |  | Idempotency key, interchangeable with the `Idempotency-Key` header. |

## Response

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

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `document` | Document | **required** | A draft is freely mutable. An issued document is immutable forever, blocked at the database engine, not merely in application code. |

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

## Examples

### cURL

```bash
curl -X PATCH "$BASE/businesses/$BID/documents/$DOC_ID" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docType": 320,
    "party": {
      "name": "דנה לוי",
      "taxId": "514667426",
      "phone": "0521111111",
      "email": "dana@example.com",
      "address": "הרצל 12, תל אביב"
    },
    "priceMode": "gross",
    "lines": [
      {
        "description": "איפור כלה",
        "quantity": 1,
        "unitPriceExVat": 120000
      }
    ],
    "payments": [
      {
        "method": 3,
        "amount": 190000
      }
    ],
    "externalRef": "order-8812"
  }'
```
### Node

```node
const res = await fetch(`${BASE}/businesses/${BID}/documents/${DOC_ID}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "docType": 320,
    "party": {
      "name": "דנה לוי",
      "taxId": "514667426",
      "phone": "0521111111",
      "email": "dana@example.com",
      "address": "הרצל 12, תל אביב"
    },
    "priceMode": "gross",
    "lines": [
      {
        "description": "איפור כלה",
        "quantity": 1,
        "unitPriceExVat": 120000
      }
    ],
    "payments": [
      {
        "method": 3,
        "amount": 190000
      }
    ],
    "externalRef": "order-8812"
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.patch(
    f"{BASE}/businesses/{BID}/documents/{DOC_ID}",
    headers={"X-Api-Key": KEY},
    json={
      "docType": 320,
      "party": {
        "name": "דנה לוי",
        "taxId": "514667426",
        "phone": "0521111111",
        "email": "dana@example.com",
        "address": "הרצל 12, תל אביב"
      },
      "priceMode": "gross",
      "lines": [
        {
          "description": "איפור כלה",
          "quantity": 1,
          "unitPriceExVat": 120000
        }
      ],
      "payments": [
        {
          "method": 3,
          "amount": 190000
        }
      ],
      "externalRef": "order-8812"
    },
)
data = res.json()
```