# Extend how far back the business's email is scanned

Makes Lazy scan a business's email further back in time. Each year adds 365 days to the business's
`max_email_scan_days`, permanently: the extension does not end with the monthly period.

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/scan-period
```

## 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 |
| --- | --- | --- | --- |
| `years` | integer | Yes | Years to add to how far back Lazy scans the business's email. Permanent. Minimum 1. Maximum 10. |

## Responses

### 204 No Content

Bought; `max_email_scan_days` is raised and the email is rescanned. 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

Lazy rescans the business's connected mailboxes in the background, back to the new limit. Documents
from the older email appear as the scan finds them. Lazy sends no webhook when the scan finishes.

## Examples

### Extend the scan by one year

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

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

### Too many years

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

Response: `400 Bad Request`

```json
{
  "error": {
    "code": "validation_error",
    "message": "years must be at most 10",
    "param": "years",
    "request_id": "q8Zr1Ndk2vLp0Xw7HcYt3Rb9Fs6Mj4Ge5Ua1Ki8Oy2Wn0Tz7Ql3Px=="
  }
}
```

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