# What a month costs, as a preview **Not live yet:** the v1 API and its hosts are not open. See [Sandbox](/get-started/sandbox/). GET /bill/preview Select code sampleFetchcURL ```js const url = 'https://api.creatorain.com/v1/bill/preview?month=2026-11'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://api.creatorain.com/v1/bill/preview?month=2026-11' \ --header 'Authorization: Bearer ' ``` - Live (crp\_live\_ keys) - Sandbox (crp\_test\_ keys) Scope `read`. Read only: nothing is charged (`charged: false`). The month’s bill as the app shows it, one line per location counted on each store’s own clock, in cents; a comped account reads 0 throughout. `total_cents` is null when a line has no locked price yet. `deposit` is the half of month one Checkout would ask today, for the stores that joined in the app and still await payment (stores added through this API are not in it). Over 2000 locations the answer is `503 service_unavailable` rather than a short bill. ## Authorizations - **[bearerAuth](/reference/#bearerauth)** ## Parameters ### Query Parameters **month** string /^\\d{4}-(0\[1-9\]|1\[0-2\])$/ #### Example ``` 2026-11 ``` YYYY-MM. Defaults to the current UTC month. ## Responses ### 200 The preview. Media typeapplication/json A preview. Never charged. Over 2000 locations the route answers 503 instead of a short bill. object **object** required string Allowed values: bill\_preview **livemode** required boolean **month** required string **currency** required string Allowed values: USD **preview** required boolean **charged** required boolean **comped** required boolean **lines** required Array object **location\_id** required string **name** required string nullable **status** required string Allowed values: active paused terminated **plan\_videos\_per\_month** required integer nullable **visits\_completed** required integer **no\_shows** required integer **videos\_published** required integer **makeup\_videos** required integer **billed\_videos** required Excludes free-plan videos (TASK-2916): they are counted, never billed. integer **amount\_cents** required Null when the location has no locked price; 0 when comped. integer nullable **total\_cents** required Null when any line is null. integer nullable **deposit** required object **cents** required The half of month one Checkout would ask today. integer **location\_ids** required Array **charged** required boolean **generated\_at** required string format: date-time #### Example ```json { "object": "bill_preview", "month": "2026-11", "currency": "USD", "preview": true, "charged": false, "lines": [ { "status": "active" } ], "deposit": { "charged": false } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **RateLimit-Limit** integer ##### Example ```json 600 ``` Requests allowed in the current minute for this workspace (600). **RateLimit-Remaining** integer Requests left in the current minute for this workspace. **RateLimit-Reset** integer Seconds until the current window resets. ### 400 Parameter\_invalid (with `field`) or invalid\_json. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 401 Invalid\_key, test\_key\_on\_live or live\_key\_on\_sandbox. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 403 Scope\_missing or forbidden\_ip. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 429 Rate\_limited (600 a minute per workspace, an onboarding create limit, or an address blocked after failed authentication), or slow\_down (an onboarding session polled too fast). Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Retry-After** integer \>= 1 Seconds to wait before retrying (at least 1). ### 500 Internal\_error (500) or service\_unavailable (503). The message never carries a cause. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 503 Service\_unavailable. The read is unavailable right now (for the bill preview, an account over 2000 locations). Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support.