Buy extra documents for this month

Buy extra documents for this month

Copy for LLMView as Markdown

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.

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. Any endpoint can also return 401, 429 and 500; 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.

Async behavior and events

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

Added in: October 2026

Examples

Buy one top-up unit

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

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

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