Add one location to the CreatoRain Network

POST

/locations

curl --request POST \
  --url 'https://api.creatorain.com/v1/locations?dry_run=false' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "name": "Sexy Crab Duluth", "address": "2416 Pleasant Hill Rd, Duluth, GA 30096", "google_place_id": "example", "plan": "paid", "videos_per_month": 4, "accepted_terms": "network-2026-10", "opening_hours": {}, "signature_dishes": [ { "name": "example" } ] }'

• Live (crp_live_ keys)
• Sandbox (crp_test_ keys)

Scope locations:write. The store is created ON HOLD (state: on_hold): nothing recruits or books it until CreatoRain releases it. The plan is the account’s: on the paid plan videos_per_month is 2 to 10 at the locked price per video, and deposit quotes the half of month one (paid later at Checkout, never charged here); on the free plan it is exactly the free plan’s videos for its term, with no deposit. There is no store maximum. Creator selection is CreatoRain’s: a creator field (min_followers, rules, approval_mode, …) is 400 customization_not_supported. The same place again answers 200 with outcome: repeat and the STORED plan (a create never updates one); a place another team of this account holds is 409 location_already_in_network.

Authorizations

• bearerAuth

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 255 characters /^[\x21-\x7E]+$/

As Idempotency-Key, and required here (a location create). Without it the answer is 400 idempotency_key_required. A dry run needs one too: it writes no store row; the Idempotency-Key is still stored.

Query Parameters

dry_run

boolean

true validates and quotes: the same refusals as a live call, and writes no store row; the Idempotency-Key is still stored. Ids are null.

Request Body^required

Media typeapplication/json

object

name

required

string

>= 1 characters <= 300 characters

Example

Sexy Crab Duluth

address

required

One of:

string

string

>= 5 characters <= 400 characters

Example

2416 Pleasant Hill Rd, Duluth, GA 30096

object

object

line1

required

string

<= 300 characters

city

required

string

<= 120 characters

state

required

string

<= 120 characters

postal_code

string

nullable <= 40 characters

country

string

nullable <= 120 characters

google_place_id

string

nullable <= 300 characters

plan

Absent means the account’s plan; another plan is 422 package_not_available.

string

Allowed values: paid free

videos_per_month

required

Paid: 2 to 10. Free: exactly the free plan’s videos. Otherwise 400 videos_per_month_out_of_range.

integer

Example

4

accepted_terms

The network terms version accepted

string

nullable /^[a-z0-9][a-z0-9.-]{2,59}$/

Example

network-2026-10

opening_hours

The store’s week

object

signature_dishes

Array

<= 50 items

One of:

string

string

<= 300 characters

object

object

name

required

string

<= 300 characters

Responses

200

A repeat of a live store (nothing written), or a dry run.

Media typeapplication/json

object

object

required

string

Allowed values: location

id

required

Null on a dry run.

string

nullable

outcome

required

string

Allowed values: create repeat revive

livemode

required

boolean

name

required

string

nullable

address

required

string

nullable

plan

required

string

Allowed values: paid free

videos_per_month

required

integer

nullable

term_months

required

Free: the free term. Paid: null, until stopped.

integer

nullable

price_per_video_cents

required

integer

nullable

currency

required

string

Allowed values: USD

deposit

required

object

cents

required

The half of month one: videos_per_month x price_per_video_cents / 2. Free: 0.

integer

nullable

charged

required

Never charged by this call.

boolean

state

required

The network state; null on a dry run.

string

nullable

dry_run

required

boolean

account

required

object

counting_locations

required

Live stores of this account after the call (a dry run - as it would be).

integer

min_locations

required

integer

blockers

required

Below_minimum while counting_locations is under min_locations.

Array<string>

Example

{
  "object": "location",
  "id": "loc_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e",
  "outcome": "create",
  "plan": "paid",
  "price_per_video_cents": 30000,
  "currency": "USD",
  "deposit": {
    "charged": false
  },
  "state": "on_hold",
  "account": {
    "min_locations": 3
  }
}

Headers

Request-Id

string format: uuid

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

Idempotent-Replayed

string

Allowed values: true

True when this answer is the stored response to an earlier request with the same Idempotency-Key.

201

Created, or an ended store brought back (outcome: revive); on hold either way.

Media typeapplication/json

object

object

required

string

Allowed values: location

id

required

Null on a dry run.

string

nullable

outcome

required

string

Allowed values: create repeat revive

livemode

required

boolean

name

required

string

nullable

address

required

string

nullable

plan

required

string

Allowed values: paid free

videos_per_month

required

integer

nullable

term_months

required

Free: the free term. Paid: null, until stopped.

integer

nullable

price_per_video_cents

required

integer

nullable

currency

required

string

Allowed values: USD

deposit

required

object

cents

required

The half of month one: videos_per_month x price_per_video_cents / 2. Free: 0.

integer

nullable

charged

required

Never charged by this call.

boolean

state

required

The network state; null on a dry run.

string

nullable

dry_run

required

boolean

account

required

object

counting_locations

required

Live stores of this account after the call (a dry run - as it would be).

integer

min_locations

required

integer

blockers

required

Below_minimum while counting_locations is under min_locations.

Array<string>

Example

{
  "object": "location",
  "id": "loc_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e",
  "outcome": "create",
  "plan": "paid",
  "price_per_video_cents": 30000,
  "currency": "USD",
  "deposit": {
    "charged": false
  },
  "state": "on_hold",
  "account": {
    "min_locations": 3
  }
}

Headers

Request-Id

string format: uuid

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

Idempotent-Replayed

string

Allowed values: true

True when this answer is the stored response to an earlier request with the same Idempotency-Key.

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

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>

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

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>

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

Request-Id

string format: uuid

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

409

Location_already_in_network (another team of this account holds the place, or the same place under another name), idempotency_conflict or idempotency_in_progress.

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

Request-Id

string format: uuid

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

422

Package_not_available (a plan other than the account’s, or a free-plan account bringing back a store that already ran its free term).

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

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>

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

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>

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

Request-Id

string format: uuid

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

503

Service_unavailable. A concurrent request wrote one of these locations; retry after Retry-After with the same key (it was not stored).

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

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).