Skip to content
Crossmart Docs

Create a workspace

POST
/api/v1/organizations/{organizationId}/workspaces
curl --request POST \
  --url https://api.crossmart.io/api/v1/organizations/example/workspaces \
  --header 'Content-Type: application/json' \
  --cookie better-auth.session_token=<better-auth.session_token> \
  --data '{ "name": "EU store", "currency": "USD", "timeZone": "Europe/Berlin" }'

For owners of a workspace in the organization, such as one per client or brand. You own the new workspace. Refused (402) past the plan’s workspace limit.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organizationId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
<= 200 characters

Example 

EU store
currency

ISO 4217 code of the catalog prices. It cannot change later.

string
default: USD

Example 

EUR
timeZone

IANA time zone where the workspace’s day starts, for reports, such as Asia/Jerusalem

string

Example 

Europe/Berlin

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
id
required
string format: uuid
organizationId
required
string format: uuid
name
required
string
displayName
required

The name to show: the organization name while the workspace is named Default

string
slug
required
string
currency
required

ISO 4217 code of the catalog prices

string
timeZone
required

IANA time zone that reports follow; null until set

string
nullable
role
required

Your role here

string
Allowed values: OWNER ADMIN EDITOR APPROVER VIEWER CUSTOM
customRole
required

The workspace’s own role, when role is CUSTOM

object
id
required
string format: uuid
name
required
string
permissions
required

What your role lets you do here. Check these, not the role, to adapt a UI.

Array<string>
Allowed values: workspace:view workspace:manage workspace:delete members:view members:manage api-keys:manage products:view products:edit inventory:view inventory:edit orders:view reports:view channels:view channels:manage listings:edit activity:view suggestions:view suggestions:approve billing:view ai:generate

Example 

{
  "currency": "USD",
  "timeZone": "Asia/Jerusalem",
  "role": "OWNER",
  "permissions": [
    "workspace:view"
  ]
}

402

Section titled “402”

The organization’s plan does not allow this (ENTITLEMENTS_ENFORCED is on). code and feature say why; upgrading the plan resolves it.

Media typeapplication/json
object
statusCode
required
number
error
required
string
code
required
string
Allowed values: plan_limit_reached plan_feature_not_included
message
required
string
feature
required
string
Allowed values: active_listings channel_connections workspaces members api_keys ai_credits autonomous_agents bring_your_own_key
plan
required

The code of the organization’s plan

string
limit
required

Null is unlimited

number
nullable
usage
required
number
requested
required

How many more the request asked for

number

Example 

{
  "statusCode": 402,
  "error": "Payment Required",
  "code": "plan_limit_reached",
  "message": "The Free plan includes 2 connected channels, and 2 are in use. Upgrade the plan to add more.",
  "feature": "active_listings",
  "plan": "free"
}