Add 1 to 50 locations at once, all or nothing

POST

/locations/batch

curl --request POST \
  --url 'https://api.creatorain.com/v1/locations/batch?dry_run=false' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "locations": [ { "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)

Each location as in POST /locations. All or nothing: any refused item is 400 batch_invalid with every refused item in error.items by index, and nothing is written; a write that fails part way writes nothing either. 201 when any store was created or brought back, 200 when every one was a repeat (or a dry run).

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

locations

required

Array<object>

>= 1 items <= 50 items

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

Every location was a repeat, or a dry run.

Media typeapplication/json

object

object

required

string

Allowed values: list

dry_run

required

boolean

locations

required

Array<object>

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

deposit_total_cents

required

integer

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": "list",
  "locations": [
    {
      "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

At least one location was created or brought back.

Media typeapplication/json

object

object

required

string

Allowed values: list

dry_run

required

boolean

locations

required

Array<object>

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

deposit_total_cents

required

integer

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": "list",
  "locations": [
    {
      "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).