# Buy extra documents for this month

Buys extra documents for a business for the current monthly period. Each unit adds the number of
documents your contract with Lazy sets per unit to the business's `max_docs`. A unit is not one
document. The extra documents last until the period ends, when `max_docs` returns to the monthly
allowance.

The purchase is billed to your platform in its next monthly bill. Read the new limit with
[Get usage](https://developers.lazyinvoice.co.il/embedded/api/usage/get/).

```text
POST https://embedded-api.lazyinvoice.co.il/v1/businesses/{biz_id}/upgrade/top-up
```

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `biz_id` | string | Yes | The Lazy ID of the business, returned when the business was created. |

### Body

A JSON object with these fields.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `units` | integer | Yes | Top-up units to buy. A unit is not one document: its size in documents is set in your contract with Lazy. Each unit adds that many documents to this month's `max_docs`. Minimum 1. Maximum 100. |

## Responses

### 204 No Content

Bought; `max_docs` is raised. Billed in your next monthly bill. No response body.

## Errors

Every error body is the [error envelope](https://developers.lazyinvoice.co.il/embedded/errors/). Any endpoint can also return 401, 429 and 500; [Errors](https://developers.lazyinvoice.co.il/embedded/errors/) explains them.

| Status | Code, cause and what to do |
| --- | --- |
| 400 | `validation_error`: a body that is not valid JSON or not a JSON object, a missing, mistyped, out-of-range or unknown field, or an unknown query parameter. Fix the request; `param` names the field at fault when there is one. |
| 404 | `not_found`: no business with this `biz_id` belongs to your platform. Check the `biz_id`; a deleted business stays not found. |
| 409 | `business_not_ready`: the business's creation did not finish; repeat the create request with the same `external_id`, then retry. `billing_not_ready`: your platform's billing is not set up yet; contact Lazy. |

## Retry safety

Not safe to retry after a lost response: a retry can buy, and bill, twice. Follow the [purchase recipe](https://developers.lazyinvoice.co.il/embedded/retries/#purchases-top-ups-and-scan-period-extensions).

## Async behavior and events

None. The change is complete when the response arrives, and Lazy sends no webhook for it.

## Examples

### Buy one top-up unit

```bash
curl -X POST https://embedded-api.lazyinvoice.co.il/v1/businesses/biz_8fKq2LmZp4TnWx7RcV1a/upgrade/top-up \
  -H "Authorization: Bearer $LAZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"units": 1}'
```

Response: `204 No Content`, with no body.

### Zero units

```bash
curl -X POST https://embedded-api.lazyinvoice.co.il/v1/businesses/biz_8fKq2LmZp4TnWx7RcV1a/upgrade/top-up \
  -H "Authorization: Bearer $LAZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"units": 0}'
```

Response: `400 Bad Request`

```json
{
  "error": {
    "code": "validation_error",
    "message": "units must be at least 1",
    "param": "units",
    "request_id": "q8Zr1Ndk2vLp0Xw7HcYt3Rb9Fs6Mj4Ge5Ua1Ki8Oy2Wn0Tz7Ql3Px=="
  }
}
```

Added in: [October 2026](https://developers.lazyinvoice.co.il/embedded/changelog/#october-2026)