createStorefront

mutation · in the family Storefront

What it does

Set up an online storefront for one of your organizations — pick the selling location, a canned theme, the collections it merchandises, and optionally a browse tree, a channel division and a custom web address.

Create a Storefront — the ecom DTC publish-config under an Organization; requires the unrestricted capability. Publishing is a separate strict door.

What happens

Born as a draft — nothing goes live and no web address is claimed until you publish. Publishing is a separate, stricter step.

Who may call it

Capability area: System and integration setup — Registers, connections and the settings your systems run on.

Owner
System Administrator
An API key whose scope allows api:createStorefront

Arguments

Name	Type	Required	Notes
`input`	NewStorefrontInput `NewStorefrontInput!`	yes	No further notes.

Returns

Storefront Storefront! — A Storefront — the ecom DTC PUBLISH-CONFIG document: which selling facility the site sells from, which canned theme renders it, which collections it merchandises, which browse tree and channel division frame it, and (optionally) the custom domain it claims. The lifecycle: born draft (claiming nothing) → publish (THE INVALID_CONFIG GATE re-validates every ref record-aware + the GLOBAL domain marker claims in the SAME transaction — CONFLICT/IDENTITY_TAKEN if another published site holds the name) → unpublish (the marker releases) → republish (the SAME gate + re-claim). published NEVER dooms — unpublish first (the FSM forbids the edge). THE SERVING ESTATE IS DELIBERATELY ABSENT v1 (the map): publish flips state, claims the domain, validates config — it provisions NOTHING; this record is the control plane the DTC workstream will consume. SEO copy rides the Decoration attachment, never fields here.

Example request

mutation ExampleCreateStorefront($input: NewStorefrontInput!) {
  createStorefront(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    logicalFacilityId
    theme
    customDomain
    collectionIds
    categoryId
    divisionId
  }
}

Variables:

{
  "input": {
    "caption": "Blue jeans",
    "organizationId": "01900000-0000-7000-8000-44b781470000",
    "logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000",
    "theme": "<theme>"
  }
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "createStorefront": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SF-EXMP-0000-000F",
      "type": "Storefront",
      "caption": "Blue jeans",
      "status": "draft",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000",
      "theme": "<theme>",
      "customDomain": "<custom domain>",
      "collectionIds": [
        "01900000-0000-7000-8000-b1c179550000"
      ],
      "categoryId": "01900000-0000-7000-8000-786111a40000",
      "divisionId": "01900000-0000-7000-8000-25bd925b0000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer

VALIDATION/INVALID — Something in the request is not valid. (VALIDATION)
AUTHN/REQUIRED — Sign in to do this. (AUTHN)
AUTHZ/FORBIDDEN — Your role does not allow this action. (AUTHZ)
RATE_LIMIT/THROTTLED — Too many requests in a short time. (RATE_LIMIT)
NOT_FOUND/* — That record could not be found. (NOT_FOUND)
CONFLICT/* — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. (CONFLICT)
VALIDATION/VERSION_REQUIRED — The request did not say which app version it came from. (VALIDATION)

Dry run

Add dryRun: true to the request envelope (extensions.at) to rehearse this call: every check runs, the write is rehearsed against the current records and nothing is stored; the answer is the refusal a real call would give, or the record it would create. Every response to a rehearsal carries dryRun: true, so a rehearsed record is never mistaken for a saved one.

Used in

Open your online storefront