Skip to content
CreatoRainCreatoRain API
Not live yet: the v1 API and its hosts are not open. See Sandbox.

What a month costs, as a preview

GET
/bill/preview
curl --request GET \
  --url 'https://api.creatorain.com/v1/bill/preview?month=2026-11' \
  --header 'Authorization: Bearer <token>'

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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
month
string
/^\d{4}-(0[1-9]|1[0-2])$/

Example 

2026-11

YYYY-MM. Defaults to the current UTC month.

Responses

Section titled “Responses”

200

Section titled “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>
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<string>
charged
required
boolean
generated_at
required
string format: date-time

Example 

{
  "object": "bill_preview",
  "month": "2026-11",
  "currency": "USD",
  "preview": true,
  "charged": false,
  "lines": [
    {
      "status": "active"
    }
  ],
  "deposit": {
    "charged": false
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

RateLimit-Limit
integer
Example 
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

Section titled “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>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "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

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

401

Section titled “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>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "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

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

403

Section titled “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>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "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

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

429

Section titled “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>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "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

Section titled “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

Section titled “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>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "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

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

503

Section titled “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>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "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

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.