# Update a recurring plan

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

Requires the `documents` scope.

Any field of the input; `active: false` pauses, `nextRunOn` reschedules. Documents already produced are untouched.

## Path parameters

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

## Body

| Field | Type | | Description |
|---|---|---|---|
| `docType` | integer |  | 300 / 305 / 320 / 400 One of: `300`, `305`, `320`, `400`. |
| `partyId` | string |  | A saved party (recommended: a recurring document has a recurring customer). |
| `priceMode` | string |  |  One of: `net`, `gross`. Default `net`. |
| `currency` | string |  |  One of: `ILS`, `USD`, `EUR`, `GBP`, `CHF`, `AUD`, `CAD`. Default `ILS`. |
| `fxRate` | number |  | Fix the rate for every run (a contract in dollars at an agreed rate). Omit to use the Bank of Israel rate of each run date. |
| `lang` | string |  |  One of: `he`, `en`. Default `he`. |
| `brandingThemeId` | string |  | The branding theme it prints in (GET /businesses/{bid}/branding-themes). Omit or `null` for the customer's default, else the main design; `"main"` for the main design whatever the customer's default. Frozen at issue: the issued row names the theme it used, `null` for the main design. |
| `zeroVat` | boolean |  |  |
| `lines` | array of DocumentLine |  | Required for 300/305/320. |
| `payments` | array of Payment |  | Required for 320/400; must cover the total exactly as on a one-off document. |
| `discountAmount` | integer |  |  Integer agorot (₪1 = 100). |
| `note` | string |  | ≤500 chars, printed on every document the plan produces. |
| `interval` | string |  |  One of: `monthly`, `quarterly`, `yearly`. Default `monthly`. |
| `dayOfMonth` | integer |  | 1..28. Default 1. |
| `nextRunOn` | string |  | First run. Default: the plan's day this month if still ahead, else next month. |
| `endOn` | string |  | Last possible run date; the plan pauses itself after it. |
| `autoIssue` | boolean |  | Default false: each run leaves a DRAFT to review. true: each run ISSUES (a permanent, numbered document with nobody looking), which is what a subscription business wants and what a first-time integrator should not switch on before watching a few drafts. |
| `active` | boolean |  | false pauses the plan. |

## Response

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

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `plan` | RecurringPlan | **required** | A template the scheduler turns into a draft (or an issued document, with `autoIssue`) every interval. Not a document: freely editable and deletable. |

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 PATCH "$BASE/businesses/$BID/recurring/$DOC_ID" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priceMode": "gross",
    "lines": [
      {
        "description": "איפור כלה",
        "quantity": 1,
        "unitPriceExVat": 120000
      }
    ],
    "payments": [
      {
        "method": 3,
        "amount": 120000
      }
    ]
  }'
```
### Node

```node
const res = await fetch(`${BASE}/businesses/${BID}/recurring/${DOC_ID}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "priceMode": "gross",
    "lines": [
      {
        "description": "איפור כלה",
        "quantity": 1,
        "unitPriceExVat": 120000
      }
    ],
    "payments": [
      {
        "method": 3,
        "amount": 120000
      }
    ]
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.patch(
    f"{BASE}/businesses/{BID}/recurring/{DOC_ID}",
    headers={"X-Api-Key": KEY},
    json={
      "priceMode": "gross",
      "lines": [
        {
          "description": "איפור כלה",
          "quantity": 1,
          "unitPriceExVat": 120000
        }
      ],
      "payments": [
        {
          "method": 3,
          "amount": 120000
        }
      ]
    },
)
data = res.json()
```