{"openapi":"3.0.0","paths":{"/repository/org/{orgid}":{"get":{"operationId":"RepositoryController_getOrg","parameters":[{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"Organization id to read.","example":"acme-retail"},{"name":"enrich","in":"query","required":false,"description":"Resolve linked records inline.","schema":{"type":"boolean","default":false},"example":false}],"responses":{"200":{"description":"The organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an organization","description":"Fetches one organization by id. The org is a **path parameter**, not the `orgid` header, because this reads an org other than the caller's own — which is why it is root-only.\n\n#### Signature\n\n```http\nGET /repository/org/{orgid} (orgid: string, enrich?: boolean) -> The organization\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootUser`, `RootSystem`, `RootAdmin`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/org-by-hostname/{hostname}`","tags":["Repository · Organizations"]}},"/repository/org-by-hostname/{hostname}":{"get":{"operationId":"RepositoryController_getOrgIdByDomainName","parameters":[{"name":"hostname","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name to resolve.","example":"shop.example.com"},{"name":"enrich","in":"query","required":false,"schema":{"type":"boolean","default":false},"example":false}],"responses":{"200":{"description":"The organization owning that hostname","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an organization by hostname","description":"Resolves an organization from a domain name — how a multi-tenant front end works out which org a request belongs to before it has an `orgid` to send.\n\n#### Signature\n\n```http\nGET /repository/org-by-hostname/{hostname} (hostname: string, enrich?: boolean) -> The organization owning that hostname\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootUser`, `RootSystem`, `RootAdmin`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/org/{orgid}`","tags":["Repository · Organizations"]}},"/repository/org":{"get":{"operationId":"RepositoryController_queryOrg","parameters":[{"name":"keyword","in":"query","required":false,"description":"Search text.","schema":{"type":"string"},"example":"acme"},{"name":"fields","in":"query","required":false,"description":"Include full field detail rather than a summary.","schema":{"type":"boolean","default":false},"example":false}],"responses":{"200":{"description":"Matching organizations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Query organizations","description":"Lists organizations across the platform. **Root-level access only** — this crosses tenant boundaries and is not scoped to a single org.\n\n#### Signature\n\n```http\nGET /repository/org (keyword?: string, fields?: boolean) -> Matching organizations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootUser`, `RootSystem`, `RootAdmin`.\n\n#### Notes\n\n- Cross-tenant. Restrict who holds root roles accordingly.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/org/{orgid}`","tags":["Repository · Organizations"]}},"/repository/org/update/{orgid}":{"post":{"operationId":"RepositoryController_updateOrg","parameters":[{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"Organization to update.","example":"acme-retail"}],"responses":{"201":{"description":"The updated organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update an organization","description":"Updates an organization's settings. Root-level: it can target any org, not just the caller's.\n\n#### Signature\n\n```http\nPOST /repository/org/update/{orgid} (orgid: string, body) -> The updated organization\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/org/delete/{orgid}`","tags":["Repository · Organizations"],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"title":"Acme Retail (EMEA)"}}}}}},"/repository/org/create":{"post":{"operationId":"RepositoryController_createOrg","parameters":[],"responses":{"201":{"description":"The created organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create an organization","description":"Provisions a new organization — a tenant-level operation restricted to root roles.\n\n#### Signature\n\n```http\nPOST /repository/org/create (body) -> The created organization\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/org/update/{orgid}`","tags":["Repository · Organizations"],"requestBody":{"description":"The organization to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"acme-retail"},"title":{"type":"string","example":"Acme Retail"},"hostname":{"type":"string","example":"shop.example.com"}}},"example":{"name":"acme-retail","title":"Acme Retail","hostname":"shop.example.com"}}}}}},"/repository/org/delete/{orgid}":{"delete":{"operationId":"RepositoryController_deleteOrg","parameters":[{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"Organization to delete.","example":"acme-retail"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete an organization","description":"Deletes an entire organization. This is the most destructive operation on the platform — it removes a whole tenant — and is restricted to `RootAdmin` alone, a narrower role than any other endpoint here.\n\nThere is no confirmation step and no undo.\n\n#### Signature\n\n```http\nDELETE /repository/org/delete/{orgid} (orgid: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`.\n\n#### Notes\n\n- Irreversible, and removes an entire tenant's data. `RootAdmin` only.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/org/update/{orgid}`","tags":["Repository · Organizations"]}},"/repository/org/user/{email}":{"get":{"operationId":"RepositoryController_getUserOrg","parameters":[{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"The user's email address.","example":"ada@example.com"}],"responses":{"200":{"description":"Organizations the user belongs to","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a user's organizations","description":"Lists the organizations a user belongs to — how a sign-in flow offers an org picker to someone who is a member of several.\n\n**This route is public**, so it discloses which organizations a given email address belongs to without authentication. Rate-limit anything built on it.\n\n#### Signature\n\n```http\nGET /repository/org/user/{email} (email: string) -> Organizations the user belongs to\n```\n\n#### Access\n\nPublic — no credentials required. Required role(s): `User`.\n\n#### Notes\n\n- Unauthenticated — it confirms both that an account exists and where it has access.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/org/user/{email}:/{orgid}`","tags":["Repository · Organizations"]}},"/repository/org/query/{datatype}":{"post":{"operationId":"RepositoryController_queryOrgData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on.","example":"sf_product"}],"responses":{"201":{"description":"Matching records","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Query data across organizations","description":"Runs a query against a datatype at root level. Restricted to root roles because it is the cross-tenant form of the ordinary repository query.\n\n#### Signature\n\n```http\nPOST /repository/org/query/{datatype} (datatype: string, body) -> Matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootUser`, `RootPowerUser`, `RootSystem`.\n\n#### Notes\n\n- Root-scoped. Verify the tenant boundary before exposing results to a user.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/find/{datatype}`","tags":["Repository · Organizations"],"requestBody":{"description":"The query to run.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"query":{"data.status":"active"},"page":1,"pageSize":50}}}}}},"/repository/org/user/{email}:/{orgid}":{"delete":{"operationId":"RepositoryController_deleteUserOrg","parameters":[{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"The user's email address. A literal `:` must follow it in the URL.","example":"ada@example.com"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"Organization to remove them from.","example":"acme-retail"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Remove a user from an organization","description":"Removes a user's membership of an organization.\n\n**The route path is malformed.** It is declared as `org/user/:email:/:orgid` — with a stray colon after `:email` — so the URL requires a literal `:` between the email and the org id, giving `/repository/org/user/ada@example.com:/acme-retail`. That is almost certainly a typo for `org/user/:email/:orgid`; treat the endpoint as unstable and expect the path to change.\n\n#### Signature\n\n```http\nDELETE /repository/org/user/{email}:/{orgid} (email: string, orgid: string) -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The literal `:` in the path is a defect in the route declaration, not a deliberate separator.\n- Unlike the other org routes, this one declares no role restriction.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/org/user/{email}`","tags":["Repository · Organizations"]}},"/repository/request-approval/{datatype}/{id}":{"get":{"operationId":"RepositoryController_requestApproval","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The approval request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Request approval for a record","description":"Submits a record into its approval workflow.\n\nNote this is mounted on `GET` despite changing state, so it can be triggered by anything that follows a link. Do not expose the URL where it may be prefetched.\n\n#### Signature\n\n```http\nGET /repository/request-approval/{datatype}/{id} (datatype: string, id: string) -> The approval request result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Notes\n\n- A state change on `GET` — and it needs only `read` permission, not `approve`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/approve/{datatype}/{id}`","tags":["Repository · Workflow"]}},"/repository/approve/{datatype}/{id}":{"post":{"operationId":"RepositoryController_approve","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The approved record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Approve a record","description":"Approves a record that is awaiting review, advancing it through its workflow. Requires the `approve` permission, which is separate from `update`.\n\n#### Signature\n\n```http\nPOST /repository/approve/{datatype}/{id} (datatype: string, id: string, body) -> The approved record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:approve`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/reject/{id}`","tags":["Repository · Workflow"],"requestBody":{"description":"Optional approval notes.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"notes":"Checked against the brand guidelines"}}}}}},"/repository/reject/{datatype}/{id}":{"post":{"operationId":"RepositoryController_reject","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/repository/publish/{datatype}/{id}":{"post":{"operationId":"RepositoryController_publish","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The published record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Publish a record","description":"Makes a record publicly visible. Requires `create` permission rather than a dedicated publish right.\n\n#### Signature\n\n```http\nPOST /repository/publish/{datatype}/{id} (datatype: string, id: string) -> The published record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:create`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/unpublish/{datatype}/{id}`","tags":["Repository · Workflow"]}},"/repository/unpublish/{datatype}/{id}":{"post":{"operationId":"RepositoryController_unpublish","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The unpublished record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Unpublish a record","description":"Withdraws a record from public visibility without deleting it. Requires `delete` permission — a heavier right than publishing needs, so an account able to publish may be unable to reverse it.\n\n#### Signature\n\n```http\nPOST /repository/unpublish/{datatype}/{id} (datatype: string, id: string) -> The unpublished record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:delete`.\n\n#### Notes\n\n- Publishing needs `create`; unpublishing needs `delete`. The asymmetry is deliberate but surprising.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/publish/{datatype}/{id}`","tags":["Repository · Workflow"]}},"/repository/history/{datatype}/{id}":{"get":{"operationId":"RepositoryController_history","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"view","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The record's revisions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a record's history","description":"The revision history for a record — what changed, when and by whom. The basis for restoring an earlier version.\n\n#### Signature\n\n```http\nGET /repository/history/{datatype}/{id} (datatype: string, id: string) -> The record's revisions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/history/{restore}`","tags":["Repository · History"]}},"/repository/history/{restore}":{"post":{"operationId":"RepositoryController_historyRestore","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"restore","in":"path","required":true,"description":"Path segment required by the route; the body carries the actual instruction.","schema":{"type":"string"},"example":"restore"}],"responses":{"201":{"description":"The restored record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Restore a record revision","description":"Restores a record to an earlier revision.\n\nThe `{restore}` path segment is part of the route but the work is driven by the body — pass the record and the revision to restore there.\n\n#### Signature\n\n```http\nPOST /repository/history/{restore} (restore: string, body) -> The restored record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:create`, `content:update`.\n\n#### Notes\n\n- Restoring overwrites the current version — take the current state from `history` first if you may need it back.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/history/{datatype}/{id}`","tags":["Repository · History"],"requestBody":{"description":"Which record and revision to restore.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"datatype":"sf_product","id":"66f1a2b3c4d5e6f708192a3b","version":3}}}}}},"/repository/trash-restore":{"post":{"operationId":"RepositoryController_trashRestore","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Restore result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Restore records from trash","description":"Brings soft-deleted records back. Only works for records that were soft-deleted — a hard delete or a truncate leaves nothing to restore.\n\n#### Signature\n\n```http\nPOST /repository/trash-restore (body) -> Restore result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:create`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/delete/{datatype}/{id}`","tags":["Repository"],"requestBody":{"description":"What to restore.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"datatype":"sf_product","ids":["66f1a2b3c4d5e6f708192a3b"]}}}}}},"/repository/isunique/{datatype}/{attribute}/{value}/{scopeValue}":{"get":{"operationId":"RepositoryController_isUnique","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"attribute","required":true,"in":"path","schema":{"type":"string"},"description":"Field to check.","example":"email"},{"name":"value","required":true,"in":"path","schema":{"type":"string"},"description":"Value to test.","example":"ada@example.com"},{"name":"scopeValue","required":true,"in":"path","schema":{"type":"string"},"description":"Restrict uniqueness to a subset.","example":"acme-retail"}],"responses":{"200":{"description":"Whether the value is available","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"unique":{"type":"boolean","example":false}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Check whether a value is unique","description":"Reports whether a value is already taken for an attribute — the check behind \"this username is unavailable\" on a signup form.\n\nThis route is **public**: it can be called without authentication, which means it discloses whether a given email or username exists in the org. Rate-limit any public form built on it.\n\n`scopeValue` narrows the uniqueness check to a subset, for values that need only be unique within a group.\n\n#### Signature\n\n```http\nGET /repository/isunique/{datatype}/{attribute}/{value}/{scopeValue} (datatype: string, attribute: string, value: string, scopeValue: string) -> Whether the value is available\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated. It confirms the existence of accounts — treat it as an enumeration surface.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /repository/create`","tags":["Repository"]}},"/repository/collections/fix":{"post":{"operationId":"RepositoryController_fixCollection","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"What was repaired","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Repair collection definitions","description":"Repairs inconsistencies in the org's collection definitions — an administrative maintenance operation, not part of normal use.\n\nIt rewrites schema metadata. Run it deliberately, not as part of a routine flow.\n\n#### Signature\n\n```http\nPOST /repository/collections/fix () -> What was repaired\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Maintenance operation — it modifies schema definitions across the org.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/collections/{name}/{subName}`","tags":["Repository"]}},"/repository/collection-list":{"get":{"operationId":"RepositoryController_listCollections","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"q","required":true,"in":"query","schema":{"type":"string"}},{"name":"kind","required":true,"in":"query","schema":{"type":"string"}},{"name":"sort","required":true,"in":"query","schema":{"type":"string"}},{"name":"sortType","required":true,"in":"query","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"string"}},{"name":"pageSize","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/repository/collections/{name}/{subName}":{"get":{"operationId":"RepositoryController_getCollection","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Collection name. Omit to list all.","example":"sf_product"},{"name":"subName","required":true,"in":"path","schema":{"type":"string"},"description":"Nested collection name.","example":"variant"},{"name":"enriched","in":"query","required":false,"description":"Include resolved schema detail. **Defaults to true**, unlike most enrich flags on this controller.","schema":{"type":"boolean","default":true},"example":true},{"name":"collectionType","in":"query","required":false,"description":"Filter by collection type.","schema":{"type":"string"},"example":"content"}],"responses":{"200":{"description":"Collection definitions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get collection definitions","description":"Returns the collection (datatype) definitions for the org — the schemas that describe what fields each datatype has. Omit `name` to list them all.\n\nThis is how a generic client discovers what it can create: read the collection definition, then build a form from its schema.\n\n#### Signature\n\n```http\nGET /repository/collections/{name}/{subName} (name: string, subName: string, enriched?: boolean, collectionType?: string) -> Collection definitions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `enriched` defaults to `true` here; the `en` flag elsewhere on this controller defaults to false.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/collections/fix`","tags":["Repository"]}},"/repository/link/{datatype}/{id}":{"get":{"operationId":"RepositoryController_recordLink","summary":"A studio link to a record","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"`{ url, title, datatype }`","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"response not found — No record of that datatype has the given id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"response not found","path":"/repository/link/{datatype}/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"description":"A link to a record in the studio, to hand to a person — \"here it is\" instead of \"the id is 6a5b…\". Returns `{ url, title, datatype }`; the url opens `/app/collection/{datatype}/{id}`, which shows the record in its own app when it has one, else in the Database app. The title is the person's name, else the record's title, subject, name or email.\n\n#### Signature\n\n```http\nGET /repository/link/{datatype}/{id} (datatype: string, id: string) -> `{ url, title, datatype }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Staff only: a customer token gets `403`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | response not found | No record of that datatype has the given id. | Check the id and datatype. Note the message is the literal string `response not found`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/get/{datatype}/{id}`","tags":["Repository"]}},"/repository/get/{datatype}/{id}":{"get":{"operationId":"RepositoryController_getData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"response not found — No record of that datatype has the given id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"response not found","path":"/repository/get/{datatype}/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a record by id","description":"Fetches one record by its `sk`.\n\n**Mind the overload.** This route and `GET /repository/get/{datatype}/{attribute}/{value}` share the same `get/` prefix and are told apart only by how many segments follow. Three segments (`get/product/abc123`) is a lookup by id; four (`get/product/name/widget`) is a lookup by attribute. Getting the arity wrong silently runs the other query.\n\n#### Signature\n\n```http\nGET /repository/get/{datatype}/{id} (datatype: string, id: string) -> The record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This is one of the few repository reads that raises a real `404` rather than returning null.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | response not found | No record of that datatype has the given id. | Check the id and datatype. Note the message is the literal string `response not found`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/find-any-id/{datatype}/{id}`\n- `GET /repository/get/{datatype}/{attribute}/{value}`","tags":["Repository"]}},"/repository/find-any-id/{datatype}/{id}":{"get":{"operationId":"RepositoryController_findOneAnyId","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Any identifier — `sk`, `name`, or another natural key.","example":"cola-330ml"},{"name":"en","required":false,"in":"query","schema":{"type":"boolean"},"description":"Resolve linked records inline instead of returning bare references. Costs extra queries.","example":false},{"name":"published","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The record, or `null` when nothing matches","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a record by any identifier","description":"Resolves a record from whatever identifier you have — the `sk`, the `name`, or another natural key such as a SKU. Use this when the caller holds a slug from a URL rather than a record id.\n\nA record that does not exist comes back as `null` with a `200`, not a `404`.\n\n#### Signature\n\n```http\nGET /repository/find-any-id/{datatype}/{id} (datatype: string, id: string, en?: boolean) -> The record, or `null` when nothing matches\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Returns `null` + `200` for a miss — check the body, not the status.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/get/{datatype}/{id}`","tags":["Repository"]}},"/repository/get/{datatype}/{attribute}/{value}":{"get":{"operationId":"RepositoryController_findByDatatypeAttribute2","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"attribute","required":true,"in":"path","schema":{"type":"string"},"description":"Field to match, **without** a `data.` prefix.","example":"brand"},{"name":"value","required":true,"in":"path","schema":{"type":"string"},"description":"Value to match.","example":"fizzco"},{"name":"l","required":false,"in":"query","schema":{"type":"string"},"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth."},{"name":"en","required":false,"in":"query","schema":{"type":"boolean"},"description":"Resolve linked records inline instead of returning bare references. Costs extra queries.","example":false},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"}],"responses":{"200":{"description":"A page of matching records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}},"total":{"type":"integer","example":42}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Find records by attribute","description":"Lists records of a datatype whose attribute equals a value, paged.\n\nThe attribute is resolved **within the data payload**, so pass the bare field name — `name`, not `data.name`. Prefixing it with `data.` produces a double prefix and matches nothing.\n\nOmitting both attribute and value lists the datatype unfiltered. See the note on `GET /repository/get/{datatype}/{id}` about how these two routes are distinguished.\n\n#### Signature\n\n```http\nGET /repository/get/{datatype}/{attribute}/{value} (datatype: string, attribute: string, value: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string, en?: boolean) -> A page of matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Notes\n\n- Attributes are scoped to the data payload automatically — `data.name` will not match.\n- Matching is exact equality, not a partial or fuzzy match. Use `search` for that.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/find-by-attribute/{datatype}/{attribute}/{attrValue}`\n- `GET /repository/search/{datatype}`","tags":["Repository"]}},"/repository/find-by-attribute/{datatype}/{attribute}/{attrValue}":{"get":{"operationId":"RepositoryController_findByDatatypeAttribute","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"attribute","required":true,"in":"path","schema":{"type":"string"},"description":"Field to match, without a `data.` prefix.","example":"brand"},{"name":"attrValue","required":true,"in":"path","schema":{"type":"string"},"description":"Value to match.","example":"fizzco"},{"name":"l","required":false,"in":"query","schema":{"type":"string"},"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth."},{"name":"keyword","required":false,"in":"query","schema":{"type":"string"},"description":"Text filter applied alongside the attribute match.","example":"cola"},{"name":"en","required":false,"in":"query","schema":{"type":"boolean"},"description":"Resolve linked records inline instead of returning bare references. Costs extra queries.","example":false},{"name":"attributes","in":"query","required":false,"description":"Additional field/value pairs to match, as a map.","schema":{"type":"string"},"example":"status=active"},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"}],"responses":{"200":{"description":"A page of matching records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}},"total":{"type":"integer","example":42}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Find records by attribute","description":"The explicit form of the attribute lookup, without the arity overload of the `get/` routes — prefer this one in new work.\n\nIt additionally accepts an `attributes` map for matching several fields at once, and a `keyword` for a text filter alongside the attribute match.\n\nAs with the `get/` form, attributes are resolved inside the data payload: pass `name`, not `data.name`.\n\n#### Signature\n\n```http\nGET /repository/find-by-attribute/{datatype}/{attribute}/{attrValue} (datatype: string, attribute: string, attrValue: string, attributes?: string, keyword?: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string, en?: boolean) -> A page of matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Notes\n\n- Preferred over `GET /repository/get/{datatype}/{attribute}/{value}` — same behaviour, unambiguous route.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/get/{datatype}/{attribute}/{value}`","tags":["Repository"]}},"/repository/lookup-code":{"post":{"operationId":"RepositoryController_lookupCode","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"What the code resolved to","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"The kind of record matched.","example":"sf_order"},"match":{"type":"object","additionalProperties":true,"description":"The record itself."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Resolve a scanned code","description":"Resolves a scanned string — a barcode, receipt number, ticket code — to the record it identifies, returning `{ type, match }`.\n\nIt answers *what this code is*, not what to do about it: routing the user to the right screen is the client's decision. Narrow the search with `types` when the scanner's context already limits what a code could be.\n\nThis route is **public** — anyone can probe codes against it.\n\n#### Signature\n\n```http\nPOST /repository/lookup-code (body) -> What the code resolved to\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — do not rely on it to keep record existence private.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /repository/find-any-id/{datatype}/{id}`","tags":["Repository"],"requestBody":{"description":"The scanned code.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The scanned string.","example":"9400111899223197428490"},"types":{"type":"array","items":{"type":"string"},"description":"Restrict which record types to try. Omit to try all.","example":["sf_order","ticket"]}}},"examples":{"any":{"summary":"Resolve against everything","value":{"code":"A7K2M9QX4"}},"scoped":{"summary":"Only orders and tickets","value":{"code":"A7K2M9QX4","types":["sf_order","ticket"]}}}}}}}},"/repository/find-timed-data/{startDate}/{endDate}":{"get":{"operationId":"RepositoryController_findTimedData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":true,"in":"path","schema":{"type":"string"},"description":"Start of the range.","example":"2026-08-01"},{"name":"endDate","required":true,"in":"path","schema":{"type":"string"},"description":"End of the range.","example":"2026-08-31"},{"name":"enrich","required":false,"in":"query","schema":{"type":"boolean"},"description":"Resolve linked records inline.","example":false},{"name":"datatypes","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated collections to search. Omit to search the defaults.","example":"sf_order,booking"}],"responses":{"200":{"description":"Records in the range","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Find records in a date range","description":"Returns records falling inside a date range, across one or more datatypes. The read behind a calendar or an activity feed that spans several collections at once.\n\nBoth dates are optional path segments; `datatypes` narrows which collections are searched.\n\n#### Signature\n\n```http\nGET /repository/find-timed-data/{startDate}/{endDate} (startDate: string, endDate: string, datatypes?: string, enrich?: boolean) -> Records in the range\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Notes\n\n- Omitting both dates returns an unbounded range — always supply at least one on a large org.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/search/{datatype}`","tags":["Repository"]}},"/repository/find-page-data/{datatype}/{dataId}":{"get":{"operationId":"RepositoryController_query","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on.","example":"sf_product"},{"name":"dataId","required":true,"in":"path","schema":{"type":"string"},"description":"Restrict to one record.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"l","required":false,"in":"query","schema":{"type":"string"},"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth."},{"name":"keyword","required":false,"in":"query","schema":{"type":"string"},"example":"cola"},{"name":"en","required":true,"in":"query","schema":{"type":"boolean"}},{"name":"site","required":true,"in":"query","schema":{"type":"string"}},{"name":"published","required":true,"in":"query","schema":{"type":"string"}},{"name":"attributes","in":"query","required":false,"schema":{"type":"string"},"example":"status=active"},{"name":"categories","in":"query","required":false,"schema":{"type":"string"},"example":"cold-drinks"},{"name":"tags","in":"query","required":false,"schema":{"type":"string"},"example":"summer-sale"},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"}],"responses":{"200":{"description":"A page of matching records","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Query records (alias)","description":"An alias for `GET /repository/find/{datatype}/{dataId}` — the same handler is mounted at both paths. Prefer `find/`.\n\n#### Signature\n\n```http\nGET /repository/find-page-data/{datatype}/{dataId} (datatype: string, dataId: string, attributes?: string, categories?: string, tags?: string, keyword?: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string) -> A page of matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/find/{datatype}/{dataId}`","tags":["Repository"]}},"/repository/find/{datatype}/{dataId}":{"get":{"operationId":"RepositoryController_query","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on.","example":"sf_product"},{"name":"dataId","required":true,"in":"path","schema":{"type":"string"},"description":"Restrict to one record.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"l","required":false,"in":"query","schema":{"type":"string"},"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth."},{"name":"keyword","required":false,"in":"query","schema":{"type":"string"},"description":"Text filter.","example":"cola"},{"name":"en","required":false,"in":"query","schema":{"type":"boolean"},"description":"Resolve linked records inline.","example":false},{"name":"site","required":true,"in":"query","schema":{"type":"string"}},{"name":"published","required":true,"in":"query","schema":{"type":"string"}},{"name":"attributes","in":"query","required":false,"description":"Field/value pairs to match.","schema":{"type":"string"},"example":"status=active"},{"name":"categories","in":"query","required":false,"description":"Categories to match. Repeat for several.","schema":{"type":"string"},"example":"cold-drinks"},{"name":"tags","in":"query","required":false,"description":"Tags to match. Repeat for several.","schema":{"type":"string"},"example":"summer-sale"},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"}],"responses":{"200":{"description":"A page of matching records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}},"total":{"type":"integer","example":42}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Query records","description":"The richest read on the controller: filters by attributes, categories, tags and keyword together, with paging and sorting.\n\nIt is mounted at two paths — `find/...` and `find-page-data/...` — which behave identically. `find/` is the one to use; the other name is historical.\n\n#### Signature\n\n```http\nGET /repository/find/{datatype}/{dataId} (datatype: string, dataId: string, attributes?: string, categories?: string, tags?: string, keyword?: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string, en?: boolean) -> A page of matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/find-page-data/{datatype}/{dataId}`\n- `POST /repository/find/{datatype}`","tags":["Repository"]}},"/repository/category/{datatype}":{"get":{"operationId":"RepositoryController_getDataTypeCategories","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"Collection to read categories for. Omit for all.","example":"sf_product"}],"responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get categories for a datatype","description":"The categories in use for a datatype. Omit `datatype` for categories across everything.\n\n#### Signature\n\n```http\nGET /repository/category/{datatype} (datatype: string) -> Categories\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/tag`","tags":["Repository"]}},"/repository/tag":{"get":{"operationId":"RepositoryController_getTags","summary":"List tags","description":"The tags defined for the org, optionally filtered by keyword — the source for a tag autocomplete.\n\n#### Signature\n\n```http\nGET /repository/tag (keyword?: string) -> Tags\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/tag`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"keyword","required":false,"in":"query","description":"Filter tags by text.","schema":{"type":"string"},"example":"sum"}],"responses":{"200":{"description":"Tags","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Repository"]},"post":{"operationId":"RepositoryController_addTag","summary":"Create a tag","description":"Adds a tag to the org's tag vocabulary so it can be applied to records and offered in autocomplete.\n\n#### Signature\n\n```http\nPOST /repository/tag (body) -> The created tag\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/tag`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The tag to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"summer-sale"},"title":{"type":"string","example":"Summer Sale"}}},"example":{"name":"summer-sale","title":"Summer Sale"}}}},"responses":{"201":{"description":"The created tag","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Repository"]}},"/repository/find-related/{datatype}/{anyId}":{"get":{"operationId":"RepositoryController_findRelated","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on.","example":"sf_product"},{"name":"anyId","required":true,"in":"path","schema":{"type":"string"},"description":"Any identifier for the source record.","example":"cola-330ml"},{"name":"site","required":true,"in":"query","schema":{"type":"string"}},{"name":"published","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Related records","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Find related records","description":"Returns records linked to a given one, across datatypes. Resolves by any identifier, not just the `sk`.\n\n#### Signature\n\n```http\nGET /repository/find-related/{datatype}/{anyId} (datatype: string, anyId: string) -> Related records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/find/{datatype}/{dataId}`","tags":["Repository"]}},"/repository/find/{datatype}":{"post":{"operationId":"RepositoryController_findPost","summary":"Find records of any data type — look up a user (staff, colleague) by email or name and get their phone, or customers, orders, anything","description":"Look up any data the caller can read: `datatype` is the collection. The org’s people are `user` (staff — name in `data.firstName`/`data.lastName`, `data.title`, `data.email`, `data.phone`); customers are `customer`. Body `{ query, options }`: `query` is a filter on the record (fields under `data.`), `options` `{ page, pageSize, sort }`. Example — a colleague’s phone number: `POST /repository/find/user` with `{ \"query\": { \"data.email\": \"someone@company.com\" } }`. Also mounted at `POST /repository/query/{datatype}`.\n\n#### Signature\n\n```http\nPOST /repository/find/{datatype} (datatype: string, body) -> Matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/query/{datatype}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on.","example":"sf_product"}],"responses":{"201":{"description":"Matching records","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Repository"],"requestBody":{"description":"The filter and paging.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"query":{"data.email":"someone@company.com"},"options":{"page":1,"pageSize":20}}}}}}},"/repository/query/{datatype}":{"post":{"operationId":"RepositoryController_findPost","summary":"Query records with a body (alias)","description":"An alias for `POST /repository/find/{datatype}` — the same handler on both paths.\n\n#### Signature\n\n```http\nPOST /repository/query/{datatype} (datatype: string, body) -> Matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/find/{datatype}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on.","example":"sf_product"}],"responses":{"201":{"description":"Matching records","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Repository"],"requestBody":{"description":"The query to run.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"query":{"data.status":"active"},"options":{"page":1,"pageSize":50}}}}}}},"/repository/find-asset/{datatype}":{"post":{"operationId":"RepositoryController_findAsset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","in":"path","required":true,"description":"The collection to act on.","schema":{"type":"string"},"example":"sf_product"}],"responses":{"201":{"description":"Matching assets","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Find assets","description":"Searches assets of a datatype using a body-supplied query.\n\n#### Signature\n\n```http\nPOST /repository/find-asset/{datatype} (datatype: string, body) -> Matching assets\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/search-asset/{datatype}`","tags":["Repository · Assets"],"requestBody":{"description":"The asset query.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"keyword":"hero","options":{"page":1,"pageSize":50}}}}}}},"/repository/find-experts":{"get":{"operationId":"RepositoryController_findExperts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"keyword","required":true,"in":"query","schema":{"type":"string"},"description":"Search text.","example":"photography"}],"responses":{"200":{"description":"Matching experts","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Find experts","description":"Searches for experts by keyword — a domain-specific lookup that happens to live on the repository controller.\n\n#### Signature\n\n```http\nGET /repository/find-experts (keyword?: string) -> Matching experts\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Repository"]}},"/repository/update-asset/{datatype}/{id}":{"post":{"operationId":"RepositoryController_updateAsset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","in":"path","required":true,"description":"The collection to act on.","schema":{"type":"string"},"example":"sf_product"},{"name":"id","in":"path","required":true,"description":"Asset id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated asset","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update an asset","description":"Updates an asset's metadata.\n\n#### Signature\n\n```http\nPOST /repository/update-asset/{datatype}/{id} (datatype: string, id: string, body) -> The updated asset\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootUser`, `RootSystem`, `RootAdmin`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/delete-asset/{datatype}`","tags":["Repository · Assets"],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"title":"Cola hero image","alt":"A chilled can of cola"}}}}}},"/repository/delete-asset/{datatype}":{"post":{"operationId":"RepositoryController_deleteAsset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","in":"path","required":true,"description":"The collection to act on.","schema":{"type":"string"},"example":"sf_product"}],"requestBody":{"description":"Asset ids to delete, as a bare array.","required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}},"example":["66f1a2b3c4d5e6f708192a3b"]}}},"responses":{"201":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete assets","description":"Deletes several assets at once. The body is a bare array of ids.\n\n#### Signature\n\n```http\nPOST /repository/delete-asset/{datatype} (datatype: string, body) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootUser`, `RootSystem`, `RootAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Deletes the asset records. Whether the underlying files are removed depends on the storage driver.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/delete`","tags":["Repository · Assets"]}},"/repository/search/{datatype}":{"get":{"operationId":"RepositoryController_searchGet","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"keyword","required":false,"in":"query","schema":{"type":"string"},"description":"Text to search for.","example":"cola"},{"name":"query","required":false,"in":"query","schema":{"type":"string"},"description":"Structured filter as a JSON string. Parsed leniently — malformed JSON is ignored.","example":"{\"data.status\":\"active\"}"},{"name":"site","required":true,"in":"query","schema":{"type":"string"}},{"name":"published","required":true,"in":"query","schema":{"type":"string"}},{"name":"datatype","in":"path","required":true,"description":"Collection to search. Omit to search across all.","schema":{"type":"string"},"example":"sf_product"},{"name":"p","in":"query","required":false,"schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"schema":{"type":"integer","default":50},"example":50}],"responses":{"200":{"description":"Matching records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}},"total":{"type":"integer","example":12}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search records","description":"Full-text search across a datatype, with an optional structured `query` for additional filtering. Omit `datatype` to search across everything.\n\n`query` is a JSON string parsed leniently — a malformed value is treated as absent rather than rejected, so a syntax error silently widens the search instead of failing.\n\n#### Signature\n\n```http\nGET /repository/search/{datatype} (datatype: string, keyword?: string, query?: string, p?: integer, ps?: integer) -> Matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Notes\n\n- A malformed `query` is silently dropped. Check the result count if a filter appears to have no effect.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/search/{datatype}`","tags":["Repository"]},"post":{"operationId":"RepositoryController_searchPost","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","in":"path","required":true,"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","schema":{"type":"string"},"example":"sf_product"}],"responses":{"201":{"description":"Matching records","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search records with a body","description":"The POST form of search, for queries too large or too structured to sit in a query string. `query` is a real object here rather than a JSON string, so it is not silently dropped when malformed.\n\n#### Signature\n\n```http\nPOST /repository/search/{datatype} (datatype: string, body) -> Matching records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Notes\n\n- Prefer this over the GET form for anything beyond a simple keyword — the structured query is validated rather than silently ignored.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/search/{datatype}`","tags":["Repository"],"requestBody":{"description":"The search to run.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string","description":"Text to search for.","example":"cola"},"query":{"type":"object","additionalProperties":true,"description":"Structured filter."},"options":{"type":"object","additionalProperties":true,"description":"Paging and sorting.","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50}}}}},"example":{"keyword":"cola","query":{"data.status":"active"},"options":{"page":1,"pageSize":50}}}}}}},"/repository/search-asset/{datatype}":{"post":{"operationId":"RepositoryController_searchAsset","parameters":[{"name":"datatype","in":"path","required":true,"description":"The collection to act on.","schema":{"type":"string"},"example":"sf_product"}],"responses":{"201":{"description":"Matching assets","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search assets","description":"Full-text search across assets of a datatype.\n\n**Note this handler does not read the `orgid` header** — unlike every other asset endpoint, it is not org-scoped at the controller level.\n\n#### Signature\n\n```http\nPOST /repository/search-asset/{datatype} (datatype: string, body) -> Matching assets\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Takes no `orgid` — verify the scoping before relying on it in a multi-tenant context.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/find-asset/{datatype}`","tags":["Repository · Assets"],"requestBody":{"description":"The search to run.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"keyword":{"type":"string","example":"hero"},"query":{"type":"object","additionalProperties":true},"options":{"type":"object","additionalProperties":true}}},"example":{"keyword":"hero"}}}}}},"/repository/update/{id}":{"post":{"operationId":"RepositoryController_updateHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update a record","description":"Replaces a record's data. The datatype is inferred from the record itself, so it is not a path parameter here — unlike almost every other write on this controller.\n\nUse `update-partial` to change a few fields without sending the whole payload.\n\n#### Signature\n\n```http\nPOST /repository/update/{id} (id: string, body) -> The updated record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:update`.\n\n#### Notes\n\n- This writes the payload you send — fields you omit can be lost. Prefer `update-partial` for targeted edits.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/update-partial/{datatype}/{id}`","tags":["Repository"],"requestBody":{"description":"The record to write.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"data":{"sku":"DRK-COLA-330","title":"Cola 330ml","price":12.5}}}}}}},"/repository/update-partial/{datatype}/{id}":{"post":{"operationId":"RepositoryController_updatePartialHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Partially update a record","description":"Writes only the fields you send, leaving the rest of the record untouched. This is the safe way to edit one part of a large record, and the way to avoid two concurrent editors overwriting each other's unrelated fields.\n\nPaths are dotted and absolute within the record — `data.children`, not `children`.\n\n#### Signature\n\n```http\nPOST /repository/update-partial/{datatype}/{id} (datatype: string, id: string, body) -> The updated record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:update`.\n\n#### Notes\n\n- Paths include the `data.` prefix here, unlike the attribute-lookup endpoints which strip it.\n- Send dotted paths, never a nested `data` object. `{\"data\": {...}}` REPLACES the entire `data` field — every key you did not include, such as images, price or attributes, is dropped. Snapshot the record with `find` before any bulk write.\n- Send the `version` you read from `get`. A stale version is rejected instead of silently overwriting a concurrent editor.\n- Read with `get/{datatype}/{id}` before editing. `find` returns a partial projection, so a record edited from a `find` result can lose fields you never saw.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/update/{id}`","tags":["Repository"],"requestBody":{"description":"The fields to write, keyed by dotted path.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Dotted paths to values."},"examples":{"singleField":{"summary":"Change one field","value":{"data.price":12.5}},"nested":{"summary":"Write a nested array","value":{"data.children":[{"name":"cold-drinks"}]}},"withVersion":{"summary":"Pin the write to the version you read","value":{"sk":"6aa7…","version":11,"data.price":12.5}},"destructive":{"summary":"DO NOT do this — replaces the whole data object","value":{"data":{"price":12.5}}}}}}}}},"/repository/bulk-edit/{datatype}":{"get":{"operationId":"RepositoryController_bulkEditRuleHandler","parameters":[{"name":"datatype","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/repository/bulk-update":{"post":{"operationId":"RepositoryController_bulkUpdateHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/repository/setting/{settingType}/{settingName}/{subName}":{"get":{"operationId":"RepositoryController_getSettingHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"settingType","required":true,"in":"path","schema":{"type":"string"},"description":"Setting group.","example":"securitySettings"},{"name":"settingName","required":true,"in":"path","schema":{"type":"string"},"description":"Named setting within the group.","example":"passwordPolicy"},{"name":"subName","required":true,"in":"path","schema":{"type":"string"},"description":"Nested value within the setting.","example":"minLength"}],"responses":{"200":{"description":"The setting value","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an org setting","description":"Reads an organization setting. `settingType` names the group; `settingName` and `subName` drill into named or nested values.\n\nSettings can hold credentials and security configuration, which is why these routes are admin-only.\n\n#### Signature\n\n```http\nGET /repository/setting/{settingType}/{settingName}/{subName} (settingType: string, settingName: string, subName: string) -> The setting value\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `ContentAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/setting/{settingType}/{settingName}/{subName}`","tags":["Repository · Settings"]},"post":{"operationId":"RepositoryController_setSettingHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"settingType","required":true,"in":"path","schema":{"type":"string"},"description":"Setting group.","example":"securitySettings"},{"name":"settingName","required":true,"in":"path","schema":{"type":"string"},"description":"Named setting within the group.","example":"passwordPolicy"},{"name":"subName","required":true,"in":"path","schema":{"type":"string"},"description":"Nested value within the setting.","example":"minLength"}],"responses":{"201":{"description":"The stored setting","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Set an org setting","description":"Writes an organization setting.\n\nThe body is unwrapped intelligently: send `{ \"value\": … }` and the inner value is stored; send anything else and the whole body is stored as the value. That means a payload that happens to contain a `value` key will be unwrapped whether you meant it or not.\n\n#### Signature\n\n```http\nPOST /repository/setting/{settingType}/{settingName}/{subName} (settingType: string, settingName: string, subName: string, body) -> The stored setting\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `ContentAdmin`.\n\n#### Notes\n\n- A body containing a `value` key is always unwrapped — wrap it twice if `value` is a genuine field of your setting.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/setting/{settingType}/{settingName}/{subName}`","tags":["Repository · Settings"],"requestBody":{"description":"The value to store. Wrapped in `value`, or sent bare.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"value":{"description":"When present, this inner value is stored rather than the whole body."}}},"examples":{"wrapped":{"summary":"Explicit value wrapper","value":{"value":{"minLength":12}}},"bare":{"summary":"Bare object stored as-is","value":{"minLength":12,"requireSymbol":true}}}}}}},"delete":{"operationId":"RepositoryController_deleteSettingHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"settingType","required":true,"in":"path","schema":{"type":"string"},"description":"Setting group.","example":"securitySettings"},{"name":"settingName","required":true,"in":"path","schema":{"type":"string"},"description":"Named setting. Omit to delete the whole group.","example":"passwordPolicy"},{"name":"subName","required":true,"in":"path","schema":{"type":"string"},"description":"Nested value.","example":"minLength"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete an org setting","description":"Removes an organization setting. Deleting a group rather than a named setting removes everything under it, so name the setting precisely.\n\n#### Signature\n\n```http\nDELETE /repository/setting/{settingType}/{settingName}/{subName} (settingType: string, settingName: string, subName: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `ContentAdmin`.\n\n#### Notes\n\n- Omitting `settingName` deletes the entire group.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/setting/{settingType}/{settingName}/{subName}`","tags":["Repository · Settings"]}},"/repository/create-extended":{"put":{"operationId":"RepositoryController_createPageWit","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The created record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a record with extensions","description":"Creates a record along with its related sub-records in one call — the composite form of create, for a record that is not useful on its own.\n\n#### Signature\n\n```http\nPUT /repository/create-extended (body) -> The created record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:create`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/create`","tags":["Repository"],"requestBody":{"description":"The record and its extensions.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"datatype":"sf_product","data":{"sku":"DRK-COLA-330"},"extensions":[]}}}}}},"/repository/create":{"post":{"operationId":"RepositoryController_createHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The record to create.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["datatype","data","isNew"],"properties":{"datatype":{"type":"string","description":"Collection to create in.","example":"sf_product"},"data":{"type":"object","additionalProperties":true,"description":"Domain fields for that datatype."},"isNew":{"type":"boolean","description":"Required, and must be `true`. Omit it and the call fails with 400 \"create => record is not marked as new\". The flag is named `isNew` — not `new`.","example":true}}},"example":{"datatype":"sf_product","isNew":true,"data":{"sku":"DRK-COLA-330","title":"Cola 330ml","price":12}}}}},"responses":{"200":{"description":"The result of the create operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"message":{"type":"string"}}}}}},"201":{"description":"The created record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a record","description":"Creates a record of any datatype. `datatype` names the collection and `data` carries the domain fields.\n\nThe same handler is mounted on both `POST` and `PUT` — they behave identically.\n\n#### Signature\n\n```http\nPOST /repository/create (body) -> The created record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:create`.\n\n#### Notes\n\n- `isNew: true` is mandatory. Without it the request is rejected with 400 — the record is only accepted as a creation when it says it is new.\n- Author is taken from the authenticated user, not the body.\n- Field validation depends on the datatype's schema — an unknown datatype is created without one.\n- A top-level `name` is truncated at 100 characters; the full title belongs in `data`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /repository/create`\n- `POST /repository/update/{id}`","tags":["Repository"]},"put":{"operationId":"RepositoryController_createPutHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The created record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a record","description":"Identical to `POST /repository/create` — the same handler is mounted on both verbs. Use whichever your client prefers.\n\n#### Signature\n\n```http\nPUT /repository/create (body) -> The created record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:create`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/create`","tags":["Repository"],"requestBody":{"description":"The record to create.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["datatype","data","isNew"],"properties":{"datatype":{"type":"string","example":"sf_product"},"data":{"type":"object","additionalProperties":true},"isNew":{"type":"boolean","description":"Required, and must be `true`. See `POST /repository/create`.","example":true}}},"example":{"datatype":"sf_product","isNew":true,"data":{"sku":"DRK-COLA-330","title":"Cola 330ml","price":12}}}}}}},"/repository/clone":{"put":{"operationId":"RepositoryController_cloneHandler","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"An unsaved copy of the record","content":{"application/json":{"schema":{"type":"object","description":"A platform record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Domain fields — shape depends on `datatype`."}}}}}},"400":{"description":"Clone failed — The source record does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Clone failed","path":"/repository/clone","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Clone a record","description":"Builds a copy of a record and **returns it without saving**. The clone exists only in the response — post it to `POST /repository/create` to persist it.\n\nThat makes it a template-builder rather than a duplicate operation: adjust the returned copy before creating it.\n\n#### Signature\n\n```http\nPUT /repository/clone (body) -> An unsaved copy of the record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:create`.\n\n#### Notes\n\n- **Nothing is persisted.** The clone is discarded unless you create it explicitly.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CLONE_FAILED | Clone failed | The source record does not exist. | Check `datatype` and `uid`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/create`","tags":["Repository"],"requestBody":{"description":"Which record to clone.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["datatype","uid"],"properties":{"datatype":{"type":"string","example":"sf_product"},"uid":{"type":"string","description":"Record `sk` to copy.","example":"66f1a2b3c4d5e6f708192a3b"}}},"example":{"datatype":"sf_product","uid":"66f1a2b3c4d5e6f708192a3b"}}}}}},"/repository/delete/{datatype}/{id}":{"delete":{"operationId":"RepositoryController_deleteData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"'<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal. — The datatype is `customer` or `user`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"'<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal.","path":"/repository/delete/{datatype}/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can delete a root group. Blocked: RootAdmin. — A `usergroup` or `userrole` record being deleted grants a root role, and the caller's org is not the root org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can delete a root group. Blocked: RootAdmin.","path":"/repository/delete/{datatype}/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a record","description":"Deletes one record.\n\n**`customer` and `user` are refused here.** Deleting an account has to notify the person, unwind their sessions and leave an audit trail, and a generic row delete does none of that — the account holder would find out when they next tried to sign in. The error names the domain endpoint to use instead.\n\n#### Signature\n\n```http\nDELETE /repository/delete/{datatype}/{id} (datatype: string, id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:delete`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | USE_DOMAIN_API | '<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal. | The datatype is `customer` or `user`. | Use the domain endpoint the error names — `DELETE user/customer/profile/{emailOrUsername}` or `DELETE user/user/delete/{emailOrUsername}`. The error body carries `code`, `datatype` and `endpoint`. |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can delete a root group. Blocked: RootAdmin. | A `usergroup` or `userrole` record being deleted grants a root role, and the caller's org is not the root org. | Root groups are managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/delete/{datatype}`\n- `POST /repository/trash-restore`","tags":["Repository"]}},"/repository/delete/{datatype}":{"post":{"operationId":"RepositoryController_deleteBulkData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"}],"requestBody":{"description":"The record ids to delete, as a bare array.","required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"string"},"description":"Record `sk` values."},"example":["66f1a2b3c4d5e6f708192a3b","66f1a2b3c4d5e6f708192a3c"]}}},"responses":{"201":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"'<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal. — The datatype is `customer` or `user`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"'<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal.","path":"/repository/delete/{datatype}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can delete a root group. Blocked: RootAdmin. — A `usergroup` or `userrole` record being deleted grants a root role, and the caller's org is not the root org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can delete a root group. Blocked: RootAdmin.","path":"/repository/delete/{datatype}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete several records","description":"Deletes many records of one datatype in a single call. The same `customer` / `user` guard applies as for the single delete.\n\n#### Signature\n\n```http\nPOST /repository/delete/{datatype} (datatype: string, body) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:delete`.\n\n#### Notes\n\n- The body is a bare array of ids, not an object wrapping one.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | USE_DOMAIN_API | '<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal. | The datatype is `customer` or `user`. | Use the domain endpoint the error names — `DELETE user/customer/profile/{emailOrUsername}` or `DELETE user/user/delete/{emailOrUsername}`. The error body carries `code`, `datatype` and `endpoint`. |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can delete a root group. Blocked: RootAdmin. | A `usergroup` or `userrole` record being deleted grants a root role, and the caller's org is not the root org. | Root groups are managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/delete/{datatype}/{id}`","tags":["Repository"]}},"/repository/delete-query/{datatype}":{"post":{"operationId":"RepositoryController_deleteByQuery","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"}],"responses":{"201":{"description":"{ matched, deleted, failed }","content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"integer"},"deleted":{"type":"integer"},"failed":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"example":{"matched":12,"deleted":12,"failed":[]}}}},"400":{"description":"'<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal. — The datatype is `customer` or `user`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"'<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal.","path":"/repository/delete-query/{datatype}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can delete a root group. Blocked: RootAdmin. — A `usergroup` or `userrole` record being deleted grants a root role, and the caller's org is not the root org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can delete a root group. Blocked: RootAdmin.","path":"/repository/delete-query/{datatype}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete every record a query matches","description":"The list screen's \"Select all N → Delete\": finds every record of the datatype matching `query` (a Mongo filter on the stored shape, e.g. `{ \"data.status\": \"archived\" }`) and deletes each one the same way the bulk delete does — cascades, trash, the `customer` / `user` refusal and the root-group guard. Answers with the counts.\n\n**An empty or missing `query` matches every record of the datatype** — it is then equivalent to a truncate.\n\n#### Signature\n\n```http\nPOST /repository/delete-query/{datatype} (datatype: string, body) -> { matched, deleted, failed }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:delete`.\n\n#### Notes\n\n- Send a real filter. `{}` deletes the whole collection.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | USE_DOMAIN_API | '<datatype>' cannot be deleted through the repository API — use <endpoint>, which notifies the account holder and records the removal. | The datatype is `customer` or `user`. | Use the domain endpoint the error names — `DELETE user/customer/profile/{emailOrUsername}` or `DELETE user/user/delete/{emailOrUsername}`. The error body carries `code`, `datatype` and `endpoint`. |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can delete a root group. Blocked: RootAdmin. | A `usergroup` or `userrole` record being deleted grants a root role, and the caller's org is not the root org. | Root groups are managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/delete/{datatype}`\n- `DELETE /repository/truncate/{datatype}`","tags":["Repository"],"requestBody":{"description":"The filter.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"object","additionalProperties":true}}},"example":{"query":{"data.status":"archived"}}}}}}},"/repository/truncate/{datatype}":{"delete":{"operationId":"RepositoryController_truncateCollection","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","example":"sf_product"}],"responses":{"200":{"description":"Truncation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"This datatype is removed through its own API — The datatype (e.g. customer, user) has a domain delete endpoint.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This datatype is removed through its own API","path":"/repository/truncate/{datatype}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Truncate a collection","description":"Deletes **every record** of a datatype in the organization. There is no filter and no undo.\n\nRoot administrators only, and API only: the Studio no longer offers it. Datatypes that must be removed through their own domain API (such as `customer` and `user`) are refused with `USE_DOMAIN_API`, the same rule the single and bulk deletes apply. Every call is logged with who made it.\n\n#### Signature\n\n```http\nDELETE /repository/truncate/{datatype} (datatype: string) -> Truncation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`.\n\n#### Notes\n\n- Irreversible and unfiltered — it empties the whole collection for the org.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | USE_DOMAIN_API | This datatype is removed through its own API | The datatype (e.g. customer, user) has a domain delete endpoint. | Use that endpoint instead. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/delete/{datatype}`","tags":["Repository"]}},"/repository/aggregate/{datatype}":{"post":{"operationId":"RepositoryController_aggregate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","in":"path","required":true,"description":"The collection to act on, e.g. `sf_product`, `customer`, `category`. Determines the shape of `data`.","schema":{"type":"string"},"example":"sf_product"}],"responses":{"201":{"description":"The aggregation result","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Run an aggregation","description":"Runs an aggregation pipeline over a datatype and returns the result — the escape hatch for reporting queries the list endpoints cannot express.\n\nThe body is passed to the storage engine, so it is powerful and unvalidated: an expensive pipeline runs exactly as written. Scope aggregations tightly on large collections.\n\n#### Signature\n\n```http\nPOST /repository/aggregate/{datatype} (datatype: string, body) -> The aggregation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `content:read`.\n\n#### Notes\n\n- Unvalidated and unbounded — an unscoped pipeline can scan an entire collection.\n- Results are org-scoped, but the pipeline itself is otherwise passed through as given.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/search/{datatype}`","tags":["Repository"],"requestBody":{"description":"The aggregation pipeline.","required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Pipeline stages."},"example":[{"$match":{"data.status":"active"}},{"$group":{"_id":"$data.brand","count":{"$sum":1}}}]}}}}},"/repository/file/append":{"post":{"operationId":"RepositoryController_append","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/append","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Append to a file","description":"Appends content to the end of an existing file, without reading and rewriting the whole thing.\n\n#### Signature\n\n```http\nPOST /repository/file/append (body) -> The updated file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/prepend`","tags":["Repository · Files"],"requestBody":{"description":"What to append, and where.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"},"content":{"type":"string","description":"Content to append."}}},"example":{"location":"logs/import.log","content":"row 412 imported\n"}}}}}},"/repository/file/prepend":{"post":{"operationId":"RepositoryController_prepend","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/prepend","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Prepend to a file","description":"Inserts content at the start of an existing file.\n\n#### Signature\n\n```http\nPOST /repository/file/prepend (body) -> The updated file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/append`","tags":["Repository · Files"],"requestBody":{"description":"What to prepend, and where.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"},"content":{"type":"string","description":"Content to prepend."}}},"example":{"location":"logs/import.log","content":"# import started\n"}}}}}},"/repository/file/copy":{"post":{"operationId":"RepositoryController_copy","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The copied file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/copy","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Copy a file","description":"Copies a file to another location, leaving the original in place.\n\n#### Signature\n\n```http\nPOST /repository/file/copy (body) -> The copied file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/move`","tags":["Repository · Files"],"requestBody":{"description":"Source and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"from":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"},"to":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"from":"products/cola.jpg","to":"archive/cola.jpg"}}}}}},"/repository/file/move":{"post":{"operationId":"RepositoryController_move","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The moved file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/move","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Move a file","description":"Moves a file to another location. Any URL already pointing at the old path stops resolving, so update references before moving a file that is in use.\n\n#### Signature\n\n```http\nPOST /repository/file/move (body) -> The moved file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Breaks existing links to the old path.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/copy`","tags":["Repository · Files"],"requestBody":{"description":"Source and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"from":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"},"to":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"from":"products/cola.jpg","to":"archive/cola.jpg"}}}}}},"/repository/file/delete":{"post":{"operationId":"RepositoryController_delete","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/delete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a file","description":"Deletes a file from storage. Permanent — there is no trash for files as there is for records.\n\n#### Signature\n\n```http\nPOST /repository/file/delete (body) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Irreversible. Records still referencing the file keep a URL that no longer resolves.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/exists`","tags":["Repository · Files"],"requestBody":{"description":"The file to delete.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/driver":{"get":{"operationId":"RepositoryController_driver","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The active storage driver","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get the storage driver","description":"Reports which storage backend the org uses. Useful when behaviour differs between drivers — folder semantics and signed-URL support in particular.\n\n#### Signature\n\n```http\nGET /repository/file/driver () -> The active storage driver\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Repository · Files"]}},"/repository/file/exists":{"post":{"operationId":"RepositoryController_exists","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the file exists","content":{"application/json":{"schema":{"type":"object","properties":{"exists":{"type":"boolean","example":true}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Check whether a file exists","description":"Reports whether a file is present at a location, without fetching it.\n\n#### Signature\n\n```http\nPOST /repository/file/exists (body) -> Whether the file exists\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/stat`","tags":["Repository · Files"],"requestBody":{"description":"The location to check.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file":{"post":{"operationId":"RepositoryController_getFile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The stored file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Write a file","description":"Writes file content directly, without a multipart upload — for generated content such as an exported CSV or a rendered template.\n\n#### Signature\n\n```http\nPOST /repository/file (body) -> The stored file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/append`","tags":["Repository · Files"],"requestBody":{"description":"The file to write.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"},"content":{"type":"string","description":"File content."},"metadata":{"type":"object","additionalProperties":true}}},"example":{"location":"exports/report.csv","content":"sku,title\nDRK-COLA-330,Cola 330ml"}}}}}},"/repository/file/create_favicon":{"post":{"operationId":"RepositoryController_createFavicon","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The generated favicons","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/create_favicon","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a favicon","description":"Generates `favicon.ico` and `favicon.png` at the org bucket root from a source image, and returns `{ ico: { signedUrl, path }, png: { signedUrl, path } }`.\n\nGive it a **square** source, at least 512×512, with the mark filling the frame. The generator resizes but does not crop, so a wide wordmark becomes illegible at 16×16.\n\n#### Signature\n\n```http\nPOST /repository/file/create_favicon (body) -> The generated favicons\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `location` must NOT include the org prefix. An upload returns `<org>/brand/logo.png`; pass `brand/logo.png`. Passing the full path scopes it twice and the source is not found.\n- Generating the files is not enough to change the icon a browser shows. Write the URL to the site record as `site.data.favicon`, and it MUST be a plain string — an object is silently ignored and the site keeps the platform default. (`site.data.logo` may be an object; the two are not symmetrical.)\n- Page-level `<link rel=\"icon\">` tags in page HTML are deliberately stripped by the renderer, so a page cannot set its own favicon. The site record is the only mechanism.\n- The generated files are private — an unsigned GET returns 403. Use the returned signed URLs.\n- Every generated `.ico` is the same byte length, because it is a multi-resolution container. Compare hashes, not sizes, to tell two apart.\n- Verify on the rendered page, not the record: `curl -s https://your-site/ | grep -oE '<link rel=\"icon\" href=\"[^\"]{0,80}'`. Seeing `/favicon.ico` means your value was ignored.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/thumbnails`\n- `POST /repository/file/upload`","tags":["Repository · Files"],"requestBody":{"description":"The source image, as a path WITHOUT the org prefix.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"brand/logo.png"}}}}}},"/repository/file/get_asset":{"post":{"operationId":"RepositoryController_getFileAsset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The asset","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/get_asset","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an asset file","description":"Retrieves a file as an asset record, with its metadata alongside the content.\n\n#### Signature\n\n```http\nPOST /repository/file/get_asset (body) -> The asset\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/stat`","tags":["Repository · Files"],"requestBody":{"description":"The asset to fetch.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/buffer":{"post":{"operationId":"RepositoryController_getFileBuffer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The file contents","content":{"application/json":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/buffer","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get file contents as a buffer","description":"Returns the raw bytes of a file. Use `signurl` instead for anything large — this loads the whole file into memory.\n\n#### Signature\n\n```http\nPOST /repository/file/buffer (body) -> The file contents\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Loads the entire file. Prefer a signed URL for large files.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/signurl`\n- `POST /repository/file/stream`","tags":["Repository · Files"],"requestBody":{"description":"The file to read.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/signurl":{"post":{"operationId":"RepositoryController_getSignedUrl","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The signed URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Time-limited access URL."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/signurl","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a signed URL for a file","description":"Returns a time-limited URL that grants direct access to a private file, so a browser can fetch it without the request passing through the platform.\n\nThe URL carries its own authorization — anyone holding it has access until it expires. Do not log or cache it.\n\n#### Signature\n\n```http\nPOST /repository/file/signurl (body) -> The signed URL\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The URL is a bearer credential. Treat it as a secret for its lifetime.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/make-private`","tags":["Repository · Files"],"requestBody":{"description":"The file to sign.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"},"expiresIn":{"type":"integer","description":"Lifetime in seconds.","example":3600}}},"example":{"location":"private/contract.pdf","expiresIn":3600}}}}}},"/repository/file/stat":{"post":{"operationId":"RepositoryController_getStat","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"File metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/stat","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get file metadata","description":"Returns size, content type and timestamps for a file without downloading it.\n\n#### Signature\n\n```http\nPOST /repository/file/stat (body) -> File metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/exists`","tags":["Repository · Files"],"requestBody":{"description":"The file to inspect.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/index":{"post":{"operationId":"RepositoryController_indexFileLocation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Indexing result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Index files","description":"Rebuilds the searchable index over stored files. An administrative operation — run it after a bulk import that bypassed normal upload.\n\n#### Signature\n\n```http\nPOST /repository/file/index (body) -> Indexing result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Repository · Files"],"requestBody":{"description":"What to index.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/repository/file/stream":{"post":{"operationId":"RepositoryController_getStream","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The file stream","content":{"application/json":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/stream","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Stream a file","description":"Streams a file rather than buffering it — the right choice for large files and for passing content straight through to a client.\n\n#### Signature\n\n```http\nPOST /repository/file/stream (body) -> The file stream\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/buffer`","tags":["Repository · Files"],"requestBody":{"description":"The file to stream.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/url":{"post":{"operationId":"RepositoryController_getUrl","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The file URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a file URL","description":"Returns the public URL for a file. For a private file, use `signurl` instead — a public URL will not resolve.\n\n#### Signature\n\n```http\nPOST /repository/file/url (body) -> The file URL\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/signurl`","tags":["Repository · Files"],"requestBody":{"description":"The file to resolve.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/make-private":{"post":{"operationId":"RepositoryController_makePrivate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/make-private","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Make a file private","description":"Removes public access from a file. Existing public URLs stop resolving, and access then requires a signed URL.\n\n#### Signature\n\n```http\nPOST /repository/file/make-private (body) -> The updated file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Already-issued signed URLs keep working until they expire.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/make-public`","tags":["Repository · Files"],"requestBody":{"description":"The file to restrict.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/make-public":{"post":{"operationId":"RepositoryController_makePublic","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/make-public","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Make a file public","description":"Grants public access to a file. **Anyone with the URL can then read it, with no authentication** — check the contents before making a file public.\n\n#### Signature\n\n```http\nPOST /repository/file/make-public (body) -> The updated file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Irreversible in effect once the URL has been shared, even if you make the file private again later.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/make-private`","tags":["Repository · Files"],"requestBody":{"description":"The file to publish.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/cola-330ml.jpg"}}}}}},"/repository/file/createfolder":{"post":{"operationId":"RepositoryController_createfolder","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created folder","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a folder","description":"Creates a folder in storage. Most drivers infer folders from file paths, so this is only needed where an empty folder must exist.\n\n#### Signature\n\n```http\nPOST /repository/file/createfolder (body) -> The created folder\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/flatlist`","tags":["Repository · Files"],"requestBody":{"description":"The folder to create.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"products/2026"}}}}}},"/repository/file/thumbnails":{"post":{"operationId":"RepositoryController_createThumbnails","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The generated thumbnails","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"File not found — No file exists at that location.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"File not found","path":"/repository/file/thumbnails","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate thumbnails","description":"Generates thumbnail renditions for an image.\n\n#### Signature\n\n```http\nPOST /repository/file/thumbnails (body) -> The generated thumbnails\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FILE_NOT_FOUND | File not found | No file exists at that location. | Check the path with `POST /repository/file/exists` first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/create_favicon`","tags":["Repository · Files"],"requestBody":{"description":"The image to generate thumbnails for.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"},"sizes":{"type":"array","items":{"type":"integer"},"description":"Widths to generate.","example":[200,800]}}},"example":{"location":"products/cola.jpg","sizes":[200,800]}}}}}},"/repository/file/upload":{"post":{"operationId":"RepositoryController_upload","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The stored file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Upload a file","description":"Uploads a file as multipart form data. The stored path is `location` plus the original filename.\n\n**`isPrivate` is read as the string `\"true\"`, not a boolean** — because this is a multipart form, a JSON `true` does not match and the file is stored **public**. Send the literal string.\n\n#### Signature\n\n```http\nPOST /repository/file/upload (body) -> The stored file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A boolean `true` for `isPrivate` does not work — only the string `\"true\"` makes the file private.\n- Uploading to an existing path overwrites it without warning.\n- `location` is a FOLDER, not a full path. The filename is appended for you — passing `products/chair/chair.jpg` stores `products/chair/chair.jpg/chair.jpg`.\n- The returned `path` is org-prefixed (`<org>/<location>/<file>`). Endpoints that take a `location` want the path WITHOUT that prefix.\n- Files are served as `application/octet-stream`. Browsers sniff raster formats, so PNG and JPEG render normally — **SVG does not**, and must be inlined into the page instead of linked.\n- Raise your client timeout for large files; the default in most HTTP clients is too short for a slow connection.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/upload-url`\n- `POST /repository/file/make-private`\n- `POST /repository/file/create_favicon`","tags":["Repository · Files"],"requestBody":{"description":"Multipart form: the file plus its placement.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload."},"location":{"type":"string","description":"Directory to place it in. The original filename is appended.","example":"products"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata stored with the file."},"isPrivate":{"type":"string","enum":["true","false"],"description":"Send the **string** `\"true\"` to store privately. Anything else stores it public.","example":"false"}}}}}}}},"/repository/file/upload-url":{"post":{"operationId":"RepositoryController_uploadFromUrl","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The stored file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Upload a file from a URL","description":"Fetches a file from a URL and stores it, without the client having to download and re-upload it.\n\n#### Signature\n\n```http\nPOST /repository/file/upload-url (body) -> The stored file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The server fetches the URL — it must be reachable from the server, not just from your client.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/upload`","tags":["Repository · Files"],"requestBody":{"description":"Where to fetch from and where to store it.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","description":"Source URL.","example":"https://example.com/hero.jpg"},"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"url":"https://example.com/hero.jpg","location":"products/hero.jpg"}}}}}},"/repository/file/flatlist/{prefix}/{pageNumber}":{"get":{"operationId":"RepositoryController_flatList","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"prefix","in":"path","required":true,"description":"Path prefix to list under.","schema":{"type":"string"},"example":"products"},{"name":"pageNumber","in":"path","required":true,"description":"Page number.","schema":{"type":"string"},"example":1},{"name":"check-privacy","in":"query","required":false,"description":"Also report each file's public/private state. Slower.","schema":{"type":"boolean","default":false},"example":false}],"responses":{"200":{"description":"Files under the prefix","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List files (URL form)","description":"The URL form of the flat file listing. `check-privacy` additionally reports whether each file is public or private, at the cost of extra lookups.\n\n#### Signature\n\n```http\nGET /repository/file/flatlist/{prefix}/{pageNumber} (prefix: string, pageNumber: string, check-privacy?: boolean) -> Files under the prefix\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/file/flatlist`","tags":["Repository · Files"]}},"/repository/file/flatlist":{"post":{"operationId":"RepositoryController_flatListPost","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Files under the prefix","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List files","description":"Lists files under a prefix as a flat list rather than a tree.\n\n#### Signature\n\n```http\nPOST /repository/file/flatlist (body) -> Files under the prefix\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/file/flatlist/{prefix}/{pageNumber}`","tags":["Repository · Files"],"requestBody":{"description":"What to list.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"prefix":{"type":"string","description":"Path prefix to list under.","example":"products"},"pageNumber":{"type":"integer","example":1}}},"example":{"prefix":"products","pageNumber":1}}}}}},"/repository/media/photos":{"post":{"operationId":"RepositoryController_searchPhotosFromPexel","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Matching stock photos","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search stock photos","description":"Searches a stock photo provider, so an editor can pick an image without leaving the product. Results are the provider's and are not stored until used.\n\n#### Signature\n\n```http\nPOST /repository/media/photos (body) -> Matching stock photos\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Provider licensing applies to any image you use — this endpoint does not grant rights.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/media/photos/curated`","tags":["Repository · Media"],"requestBody":{"description":"The photo search.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Search text.","example":"summer drinks"},"per_page":{"type":"integer","example":20},"page":{"type":"integer","example":1},"orientation":{"type":"string","enum":["landscape","portrait","square"],"example":"landscape"},"size":{"type":"string","example":"large"},"color":{"type":"string","example":"blue"},"locale":{"type":"string","example":"en-US"}}},"example":{"query":"summer drinks","per_page":20,"orientation":"landscape"}}}}}},"/repository/media/photos/curated":{"post":{"operationId":"RepositoryController_searchPhotosFromPexelCurated","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Curated photos","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get curated stock photos","description":"Returns the provider's curated photo selection, for a starting point when there is no search term.\n\n#### Signature\n\n```http\nPOST /repository/media/photos/curated (body) -> Curated photos\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/media/photos`","tags":["Repository · Media"],"requestBody":{"description":"Paging.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"per_page":{"type":"integer","example":20},"page":{"type":"integer","example":1}}},"example":{"per_page":20,"page":1}}}}}},"/repository/media/videos":{"post":{"operationId":"RepositoryController_searchVideosFromPexel","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Matching stock videos","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search stock videos","description":"Searches a stock video provider. The video counterpart to the photo search.\n\n#### Signature\n\n```http\nPOST /repository/media/videos (body) -> Matching stock videos\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/media/videos/popular`","tags":["Repository · Media"],"requestBody":{"description":"The video search.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"query":{"type":"string","example":"city timelapse"},"per_page":{"type":"integer","example":20},"page":{"type":"integer","example":1}}},"example":{"query":"city timelapse","per_page":20}}}}}},"/repository/media/videos/popular":{"post":{"operationId":"RepositoryController_searchVideosFromPexelPopular","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Popular videos","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get popular stock videos","description":"Returns the provider's popular video selection.\n\n#### Signature\n\n```http\nPOST /repository/media/videos/popular (body) -> Popular videos\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/media/videos`","tags":["Repository · Media"],"requestBody":{"description":"Paging.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"per_page":{"type":"integer","example":20},"page":{"type":"integer","example":1}}},"example":{"per_page":20}}}}}},"/repository/customer/file/flatlist":{"post":{"operationId":"RepositoryController_customerFlatList","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The customer's files","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List customer files","description":"Lists files in the calling customer's own storage area.\n\n#### Signature\n\n```http\nPOST /repository/customer/file/flatlist (body) -> The customer's files\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/customer/file/upload`","tags":["Repository · Files"],"requestBody":{"description":"What to list.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"prefix":{"type":"string","example":"documents"}}},"example":{"prefix":"documents"}}}}}},"/repository/customer/file/upload":{"post":{"operationId":"RepositoryController_customerUpload","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The stored file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","example":"https://cdn.appmint.io/acme/products/cola-330ml.jpg"},"path":{"type":"string","example":"products/cola-330ml.jpg"},"contentType":{"type":"string","example":"image/jpeg"},"size":{"type":"integer","description":"Bytes.","example":84213},"isPrivate":{"type":"boolean","example":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Upload a customer file","description":"Uploads a file into the calling customer's own storage area, kept separate from org files so a customer cannot reach another's uploads.\n\n#### Signature\n\n```http\nPOST /repository/customer/file/upload (body) -> The stored file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/customer/file/flatlist`","tags":["Repository · Files"],"requestBody":{"description":"Multipart form with the file.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"location":{"type":"string","example":"documents"}}}}}}}},"/repository/customer/file/upload-file":{"post":{"operationId":"RepositoryController_customerUploadFile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/repository/customer/file/delete":{"post":{"operationId":"RepositoryController_customerDelete","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a customer file","description":"Deletes a file from the calling customer's storage area.\n\n#### Signature\n\n```http\nPOST /repository/customer/file/delete (body) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/customer/file/flatlist`","tags":["Repository · Files"],"requestBody":{"description":"The file to delete.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["location"],"properties":{"location":{"type":"string","description":"Path within the org's storage.","example":"products/cola-330ml.jpg"}}},"example":{"location":"documents/contract.pdf"}}}}}},"/repository/preview/{orgId}/{site}/{page}":{"get":{"operationId":"RepositoryController_previewPage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"orgId","required":true,"in":"path","schema":{"type":"string"},"description":"Organization id, in the path rather than the header.","example":"acme-retail"},{"name":"site","in":"path","required":true,"description":"Site name.","schema":{"type":"string"},"example":"main-store"},{"name":"page","in":"path","required":true,"description":"Page name.","schema":{"type":"string"},"example":"home"}],"responses":{"200":{"description":"The rendered preview","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Preview a page","description":"Renders a preview of a site page. Note the org is a **path parameter** here rather than the `orgid` header, because a preview link has to carry everything it needs.\n\n#### Signature\n\n```http\nGET /repository/preview/{orgId}/{site}/{page} (orgId: string, site: string, page: string) -> The rendered preview\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The only repository route that takes the org from the path.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Repository"]}},"/repository/bulk-create":{"post":{"operationId":"RepositoryController_bulkCreate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The import report (`flexdata`, status `pending`) with `job`, the background job running the import","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Import records (CSV or JSON) as a background job","description":"Imports many records into one collection — the import path for a data load (pasted CSV/JSON, or a file already in storage). It answers at once with the import report (`flexdata`, `application: \"bulk-upload\"`) and `job`, the background `import` job that reads the rows in batches; follow it with `GET /jobs/{id}` or on the Jobs screen (`/jobs?id=<job sk>`). The job counts every row as created, updated, skipped or failed, with the reason for each failure.\n\n**Columns → fields.** Into an existing collection, each column goes to the field named by its `target` in `sourceCollection.data.schema.properties.<column>.target`. A column with no `target` goes to the field whose name (or title) matches its header, ignoring case, spaces and punctuation. Columns that match no field are not imported and are listed in the job's `result.skippedColumns` (and on the report as `skippedColumns`); when no column matches any field the request is refused with `400` instead of skipping every row. A stored file (`file.path`) imported into an existing collection keeps every column as it is.\n\nWith no `datatype`, a new collection is created from `sourceCollection` (name, title, schema).\n\nAccounts (`user`, `customer`) cannot be imported here — they go through the user API.\n\n#### Signature\n\n```http\nPOST /repository/bulk-create (body) -> The import report (`flexdata`, status `pending`) with `job`, the background job running the import\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Not idempotent — re-running an import duplicates the records unless `upsertKey` is given or the datatype enforces uniqueness.\n- Columns that match no field are reported in the job result as `skippedColumns`, not silently dropped.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /jobs/{id}`\n- `POST /repository/file/upload`\n- `POST /repository/export/{datatype}`\n- `POST /repository/migrate`","tags":["Repository"],"requestBody":{"description":"What to import, and where.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"format":{"type":"string","enum":["csv","json"],"description":"Format of `data`. With `file.path` it is read from the extension (.csv / .json).","example":"csv"},"data":{"description":"The rows, pasted: CSV text with a header line, or a JSON array of objects. Give this or `file`.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":true}}]},"file":{"type":"object","properties":{"path":{"type":"string","description":"Path of a CSV/JSON file in the org's storage (from `POST /repository/file/upload`)."}},"description":"A stored file to import instead of `data`."},"datatype":{"type":"string","description":"The collection to import into. Leave out to create a new collection from `sourceCollection`.","example":"ai_test_applications"},"sourceCollection":{"type":"object","description":"Describes the incoming columns. Optional when `datatype` is an existing collection whose field names match the headers.","properties":{"data":{"type":"object","properties":{"name":{"type":"string","description":"Name for a new collection (no `datatype`)."},"title":{"type":"string"},"schema":{"type":"object","description":"`properties.<column>.target` = the target field for that column (one `target` per column); `\"ignore\"` leaves a column out.","properties":{"properties":{"type":"object","additionalProperties":{"type":"object","properties":{"target":{"type":"string"}}}}}}}}}},"dryRun":{"type":"boolean","description":"Read and validate every row, write nothing, report what would happen."},"upsertKey":{"type":"string","description":"Field to match existing records on, so a re-import updates instead of duplicating."}}},"examples":{"pasted":{"summary":"Pasted CSV into an existing collection, headers = field names","value":{"format":"csv","datatype":"ai_test_applications","data":"fullName,email,department\nAda Lovelace,ada@test.local,support"}},"mapped":{"summary":"Pasted CSV with a target per column","value":{"format":"csv","datatype":"ai_test_applications","data":"Full Name,E-mail\nAda Lovelace,ada@test.local","sourceCollection":{"data":{"name":"paste","title":"Paste","schema":{"properties":{"Full Name":{"target":"fullName"},"E-mail":{"target":"email"}}}}}}},"file":{"summary":"A stored file","value":{"datatype":"sf_product","file":{"path":"imports/products.csv"}}}}}}}}},"/repository/export/{datatype}":{"post":{"operationId":"RepositoryController_exportData","summary":"Export records","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The collection to act on.","example":"sf_product"},{"name":"background","required":false,"in":"query","description":"`true`: run as a background job and answer with the job; the file is downloaded from the job (`GET /jobs/{id}` → `result.download`, or the Jobs screen `/jobs?id=<job>`).","schema":{"type":"string"},"example":"true"}],"requestBody":{"description":"What to export, and in what format.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"format":{"type":"string","enum":["csv","json"],"default":"csv","description":"Anything other than `json` is treated as `csv`.","example":"csv"},"query":{"type":"object","additionalProperties":true,"description":"Filter for the records to export."},"fields":{"type":"array","items":{"type":"string"},"description":"Columns to include."},"limit":{"type":"integer","description":"Most rows to export."},"background":{"type":"boolean","description":"Same as `?background=true`."}}},"examples":{"csv":{"summary":"CSV export of active products","value":{"format":"csv","query":{"data.status":"active"}}},"json":{"summary":"JSON export","value":{"format":"json"}}}}}},"responses":{"201":{"description":"The exported file, streamed as an attachment named `<datatype>-<date>.<format>`","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"description":"Exports a datatype as CSV or JSON, streamed as a file download. This is the export — the file is built server-side from the stored records; there is no need to read records and assemble a CSV yourself.\n\n**`?background=true` (or `background: true` in the body) runs it as a background job instead** and answers at once with the `job` record (`kind: \"export\"`). When the job finishes, its `result.download` holds a signed link to the stored file (also emailed to the requester): read it with `GET /jobs/{id}`, or open the Jobs screen (`/jobs?id=<job sk>`) where the file is downloaded. An export too large to stream is switched to a background job by itself and answers `202` with the job.\n\n**A mid-export failure still returns `200`.** Because the row count is unknown until the last page is read, the response is chunked and the headers are sent before the data — so once an export starts, there is no way to signal failure through the status code. Instead the error is written **into the file**: a CSV gains a trailing `# export failed: …` line, and a JSON export is closed off with `]`.\n\n**Always check the tail of the file** before trusting an export to be complete.\n\nCSV output begins with a UTF-8 BOM so Excel reads non-ASCII characters correctly rather than mangling them as the local codepage.\n\n#### Signature\n\n```http\nPOST /repository/export/{datatype} (datatype: string, background?: string, body) -> The exported file, streamed as an attachment named `<datatype>-<date>.<format>`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A failed export returns `200` with a truncated file — check the last line for `# export failed:` (CSV) or a bare `]` (JSON).\n- CSV output carries a UTF-8 BOM, which some strict parsers will need told about.\n- The response is chunked, so `Content-Length` is absent and progress cannot be measured.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/bulk-create`\n- `GET /jobs/{id}`","tags":["Repository"]}},"/repository/migrate":{"post":{"operationId":"RepositoryController_migrateData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The migration to run.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sources","targetDatatype"],"properties":{"sources":{"type":"array","description":"Where records come from. Several sources can feed one target.","items":{"type":"object","required":["datatype"],"properties":{"datatype":{"type":"string","description":"Source collection.","example":"legacy_product"},"query":{"type":"object","additionalProperties":true,"description":"Filter selecting which records to migrate. Omit to take everything."},"fieldMap":{"type":"object","additionalProperties":true,"description":"Maps source field names to target field names."}}}},"targetDatatype":{"type":"string","description":"Destination collection.","example":"sf_product"},"targetCollection":{"type":"object","description":"Definition for the target collection, created if it does not exist.","properties":{"name":{"type":"string"},"title":{"type":"string"},"schema":{"type":"object","additionalProperties":true}}},"mode":{"type":"string","enum":["instant","batch","auto"],"description":"`instant` runs now, `batch` queues a job, `auto` decides.","example":"auto"},"deleteFromSource":{"type":"boolean","default":false,"description":"**Destructive.** Removes records from the source after migrating them.","example":false}}},"examples":{"dryish":{"summary":"Copy without deleting","value":{"sources":[{"datatype":"legacy_product","fieldMap":{"title":"name"}}],"targetDatatype":"sf_product","mode":"auto"}},"move":{"summary":"Move and delete from source","value":{"sources":[{"datatype":"legacy_product"}],"targetDatatype":"sf_product","mode":"batch","deleteFromSource":true}}}}}},"responses":{"201":{"description":"The migration result, or a job id when batched","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Migrate data between collections","description":"Moves or copies records from one or more source collections into a target collection, optionally mapping fields on the way.\n\n`mode` controls how it runs: `instant` performs it synchronously, `batch` queues it as a job, and `auto` chooses based on volume. A batched migration returns a job id to poll.\n\n**`deleteFromSource` makes this destructive.** With it set, records are removed from the source once migrated — run without it first and check the result before repeating with deletion enabled.\n\n#### Signature\n\n```http\nPOST /repository/migrate (body) -> The migration result, or a job id when batched\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Notes\n\n- Run once without `deleteFromSource` and verify the target before running again with it.\n- A `batch` migration returns a job id — poll `GET /repository/migrate/status/{jobId}` rather than assuming completion.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/migrate/status/{jobId}`\n- `POST /repository/migrate/cancel/{jobId}`","tags":["Repository · Migration"]}},"/repository/migrate/status/{jobId}":{"get":{"operationId":"RepositoryController_getMigrationStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"jobId","required":true,"in":"path","schema":{"type":"string"},"description":"Migration job id, from the migrate response.","example":"MIG-4821"}],"responses":{"200":{"description":"The job status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get migration job status","description":"Reports progress for a batched migration — how far it has got and whether it succeeded.\n\n#### Signature\n\n```http\nGET /repository/migrate/status/{jobId} (jobId: string) -> The job status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/migrate/jobs`","tags":["Repository · Migration"]}},"/repository/migrate/jobs":{"get":{"operationId":"RepositoryController_listMigrationJobs","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by job status.","example":"running"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"Migration jobs","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List migration jobs","description":"Lists migration jobs with optional status filtering and paging — the history of what has been migrated.\n\n#### Signature\n\n```http\nGET /repository/migrate/jobs (status?: string, page?: integer, pageSize?: integer) -> Migration jobs\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/migrate/status/{jobId}`","tags":["Repository · Migration"]}},"/repository/migrate/cancel/{jobId}":{"post":{"operationId":"RepositoryController_cancelMigrationJob","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"jobId","required":true,"in":"path","schema":{"type":"string"},"description":"Migration job id.","example":"MIG-4821"}],"responses":{"201":{"description":"The cancellation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Cancel a migration job","description":"Stops a running migration.\n\nCancelling does not roll back what has already been migrated — records already written to the target stay there, and with `deleteFromSource` set, records already removed stay removed. Check the job status to see how far it got.\n\n#### Signature\n\n```http\nPOST /repository/migrate/cancel/{jobId} (jobId: string) -> The cancellation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- No rollback. A cancelled migration leaves partially-migrated data behind.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /repository/migrate/status/{jobId}`","tags":["Repository · Migration"]}},"/repository/move/plan":{"post":{"operationId":"RecordMoveController_plan","summary":"The fields of both collections (source with an example value) — to build the field rules from. Body: { from, to, ids | query }. Writes nothing.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Repository"]}},"/repository/move/preview":{"post":{"operationId":"RecordMoveController_preview","summary":"The first records exactly as they would arrive, and what dedup would do with each. Writes nothing.","description":"Body: { from, to, ids | query, fields: [{ target, from?: \"<source path>\" | value?: <fixed> }], explode?: \"<list field>\" (one record per item, as $item), dedup?: { keys: [target fields], onDuplicate: skip|update|fill|create }, mode: copy|move, dryRun? }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Repository"]}},"/repository/move":{"post":{"operationId":"RecordMoveController_start","summary":"Move or copy records from one collection to another (a background job): map fields, fixed values, transpose, dedup, copy or move","description":"Body: { from, to, ids | query, fields: [{ target, from?: \"<source path>\" | value?: <fixed> }], explode?: \"<list field>\" (one record per item, as $item), dedup?: { keys: [target fields], onDuplicate: skip|update|fill|create }, mode: copy|move, dryRun? }. Answers { jobId } — GET jobs/:id for progress and the report (created, updated, skipped, failed, errors with reasons).","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Repository"]}},"/site/get-org/{domainName}":{"get":{"operationId":"SiteController_getOrgByDomainName","summary":"Resolve a domain to an organization","description":"Maps a hostname back to the org that owns it. This is the first hop in serving a request for a custom domain — before a page can be rendered, the tenant has to be identified from the host header.\n\n#### Signature\n\n```http\nGET /site/get-org/{domainName} (domainName: string) -> The owning organization\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/get-site-by-hostname/{hostname}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"domainName","required":true,"in":"path","description":"Hostname.","schema":{"type":"string"},"example":"shop.example.com"}],"responses":{"200":{"description":"The owning organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/company/{domainName}":{"get":{"operationId":"SiteController_getPublicCompany","summary":"Get the public company profile for a domain","description":"The org behind a domain (or behind the `orgid` header when the domain segment is left off), reduced to what a site may publish about itself: `{ name, email, displayName }`. An empty object when the org has none of them — never an error. Tax id, legal name and entity type sit on the same record and are never returned.\n\n#### Signature\n\n```http\nGET /site/company/{domainName} (domainName: string) -> Public company profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/get-org/{domainName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"domainName","required":true,"in":"path","description":"Hostname or org id. Optional — without it the `orgid` header is used.","schema":{"type":"string"},"example":"shop.example.com"}],"responses":{"200":{"description":"Public company profile","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"displayName":{"type":"string"}}},"example":{"name":"acme","email":"hello@acme.com","displayName":"Acme Coffee"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/get-site/{configSiteName}/{domainName}":{"get":{"operationId":"SiteController_getSite","summary":"Get site information","description":"Fetches a site by its configured name, optionally narrowed by domain. `domainName` is an optional path segment — the route also matches without it.\n\n#### Signature\n\n```http\nGET /site/get-site/{configSiteName}/{domainName} (configSiteName: string, domainName: string) -> The site\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The fields on `site.data` that most often trip people up: `homePage` matches the home page record's **`name`**, not its slug — a page named `home` with slug `index` is NOT found by `homePage: \"index\"`, and the site serves its fallback at `/` with no error.\n- `data.favicon` must be a plain STRING url. An object is silently ignored and the site keeps the platform default — no icon link is emitted at all. `data.logo` may be an object (`{path,url}`) because it is normalised; the two fields are not symmetrical.\n- `hostName` is the platform host and always current; `domain` is the custom domain and sits behind a cache. Verify a deploy on `hostName` first — if it shows the change and the custom domain does not, that is the cache, and redeploying will not help.\n- `seo.noIndex` is the site-wide kill switch and outranks any per-page value; it is the same flag robots.txt reads.\n- Set `hideSiteHeader` and `hideSiteFooter` when your pages carry their own chrome, or the page renders two headers.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_OR_DOMAIN_REQUIRED | Either siteName or domainName is required | Neither identifier resolves to anything. | Supply a valid site name. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/get-site-by-hostname/{hostname}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"configSiteName","required":true,"in":"path","description":"Configured site name.","schema":{"type":"string"},"example":"acme-shop"},{"name":"domainName","required":true,"in":"path","description":"Optional hostname.","schema":{"type":"string"},"example":"shop.example.com"},{"name":"shared-host","required":false,"in":"query","description":"Shared host","schema":{}}],"responses":{"200":{"description":"The site","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Either siteName or domainName is required — Neither identifier resolves to anything.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Either siteName or domainName is required","path":"/site/get-site/{configSiteName}/{domainName}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/get-site-by-hostname/{hostname}":{"get":{"operationId":"SiteController_getSiteByDomainName","summary":"Get a site by hostname","description":"Resolves a hostname straight to its site configuration — the lookup a renderer does per request. The hostname segment is optional in the route, but omitting it leaves nothing to resolve.\n\n#### Signature\n\n```http\nGET /site/get-site-by-hostname/{hostname} (hostname: string) -> The site\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_OR_DOMAIN_REQUIRED | Either siteName or domainName is required | No hostname was supplied. | Pass the hostname in the path. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/get-org/{domainName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"hostname","required":true,"in":"path","schema":{"type":"string"},"description":"Hostname.","example":"shop.example.com"},{"name":"shared-host","required":false,"in":"query","description":"Shared host","schema":{}},{"name":"domainName","required":false,"in":"path","description":"Domain name","schema":{}},{"name":"configSiteName","required":true,"in":"path","description":"Site configuration name","schema":{}}],"responses":{"200":{"description":"The site","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Either siteName or domainName is required — No hostname was supplied.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Either siteName or domainName is required","path":"/site/get-site-by-hostname/{hostname}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/get-site-host-mappings/{siteName}":{"get":{"operationId":"SiteController_getSiteHostMappings","summary":"Get a site's host mappings","description":"Every hostname routed to a site — the default platform domain plus any custom domains. This is the source of truth for what actually reaches the site; a domain configured at the registrar but absent here does not resolve.\n\n#### Signature\n\n```http\nGET /site/get-site-host-mappings/{siteName} (siteName: string, keyword?: string, fields?: string) -> Host mappings\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/fix-domains`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"siteName","required":true,"in":"path","schema":{"type":"string"},"description":"Site name.","example":"acme-shop"},{"name":"keyword","required":false,"in":"query","schema":{"type":"string"},"description":"Filter mappings.","example":"example.com"},{"name":"fields","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated fields to return.","example":"domain,target"},{"name":"shared-host","required":false,"in":"query","description":"Shared host","schema":{}},{"name":"domainName","required":false,"in":"path","description":"Domain name","schema":{}},{"name":"configSiteName","required":true,"in":"path","description":"Site configuration name","schema":{}}],"responses":{"200":{"description":"Host mappings","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/base-url":{"get":{"operationId":"SiteController_getSiteBaseUrl","summary":"Get the org's public site URL","description":"The origin every customer-facing link should be built on, from the one resolver all public links use: the site's custom domain, then its platform host, then the org's own host when it has no site. `siteName` narrows it to one site; without it the org's default site answers. Build links on this rather than assembling a host on the client.\n\n#### Signature\n\n```http\nGET /site/base-url (siteName?: string) -> { url }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"siteName","required":false,"in":"query","schema":{"type":"string"},"example":"acme-shop"},{"name":"feature","required":false,"in":"query","description":"Resolve the default site’s configured form page instead of its origin.","schema":{"enum":["forms"],"type":"string"}}],"responses":{"200":{"description":"{ url }","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","nullable":true}}},"example":{"url":"https://shop.example.com"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/product-url/{productId}":{"get":{"operationId":"SiteController_getProductUrl","summary":"A product's page on the website","description":"The address a shopper opens the product at: the default site's store page, then the product's slug (else its id). `url` is null, with `reason`, when there is no site or its Storefront is off.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"productId","required":true,"in":"path","description":"Product sk, slug or sku","schema":{"type":"string"}}],"responses":{"200":{"description":"`{ url: \"https://shop.example.com/store/blue-mug\" }` or `{ url: null, reason }`"}},"tags":["Site"]}},"/site/org-sites/{siteOrgId}":{"get":{"operationId":"SiteController_getOrgSites","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"siteOrgId","required":true,"in":"path","schema":{"type":"string"},"description":"Org whose sites to list.","example":"org_4821"}],"responses":{"200":{"description":"Sites","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Could not read organization '<orgId>' — The org record could not be read — an infrastructure problem, not a client one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"Could not read organization '<orgId>'","path":"/site/org-sites/{siteOrgId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Site"],"summary":"List an organization's sites","description":"Every site belonging to an org. `siteOrgId` is a path parameter separate from the `orgid` header, which is what lets an operator list another org's sites.\n\n#### Signature\n\n```http\nGET /site/org-sites/{siteOrgId} (siteOrgId: string) -> Sites\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `503` | ORG_UNREADABLE | Could not read organization '<orgId>' | The org record could not be read — an infrastructure problem, not a client one. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/create-site`"}},"/site/attach-domain":{"post":{"operationId":"SiteController_registerSiteDomainName","summary":"Attach a domain to a site","description":"Routes a hostname to a site. DNS still has to point at the platform for the domain to resolve — attaching here creates the mapping, it does not configure the registrar.\n\n#### Signature\n\n```http\nPOST /site/attach-domain (body) -> The mapping result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /site/unregister-site-domain/{siteId}/{domainName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The domain and target site.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","domain":"shop.example.com"}}}},"responses":{"201":{"description":"The mapping result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/site/attach-domain","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/{site}/features/{feature}/link":{"post":{"operationId":"SiteController_linkFeature","summary":"Link a site feature from the footer or menu","description":"Adds a link to a feature's page (for example Gift cards → `/gift-card`) to **every page** of the site — into its `<footer>`, or with `where: \"nav\"` into its `<nav>` (else `<header>`) — styled like the links already there. `remove: true` takes it out again. The feature must be switched on in Site Features and have a page; `unsubscribe` and `gift-card` have built-in pages. Pages that already link to it, or have no footer/menu, are left alone and reported.\n\n#### Signature\n\n```http\nPOST /site/{site}/features/{feature}/link (site: string, feature: string, body) -> { href, where, label, updated, alreadyLinked, noPlace, removed } — page names in each list\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Edits the HTML of every page of the site.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SITE_NOT_FOUND | Site acme-shop not found | No site with that name in the org. | — |\n| `400` | FEATURE_OFF | Turn gift-card on in Site Features first | Linking a feature that is not enabled on the site. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"site","required":true,"in":"path","schema":{"type":"string"},"description":"Site name.","example":"acme-shop"},{"name":"feature","required":true,"in":"path","schema":{"type":"string"},"description":"Site feature key.","example":"gift-card"}],"responses":{"201":{"description":"{ href, where, label, updated, alreadyLinked, noPlace, removed } — page names in each list","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"href":"/gift-card","where":"footer","label":"Gift Cards","updated":["home","about"],"alreadyLinked":["contact"],"noPlace":[],"removed":[]}}}},"400":{"description":"Turn gift-card on in Site Features first — Linking a feature that is not enabled on the site.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Turn gift-card on in Site Features first","path":"/site/{site}/features/{feature}/link","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Site acme-shop not found — No site with that name in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Site acme-shop not found","path":"/site/{site}/features/{feature}/link","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"],"requestBody":{"description":"Where, and what to call it.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"where":{"type":"string","enum":["footer","nav"],"default":"footer"},"label":{"type":"string","description":"Defaults to the feature name in title case."},"remove":{"type":"boolean"}}},"example":{"where":"footer","label":"Gift cards"}}}}}},"/site/make-site-template":{"post":{"operationId":"SiteController_makeSiteTemplate","summary":"Register a site as a template","description":"Records an existing site in the shared org as a reusable template, so `POST /site/create-site` can name it and start from a copy of its pages.\n\nThe template is a pointer, not a snapshot: it stores which org owns the site and what it is called, and applying it reads that site live. Editing the source site updates the template.\n\n#### Signature\n\n```http\nPOST /site/make-site-template (body) -> The registered template and its stored content\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Only the shared org may register a template — the registry is a curated gallery.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | NOT_SHARED_ORG | Not allowed, invalid org | The caller is not the shared org. | Register templates from the shared org. |\n| `404` | SITE_NOT_FOUND | Site not found | No site by that name exists in the owning org. | Check `site` and `orgId`. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /site/create-site`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The site to register, and the org that owns it.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["site"],"properties":{"site":{"type":"string","description":"Site name. Lowercased.","example":"acme-shop"},"orgId":{"type":"string","description":"Org that owns the site. Defaults to the caller.","example":"acme-retail"}}},"example":{"site":"storefront-basic","orgId":"appmint"}}}},"responses":{"201":{"description":"The registered template and its stored content","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Not allowed, invalid org — The caller is not the shared org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Not allowed, invalid org","path":"/site/make-site-template","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Site not found — No site by that name exists in the owning org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Site not found","path":"/site/make-site-template","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/create-site":{"post":{"operationId":"SiteController_createSite","summary":"Create a site","description":"Provisions a new site: the site record, its default platform domain and its host mappings. Must start with a letter and contain only lowercase letters, numbers and hyphens.\n\nThe name becomes part of the default domain and is not renameable afterwards — changing it later means creating a new site and moving the domains.\n\n#### Signature\n\n```http\nPOST /site/create-site (body) -> The created site\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- The site name is fixed once created.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_SITE_NAME | Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens | The site name breaks the naming rule. | Must start with a letter and contain only lowercase letters, numbers and hyphens. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/clone-site`\n- `POST /site/add`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The site to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","title":"Acme Shop","templateName":"storefront"}}}},"responses":{"201":{"description":"The created site","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens — The site name breaks the naming rule.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens","path":"/site/create-site","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/clone-site":{"post":{"operationId":"SiteController_cloneSite","summary":"Clone a site","description":"Copies a site — content and configuration — from a source org and site to a destination. All four of `sourceOrgId`, `sourceSiteName`, `destOrgId` and `destSiteName` are required; the destination is created, not merged into.\n\n#### Signature\n\n```http\nPOST /site/clone-site (body) -> The cloned site\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Copies across orgs — check the destination org is the intended one.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | CLONE_FIELDS_REQUIRED | sourceOrgId, sourceSiteName, destOrgId, destSiteName are required | Any of the four is missing. | Supply all four. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/create-site`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Source and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceOrgId","sourceSiteName","destOrgId","destSiteName"],"properties":{"sourceOrgId":{"type":"string","example":"org_4821"},"sourceSiteName":{"type":"string","example":"acme-shop"},"destOrgId":{"type":"string","example":"org_7712"},"destSiteName":{"type":"string","example":"acme-shop-copy"}}},"example":{"sourceOrgId":"org_4821","sourceSiteName":"acme-shop","destOrgId":"org_7712","destSiteName":"acme-shop-copy"}}}},"responses":{"201":{"description":"The cloned site","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"sourceOrgId, sourceSiteName, destOrgId, destSiteName are required — Any of the four is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"sourceOrgId, sourceSiteName, destOrgId, destSiteName are required","path":"/site/clone-site","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/delete-site/{siteOrgId}/{siteId}":{"delete":{"operationId":"SiteController_deleteSiteHostMapping","summary":"Delete a site","description":"Deletes a site and its host mappings.\n\n**Known defect:** the handler declares both path parameters with the same name (`siteOrgId`), so `siteId` is never bound — the second segment is ignored and the value used for both is the first. Pass the id you intend in the **first** segment until this is fixed.\n\n#### Signature\n\n```http\nDELETE /site/delete-site/{siteOrgId}/{siteId} (siteOrgId: string, siteId: string) -> The delete result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Both path parameters are declared as `siteOrgId`; the second segment is not bound.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/remove`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"siteOrgId","required":true,"in":"path","schema":{"type":"string"},"description":"Org id — and, because of the defect below, the value used for the site id too.","example":"org_4821"},{"name":"siteId","required":true,"in":"path","description":"Site id. Currently ignored by the handler.","schema":{"type":"string"},"example":"site_77"}],"responses":{"200":{"description":"The delete result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/site/delete-site/{siteOrgId}/{siteId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/change-site-domain-names":{"post":{"operationId":"SiteController_changeSiteDomainNames","summary":"Rename site domains in bulk","description":"Renames domain mappings in bulk — the body is an **array**, each entry naming the site plus the old and new hostname. Used when a domain moves.\n\nEach rename takes the old hostname out of service the moment it is applied, so send them when DNS for the new names is already in place.\n\n#### Signature\n\n```http\nPOST /site/change-site-domain-names (body) -> Per-rename results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The body is an array, not an object.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/fix-domains`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The renames.","required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["siteName","oldName","newName"],"properties":{"siteName":{"type":"string","example":"acme-shop"},"oldName":{"type":"string","example":"old.example.com"},"newName":{"type":"string","example":"shop.example.com"}}}},"example":[{"siteName":"acme-shop","oldName":"old.example.com","newName":"shop.example.com"}]}}},"responses":{"201":{"description":"Per-rename results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/unregister-site-domain/{siteId}/{domainName}":{"delete":{"operationId":"SiteController_unregisterSiteDomainName","summary":"Unregister a site domain","description":"Removes a hostname mapping. Traffic to that hostname stops reaching the site immediately — visitors get whatever the platform serves for an unmapped host.\n\n#### Signature\n\n```http\nDELETE /site/unregister-site-domain/{siteId}/{domainName} (siteId: string, domainName: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `ContentAdmin`.\n\n#### Notes\n\n- Takes the hostname offline at once.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_ID_OR_DOMAIN_REQUIRED | Site ID or domain name is required | Either segment is empty. | Supply both. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/attach-domain`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"siteId","required":true,"in":"path","description":"Site id.","schema":{"type":"string"},"example":"site_77"},{"name":"domainName","required":true,"in":"path","description":"Hostname to remove.","schema":{"type":"string"},"example":"shop.example.com"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site ID or domain name is required — Either segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site ID or domain name is required","path":"/site/unregister-site-domain/{siteId}/{domainName}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/page/{hostName}/{siteName}/*":{"get":{"operationId":"SiteController_getPage","summary":"Render a site page by path","description":"Renders a page at an arbitrary depth — the trailing wildcard captures the whole remaining path, so `/a/b/c` resolves as one page path rather than three parameters.\n\n#### Signature\n\n```http\nGET /site/page/{hostName}/{siteName}/* (hostName: string, siteName: string, path: string) -> The rendered page payload\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/page/{hostName}/{siteName}/*`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"hostName","required":true,"in":"path","description":"Hostname being served.","schema":{"type":"string"},"example":"shop.example.com"},{"name":"siteName","required":true,"in":"path","description":"Site name.","schema":{"type":"string"},"example":"acme-shop"},{"name":"0","required":false,"in":"path","description":"Additional path parameters","schema":{"type":"string"}},{"name":"path","in":"path","required":true,"description":"Wildcard — the full remaining page path.","schema":{"type":"string"},"example":"products/cola-330"}],"responses":{"200":{"description":"The rendered page payload","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]},"post":{"operationId":"SiteController_getPagePost","summary":"Render a site page with a body","description":"The POST form of page rendering, for pages driven by submitted data — a form post or a search. Same resolution as the GET form, with the body available to the page.\n\n#### Signature\n\n```http\nPOST /site/page/{hostName}/{siteName}/* (hostName: string, siteName: string, path: string, body) -> The rendered page payload\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/page/{hostName}/{siteName}/*`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"hostName","required":true,"in":"path","description":"Hostname being served.","schema":{"type":"string"},"example":"shop.example.com"},{"name":"siteName","required":true,"in":"path","description":"Site name.","schema":{"type":"string"},"example":"acme-shop"},{"name":"0","required":false,"in":"path","description":"Additional path parameters","schema":{"type":"string"}},{"name":"path","in":"path","required":true,"description":"Wildcard — the full remaining page path.","schema":{"type":"string"},"example":"search"}],"requestBody":{"description":"Data for the page.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"q":"cola"}}}},"responses":{"201":{"description":"The rendered page payload","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/page/{hostName}/{siteName}":{"get":{"operationId":"SiteController_getPageIndex","summary":"Render a site page","description":"Renders the root page of a site for a given host. Query parameters are passed through to the page, so they reach page-level data resolution.\n\n#### Signature\n\n```http\nGET /site/page/{hostName}/{siteName} (hostName: string, siteName: string) -> The rendered page payload\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A `page` record can hold its content in four shapes, and the renderer prefers them in this order: `data.screens[]`, then `data.html`, then `data.content`, then `data.sections[]`.\n- **`data.screens` overrides `data.html`.** Any page ever saved in the visual editor carries `screens`, so later writes to `data.html` succeed with 201 and change nothing on screen — with no warning anywhere. When a deploy script takes ownership of a page, clear the other shapes in the same write: `{\"data.html\": \"…\", \"data.screens\": [], \"data.sections\": [], \"data.content\": \"\"}`.\n- Page CSS and JavaScript live in a **top-level `style` object on the page record — a sibling of `data`**, with slots `javascript`, `css`, `scriptLinks` and `styleLinks`. `data.style` is read by nothing: a payload written there is stored, returns 201 and never runs.\n- `style.javascript` is injected into the document HEAD, so it executes before the body is parsed and before the browser runtime mounts. Code there needs a readiness gate rather than `DOMContentLoaded`, which may have fired before the script was injected.\n- A `<script>` with a body inside `data.html` never executes — the HTML is parsed to a virtual DOM with `blockTextElements: { script: false }`, which discards script bodies. The element survives as an empty node. Inline event-handler attributes DO run, because attributes survive parsing.\n- `<link rel=\"icon\">` tags in page HTML are deliberately stripped so a template cannot shadow the real favicon, which is owned by the site record.\n- An unknown path renders the site fallback with a **200**, not a 404 — so a status code is not a validity check. Verify a deployed route by its `<h1>`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/page/{hostName}/{siteName}/*`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"hostName","required":true,"in":"path","description":"Hostname being served.","schema":{"type":"string"},"example":"shop.example.com"},{"name":"siteName","required":true,"in":"path","description":"Site name.","schema":{"type":"string"},"example":"acme-shop"},{"name":"0","required":false,"in":"path","description":"Additional path parameters","schema":{}}],"responses":{"200":{"description":"The rendered page payload","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/page-data/{datatype}/{dataId}":{"get":{"operationId":"SiteController_getPageData","summary":"Get page data","description":"Fetches the record backing a page — a product for a product page, a post for an article page. `dataId` is optional: omit it for the collection, supply it for one record.\n\n#### Signature\n\n```http\nGET /site/page-data/{datatype}/{dataId} (datatype: string, dataId: string) -> The page data\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/page/{hostName}/{siteName}/*`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"datatype","required":true,"in":"path","description":"DataType name.","schema":{"type":"string"},"example":"product"},{"name":"dataId","required":true,"in":"path","description":"Record id. Omit for the collection.","schema":{"type":"string"},"example":"PRD-4821"}],"responses":{"200":{"description":"The page data","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/site-map":{"post":{"operationId":"SiteController_createSiteMap","summary":"Create a site map","description":"Generates the sitemap for a site — what search engines crawl.\n\n#### Signature\n\n```http\nPOST /site/site-map (body) -> The site map\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/get-site-host-mappings/{siteName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which site to map.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop"}}}},"responses":{"201":{"description":"The site map","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/site/site-map","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/app/dsl/{name}":{"get":{"operationId":"SiteController_getAppDSL","summary":"Get an app DSL","description":"Returns the DSL definition for a named app — the declarative description a client renders from.\n\n**Public route:** it carries no authentication, so any DSL served here is readable by anyone who knows the name. Keep credentials and private endpoints out of DSL definitions.\n\n#### Signature\n\n```http\nGET /site/app/dsl/{name} (name: string) -> The DSL definition\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — treat the content as public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /site/page-data/{datatype}/{dataId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"App name.","schema":{"type":"string"},"example":"booking-widget"}],"responses":{"200":{"description":"The DSL definition","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/add":{"post":{"operationId":"SiteController_addSite","summary":"Add a site","description":"Registers a site and its host mappings. Overlaps with `create-site`; which one applies depends on whether the underlying site content already exists.\n\n#### Signature\n\n```http\nPOST /site/add (body) -> The added site\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `ContentAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_SITE_NAME | Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens | The site name breaks the naming rule. | Must start with a letter and contain only lowercase letters, numbers and hyphens. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/remove`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The site to add.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","domain":"shop.example.com"}}}},"responses":{"200":{"description":"Site successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","description":"Created site object"},"domainRecord":{"type":"array","description":"Domain registration records if domain was provided"},"message":{"type":"string","description":"Success message"}}}}}},"201":{"description":"The added site","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens — The site name breaks the naming rule.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens","path":"/site/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/remove":{"post":{"operationId":"SiteController_removeSite","summary":"Remove a site","description":"Removes a site and its host mappings. The site stops resolving on every domain routed to it — confirm which domains are affected with `GET /site/get-site-host-mappings/{siteName}` first.\n\n#### Signature\n\n```http\nPOST /site/remove (body) -> The removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Takes the site offline on all of its domains.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /site/delete-site/{siteOrgId}/{siteId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which site to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop"}}}},"responses":{"200":{"description":"Site successfully removed","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","description":"Deleted site information"},"domains":{"type":"array","description":"Domain unregistration results"},"resources":{"type":"object","description":"Resource deletion results"},"message":{"type":"string","description":"Success message"}}}}}},"201":{"description":"The removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/site/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/create":{"post":{"operationId":"SiteController_createSiteWithPlanValidation","summary":"Create a site with plan validation (legacy)","description":"Legacy create path that checks the org's plan limits before provisioning. Kept for existing callers — new integrations should use `POST /site/create-site`.\n\n#### Signature\n\n```http\nPOST /site/create (body) -> The created site\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Legacy — prefer `POST /site/create-site`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_SITE_NAME | Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens | The site name breaks the naming rule. | Must start with a letter and contain only lowercase letters, numbers and hyphens. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/create-site`\n- `GET /site/plan-limits`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The site to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","title":"Acme Shop"}}}},"responses":{"201":{"description":"The created site","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens — The site name breaks the naming rule.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid site name. Must start with a letter and contain only lowercase letters, numbers, and hyphens","path":"/site/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/limits":{"get":{"operationId":"SiteController_planLimitsView","summary":"Get organization usage statistics","description":"Returns current usage statistics and plan limits for the organization","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"app","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns organization usage statistics","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"type":"object","description":"Organization details"},"limits":{"type":"object","properties":{"maxSites":{"type":"number"},"maxDevEnvironments":{"type":"number"},"maxHostedMailDomains":{"type":"number","description":"Mail domains hosted on SpinForge Mail (other email domains are not limited)"},"allowCustomDomains":{"type":"boolean"},"planName":{"type":"string"}}},"usage":{"type":"object","properties":{"sites":{"type":"object","properties":{"current":{"type":"number"},"max":{"type":"number"}}},"devEnvironments":{"type":"object","properties":{"current":{"type":"number"},"max":{"type":"number"}}},"customDomainsAllowed":{"type":"boolean"}}}}}}}}},"tags":["Site"]}},"/site/usage-stats":{"get":{"operationId":"SiteController_getUsageStats","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Usage statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"],"summary":"Get organization usage statistics","description":"Resource usage for the org's sites — what counts against the plan limits.\n\n#### Signature\n\n```http\nGET /site/usage-stats () -> Usage statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/plan-limits`"}},"/site/plan-limits":{"get":{"operationId":"SiteController_getPlanLimits","summary":"Get organization plan limits","description":"The org's plan ceilings — site count and resource allowances. Read alongside usage stats to know how much headroom is left before a create is refused.\n\n#### Signature\n\n```http\nGET /site/plan-limits () -> Plan limits\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/usage-stats`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Plan limits","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/update-domain/{domain}":{"post":{"operationId":"SiteController_updateDomain","summary":"Update a site domain","description":"Updates a site's domain configuration from the body. The `domain` path segment is optional and is **not read by the handler** — the domain is taken from the body.\n\n#### Signature\n\n```http\nPOST /site/update-domain/{domain} (domain: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `ContentAdmin`.\n\n#### Notes\n\n- The path parameter is ignored; put the domain in the body.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/remove-domain/{domain}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Optional, and ignored — the handler reads the body.","example":"shop.example.com"},{"name":"siteName","required":true,"in":"path","description":"Site name","schema":{}}],"requestBody":{"description":"The domain configuration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","domain":"shop.example.com"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/site/update-domain/{domain}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/remove-domain/{domain}":{"post":{"operationId":"SiteController_removeDomain","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Optional, and ignored — the handler reads the body.","example":"shop.example.com"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"No domain to remove — The body names no domain, or the site has no such mapping.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"No domain to remove","path":"/site/remove-domain/{domain}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"],"summary":"Remove a site domain","description":"Removes a domain from a site. As with `update-domain`, the `domain` path segment is optional and ignored — the domain comes from the body.\n\n#### Signature\n\n```http\nPOST /site/remove-domain/{domain} (domain: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The path parameter is ignored; put the domain in the body.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | NO_DOMAIN_TO_REMOVE | No domain to remove | The body names no domain, or the site has no such mapping. | Check the mappings first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/update-domain/{domain}`","requestBody":{"description":"Which domain to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","domain":"shop.example.com"}}}}}},"/site/apply-template":{"post":{"operationId":"SiteController_applySiteTemplate","summary":"Apply a template to a site","description":"Applies a site template to an existing site. Template content overwrites the corresponding pages — this is not a merge, so a customised page matching a template page is replaced. `siteOrgId` defaults to the calling org.\n\n#### Signature\n\n```http\nPOST /site/apply-template (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `ContentAdmin`.\n\n#### Notes\n\n- Overwrites existing pages that the template also defines.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/create-site`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Site and template.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["siteName","templateName"],"properties":{"siteOrgId":{"type":"string","description":"Defaults to the `orgid` header.","example":"org_4821"},"siteName":{"type":"string","example":"acme-shop"},"templateName":{"type":"string","example":"storefront"}}},"example":{"siteName":"acme-shop","templateName":"storefront"}}}},"responses":{"200":{"description":"Template successfully applied to site","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","description":"Updated site object"},"template":{"type":"string","description":"Applied template name"},"message":{"type":"string","description":"Success message"}}}}}},"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/site/apply-template","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/site/fix-domains":{"post":{"operationId":"SiteController_fixSiteDomains","summary":"Rebuild a site's domain mappings","description":"Repair tool: **removes every existing host mapping** for a site and recreates the default and custom domain mappings from the site record, then syncs the result to Cloudflare when it is configured.\n\nThe removal happens first, so the site is briefly unreachable on all of its domains while this runs, and a mapping that exists only in the routing table and not on the site record does not come back. Capture `GET /site/get-site-host-mappings/{siteName}` before running it.\n\nThe response reports partial failure in its `errors` and `cloudflareResults` arrays while still returning 200 — check `success`, not just the status code.\n\n#### Signature\n\n```http\nPOST /site/fix-domains (body) -> What was removed, added and synced\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Destructive-then-restorative: all mappings are dropped before being rebuilt.\n- Returns 200 even on partial failure — read `success` and `errors`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /site/get-site-host-mappings/{siteName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The site to repair.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["siteName"],"properties":{"siteOrgId":{"type":"string","description":"Defaults to the `orgid` header.","example":"org_4821"},"siteName":{"type":"string","pattern":"^[a-z][a-z0-9-]*$","example":"acme-shop"}}},"example":{"siteName":"acme-shop"}}}},"responses":{"200":{"description":"What was removed, added and synced","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"site":{"type":"string"},"removedDomains":{"type":"array","items":{"type":"string"}},"addedDomains":{"type":"array","items":{"type":"string"}},"cloudflareResults":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"target":{"type":"string"},"success":{"type":"boolean"},"recordId":{"type":"string"},"error":{"type":"string"}}}},"errors":{"type":"array","items":{"type":"string"}}}},"example":{"success":true,"message":"Domains rebuilt","site":"acme-shop","removedDomains":["shop.example.com"],"addedDomains":["acme-shop.platform.io","shop.example.com"],"cloudflareResults":[{"domain":"shop.example.com","target":"edge.platform.io","success":true,"recordId":"cf_881"}],"errors":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/site/fix-domains","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site"]}},"/dev-env/create":{"post":{"operationId":"DevEnvironmentController_createDevEnvironment","summary":"Create a development environment","description":"Provisions a dev environment — a container running a copy of a site where changes can be made without touching production. Hosting and domains are attached separately after creation.\n\n#### Signature\n\n```http\nPOST /dev-env/create (body) -> The created environment\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DEV_ENV_DATA_REQUIRED | Dev environment data is required | The body is empty. | Supply the environment definition. |\n| `500` | SPINFORGE_UNCONFIGURED | SPINFORGE_PARTNER_KEY is not configured | The hosting partner key is missing from the server environment. | A deployment configuration problem — not fixable by the caller. |\n| `503` | ORG_UNREADABLE | Could not read organization '<orgId>' | The org record could not be read — an infrastructure problem, not a client one. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /dev-env/enable-hosting/{envName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The environment to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"envName":"acme-dev","siteName":"acme-shop"}}}},"responses":{"201":{"description":"The created environment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Dev environment data is required — The body is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Dev environment data is required","path":"/dev-env/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"SPINFORGE_PARTNER_KEY is not configured — The hosting partner key is missing from the server environment.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"SPINFORGE_PARTNER_KEY is not configured","path":"/dev-env/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"503":{"description":"Could not read organization '<orgId>' — The org record could not be read — an infrastructure problem, not a client one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"Could not read organization '<orgId>'","path":"/dev-env/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Site · Dev environments"]}},"/dev-env/convert/{siteName}":{"post":{"operationId":"DevEnvironmentController_convertSiteToDevEnv","summary":"Convert a site to a development environment","description":"Turns an existing site into a dev environment. The site is converted in place rather than copied — the production site becomes the dev environment, so clone it first if it needs to keep serving.\n\n#### Signature\n\n```http\nPOST /dev-env/convert/{siteName} (siteName: string, body) -> The converted environment\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Converts in place — clone the site first if production must keep running.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |\n| `400` | SITE_NAME_REQUIRED | site name is required | The path segment is empty. | Supply the site name. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /site/clone-site`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"siteName","required":true,"in":"path","description":"Site to convert.","schema":{"type":"string"},"example":"acme-shop"}],"responses":{"201":{"description":"The converted environment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"site name is required — The path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"site name is required","path":"/dev-env/convert/{siteName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Site not found <siteName>","path":"/dev-env/convert/{siteName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"],"requestBody":{"description":"Conversion options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"envName":"acme-dev"}}}}}},"/dev-env/{envName}":{"delete":{"operationId":"DevEnvironmentController_deleteDevEnvironment","summary":"Delete a development environment","description":"Destroys a dev environment and its container. Anything that lives only inside the container — uncommitted work, local data — goes with it.\n\n#### Signature\n\n```http\nDELETE /dev-env/{envName} (envName: string) -> The delete result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Container-local state is not recoverable afterwards.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /dev-env/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"200":{"description":"The delete result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/{envName}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/enable-hosting/{envName}":{"post":{"operationId":"DevEnvironmentController_enableDevEnvHosting","summary":"Enable hosting for an environment","description":"Puts a dev environment on the network so it can be reached over HTTP. Until this runs the container exists but serves nothing.\n\n#### Signature\n\n```http\nPOST /dev-env/enable-hosting/{envName} (envName: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n| `500` | SPINFORGE_UNCONFIGURED | SPINFORGE_PARTNER_KEY is not configured | The hosting partner key is missing from the server environment. | A deployment configuration problem — not fixable by the caller. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /dev-env/attach-domain/{envName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/enable-hosting/{envName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"SPINFORGE_PARTNER_KEY is not configured — The hosting partner key is missing from the server environment.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"SPINFORGE_PARTNER_KEY is not configured","path":"/dev-env/enable-hosting/{envName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Site · Dev environments"]}},"/dev-env/attach-domain/{envName}":{"post":{"operationId":"DevEnvironmentController_attachCustomDomainToDevEnv","summary":"Attach a custom domain to an environment","description":"Routes a custom hostname to a dev environment. DNS must point at the platform separately — this creates the mapping only.\n\n#### Signature\n\n```http\nPOST /dev-env/attach-domain/{envName} (envName: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n| `400` | CUSTOM_DOMAIN_REQUIRED | Custom domain is required | `domain` is missing. | Supply the hostname. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /dev-env/detach-domain/{envName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"requestBody":{"description":"The domain.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"dev.example.com"}}},"example":{"domain":"dev.example.com"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Custom domain is required — `domain` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Custom domain is required","path":"/dev-env/attach-domain/{envName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/attach-domain/{envName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/detach-domain/{envName}":{"post":{"operationId":"DevEnvironmentController_detachCustomDomainFromDevEnv","summary":"Detach a custom domain from an environment","description":"Removes a custom hostname from a dev environment; the environment stays reachable on its container domain.\n\n#### Signature\n\n```http\nPOST /dev-env/detach-domain/{envName} (envName: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n| `400` | CUSTOM_DOMAIN_REQUIRED | Custom domain is required | `domain` is missing. | Supply the hostname. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /dev-env/attach-domain/{envName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"requestBody":{"description":"The domain to detach.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"dev.example.com"}}},"example":{"domain":"dev.example.com"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Custom domain is required — `domain` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Custom domain is required","path":"/dev-env/detach-domain/{envName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/detach-domain/{envName}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/get/{envName}":{"get":{"operationId":"DevEnvironmentController_getDevEnv","summary":"Get a development environment","description":"Fetches one environment with its configuration and hosting state.\n\n#### Signature\n\n```http\nGET /dev-env/get/{envName} (envName: string) -> The environment\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n| `503` | DEV_ENVS_UNREADABLE | Could not read dev environments for organization '<orgId>' | The org's environments could not be read. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /dev-env/{envName}/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"requestBody":{"required":true,"description":"Custom domain details","content":{"application/json":{"schema":{"type":"object","properties":{"customDomain":{"type":"string","description":"Custom domain name"}},"required":["customDomain"]}}}},"responses":{"200":{"description":"The environment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/get/{envName}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Could not read dev environments for organization '<orgId>' — The org's environments could not be read.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"Could not read dev environments for organization '<orgId>'","path":"/dev-env/get/{envName}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Site · Dev environments"]}},"/dev-env/get-spinforge/{devEnvName}":{"get":{"operationId":"DevEnvironmentController_getDevEnvsAndUser","summary":"Get SpinForge details for an environment","description":"Returns the environment along with the hosting-partner (SpinForge) session detail a client needs to open it. Requires the partner key to be configured server-side.\n\n#### Signature\n\n```http\nGET /dev-env/get-spinforge/{devEnvName} (devEnvName: string) -> The environment and hosting session detail\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DEV_ENV_NAME_REQUIRED | devEnvName path parameter is required | The path segment is empty. | Supply the environment name. |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n| `500` | SPINFORGE_UNCONFIGURED | SPINFORGE_PARTNER_KEY is not configured | The hosting partner key is missing from the server environment. | A deployment configuration problem — not fixable by the caller. |\n| `502` | SPINFORGE_NO_TOKEN | SpinForge partner auth returned no token | The hosting partner authenticated but issued no token. | An upstream failure — retry, then escalate. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /dev-env/send-session-invitation`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"devEnvName","required":true,"in":"path","schema":{"type":"string"},"description":"Dev environment name.","example":"acme-dev"}],"responses":{"200":{"description":"The environment and hosting session detail","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"devEnvName path parameter is required — The path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"devEnvName path parameter is required","path":"/dev-env/get-spinforge/{devEnvName}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/get-spinforge/{devEnvName}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"SPINFORGE_PARTNER_KEY is not configured — The hosting partner key is missing from the server environment.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"SPINFORGE_PARTNER_KEY is not configured","path":"/dev-env/get-spinforge/{devEnvName}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"502":{"description":"SpinForge partner auth returned no token — The hosting partner authenticated but issued no token.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"SpinForge partner auth returned no token","path":"/dev-env/get-spinforge/{devEnvName}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Site · Dev environments"]}},"/dev-env/{envName}/status":{"get":{"operationId":"DevEnvironmentController_getContainerStatus","summary":"Get container status","description":"Whether the environment's container is running, and its current state.\n\n#### Signature\n\n```http\nGET /dev-env/{envName}/status (envName: string) -> The container status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /dev-env/{envName}/logs`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"200":{"description":"The container status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/{envName}/status","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/{envName}/logs":{"get":{"operationId":"DevEnvironmentController_getContainerLogs","summary":"Get container logs","description":"Recent log output from the environment's container — the first place to look when a dev environment misbehaves. Logs can carry whatever the running application printed, so treat the output as potentially sensitive.\n\n#### Signature\n\n```http\nGET /dev-env/{envName}/logs (envName: string) -> The container logs\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Log content is not filtered.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /dev-env/{envName}/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"200":{"description":"The container logs","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/{envName}/logs","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/{envName}/start":{"post":{"operationId":"DevEnvironmentController_startContainer","summary":"Start a container","description":"Starts the environment's container.\n\n#### Signature\n\n```http\nPOST /dev-env/{envName}/start (envName: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /dev-env/{envName}/stop`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/{envName}/start","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/{envName}/stop":{"post":{"operationId":"DevEnvironmentController_stopContainer","summary":"Stop a container","description":"Stops the environment's container. Anyone using the environment loses it immediately, and it stops serving on its domains.\n\n#### Signature\n\n```http\nPOST /dev-env/{envName}/stop (envName: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Takes the environment offline.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /dev-env/{envName}/start`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/{envName}/stop","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/{envName}/restart":{"post":{"operationId":"DevEnvironmentController_restartContainer","summary":"Restart a container","description":"Stops and starts the container. Brief downtime, and in-container process state is lost — the filesystem is kept.\n\n#### Signature\n\n```http\nPOST /dev-env/{envName}/restart (envName: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /dev-env/{envName}/rebuild`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/{envName}/restart","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/{envName}/rebuild":{"post":{"operationId":"DevEnvironmentController_rebuildContainer","summary":"Rebuild a container","description":"Rebuilds the container image and replaces the running container. Heavier than a restart: anything written inside the container that is not part of the image or a mounted volume does not survive.\n\n#### Signature\n\n```http\nPOST /dev-env/{envName}/rebuild (envName: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Discards container-local filesystem changes.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /dev-env/{envName}/restart`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"envName","required":true,"in":"path","description":"Dev environment name.","schema":{"type":"string"},"example":"acme-dev"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Dev environment <envName> not found — No dev environment has that name in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Dev environment <envName> not found","path":"/dev-env/{envName}/rebuild","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"]}},"/dev-env/send-session-invitation":{"post":{"operationId":"DevEnvironmentController_sendSessionInvitation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The send result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Email is required — `email` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Email is required","path":"/dev-env/send-session-invitation","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Site · Dev environments"],"summary":"Send a session invitation","description":"Emails someone an invitation to join a dev-environment session. This sends real mail to the address given — check it before calling.\n\n#### Signature\n\n```http\nPOST /dev-env/send-session-invitation (body) -> The send result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Sends an email — outward-facing.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | EMAIL_REQUIRED | Email is required | `email` is missing. | Supply the recipient address. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /dev-env/get-spinforge/{devEnvName}`","requestBody":{"description":"Who to invite.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","example":"dev@example.com"},"envName":{"type":"string","example":"acme-dev"}}},"example":{"email":"dev@example.com","envName":"acme-dev"}}}}}},"/chat/engage":{"post":{"operationId":"ChatController_engage","summary":"Engage a website visitor","description":"Staff only. Pushes a notice or a chat invite into one visitor's widget, by the `deviceId` it reported (from Live View). Works whether or not the sender is connected to chat. Delivered over the widget's socket; nothing is stored.\n\n#### Signature\n\n```http\nPOST /chat/engage (body) -> { success: true, messageId }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | STAFF_ONLY | Sign in as staff to engage a visitor. | The caller is not a signed-in user. | — |\n| `400` | DEVICE_REQUIRED | Say which visitor (deviceId). Their widget has not reported a device. | No deviceId. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ success: true, messageId }","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"messageId":{"type":"string"}}}}}},"400":{"description":"Say which visitor (deviceId). Their widget has not reported a device. — No deviceId.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Say which visitor (deviceId). Their widget has not reported a device.","path":"/chat/engage","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Sign in as staff to engage a visitor. — The caller is not a signed-in user.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Sign in as staff to engage a visitor.","path":"/chat/engage","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deviceId","message"],"properties":{"deviceId":{"type":"string"},"message":{"type":"string"},"kind":{"type":"string","enum":["notice","chat-invite"],"default":"chat-invite"},"title":{"type":"string"}}},"example":{"deviceId":"dev_7Kq2M9","message":"Need help choosing a size?","kind":"chat-invite"}}}}}},"/chat/ice-servers":{"get":{"operationId":"ChatController_getIceServers","summary":"Get ICE servers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"ICE server configuration","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Returns the STUN and TURN servers a WebRTC client needs to establish a voice or video connection.\n\nFetch these when opening a call rather than caching them — TURN credentials are short-lived, and a stale set is the usual cause of a call that connects on the same network but fails across NAT.\n\n#### Signature\n\n```http\nGET /chat/ice-servers () -> ICE server configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- TURN credentials expire. Do not cache the response between sessions.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /chat/live/{chatId}/{userId}`"}},"/chat/agents/online":{"get":{"operationId":"ChatController_getOnlineAgents","summary":"List online agents","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["available","busy","away"]},"example":"available"},{"name":"skill","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to agents with a skill.","example":"billing"}],"responses":{"200":{"description":"Online agents","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"The agents currently available, optionally filtered by status or skill. The read behind a routing decision — who can take this chat right now.\n\n#### Signature\n\n```http\nGET /chat/agents/online (status?: string, skill?: string) -> Online agents\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/agents/{email}/presence`"}},"/chat/agents/{email}/presence":{"get":{"operationId":"ChatController_getAgentPresence","summary":"Get an agent's presence","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Agent email address.","example":"agent@acme.com"}],"responses":{"200":{"description":"The agent's presence","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Agent not found — No agent has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Agent not found","path":"/chat/agents/{email}/presence","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"The current presence of one agent — whether they are online, their status, and how many chats they are handling.\n\n#### Signature\n\n```http\nGET /chat/agents/{email}/presence (email: string) -> The agent's presence\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Agent not found | No agent has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /chat/agents/{email}/status`"}},"/chat/customers/online":{"get":{"operationId":"ChatController_getOnlineCustomers","summary":"List online customers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Online customers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Customers currently present on the site — who could be reached with a proactive chat invitation.\n\n#### Signature\n\n```http\nGET /chat/customers/online () -> Online customers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/customers/{email}/journey`"}},"/chat/customers/{email}/journey":{"get":{"operationId":"ChatController_getCustomerJourney","summary":"Get a customer's interaction journey","description":"The customer's full interaction history across channels — what an agent should read before answering, so the customer is not asked to repeat themselves.\n\n`limit` caps how far back it goes.\n\n#### Signature\n\n```http\nGET /chat/customers/{email}/journey (email: string, limit?: integer) -> The customer journey\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/messages/{email}/{createdAfter}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Customer email.","example":"ada@example.com"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"How many interactions to return.","example":50}],"responses":{"200":{"description":"The customer journey","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/presence/stats":{"get":{"operationId":"ChatController_getPresenceStats","summary":"Get presence statistics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Presence statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Aggregate presence across the org — how many agents are online, by status. The staffing view against queue depth.\n\n#### Signature\n\n```http\nGET /chat/presence/stats () -> Presence statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/queue/stats`"}},"/chat/agents/{email}/status":{"post":{"operationId":"ChatController_setAgentStatus","summary":"Set an agent's status","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Agent email address.","example":"agent@acme.com"}],"responses":{"201":{"description":"The updated presence","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Agent not found — No agent has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Agent not found","path":"/chat/agents/{email}/status","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Sets an agent's availability. Only `available` agents receive routed chats — moving to `busy` or `away` takes them out of routing without disconnecting the chats they already hold.\n\n#### Signature\n\n```http\nPOST /chat/agents/{email}/status (email: string, body) -> The updated presence\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Existing chats are unaffected — this changes routing eligibility only.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Agent not found | No agent has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/agents/online`","requestBody":{"description":"The status to set.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["available","busy","away"],"description":"Only `available` receives new chats.","example":"busy"}}},"example":{"status":"busy"}}}}}},"/chat/queue":{"get":{"operationId":"ChatController_getQueue","summary":"Get the chat queue","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":false,"in":"query","schema":{"type":"string"},"description":"Which queue. Omit for the default.","example":"support"}],"responses":{"200":{"description":"Queued chats","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"The chats currently waiting, in the order they will be served.\n\n#### Signature\n\n```http\nGET /chat/queue (name?: string) -> Queued chats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/queue/stats`"},"post":{"operationId":"ChatController_enqueueChat","summary":"Enqueue a chat","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The queued chat, with its position","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Puts a chat into the routing queue to wait for an agent.\n\nUse `skill` to require a particular competency and `priority` to jump the line — a higher number is served sooner. `context` travels with the chat, so whatever the customer already told a bot arrives with them.\n\n#### Signature\n\n```http\nPOST /chat/queue (body) -> The queued chat, with its position\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A `skill` no online agent has leaves the chat queued indefinitely — check `GET /chat/agents/online` before requiring one.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/queue/position/{chatId}`\n- `DELETE /chat/queue/{chatId}`","requestBody":{"description":"The chat to queue.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatId","customerEmail"],"properties":{"chatId":{"type":"string","example":"CHT-4821"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"queue":{"type":"string","description":"Which queue to join. Omit for the default.","example":"support"},"skill":{"type":"string","description":"Required agent skill.","example":"billing"},"priority":{"type":"number","description":"Higher is served sooner.","example":10},"context":{"type":"object","additionalProperties":true,"description":"Carried to the agent — prior answers, cart contents, the page they were on."}}},"examples":{"basic":{"summary":"Join the default queue","value":{"chatId":"CHT-4821","customerEmail":"ada@example.com","customerName":"Ada Lovelace"}},"skilled":{"summary":"Require a skill and raise priority","value":{"chatId":"CHT-4821","customerEmail":"ada@example.com","queue":"support","skill":"billing","priority":10,"context":{"orderNumber":"A7K2M9QX4"}}}}}}}}},"/chat/queue/stats":{"get":{"operationId":"ChatController_getQueueStats","summary":"Get queue statistics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":false,"in":"query","schema":{"type":"string"},"description":"Which queue. Omit for the default.","example":"support"}],"responses":{"200":{"description":"Queue statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Depth and wait times for a queue — read alongside `presence/stats` to see whether waits are a staffing problem or a routing one.\n\n#### Signature\n\n```http\nGET /chat/queue/stats (name?: string) -> Queue statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/presence/stats`"}},"/chat/queue/position/{chatId}":{"get":{"operationId":"ChatController_getQueuePosition","summary":"Get a chat's queue position","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"chatId","required":true,"in":"path","schema":{"type":"string"},"description":"Chat session id.","example":"CHT-4821"},{"name":"name","required":false,"in":"query","schema":{"type":"string"},"description":"Which queue. Omit for the default.","example":"support"}],"responses":{"200":{"description":"The queue position","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/queue/position/{chatId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Where a waiting chat sits in the queue — what a customer-facing \"you are 3rd in line\" indicator reads.\n\n#### Signature\n\n```http\nGET /chat/queue/position/{chatId} (chatId: string, name?: string) -> The queue position\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Position moves as higher-priority chats are queued, so it can go up as well as down.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /chat/queue`"}},"/chat/queue/{chatId}":{"delete":{"operationId":"ChatController_dequeueChat","summary":"Remove a chat from the queue","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"chatId","required":true,"in":"path","schema":{"type":"string"},"description":"Chat session id.","example":"CHT-4821"},{"name":"name","required":false,"in":"query","schema":{"type":"string"},"description":"Which queue. Omit for the default.","example":"support"}],"responses":{"200":{"description":"The dequeue result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/queue/{chatId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"description":"Dequeues a waiting chat — because the customer left, or because it was answered another way. The chat session itself is not ended by this.\n\n#### Signature\n\n```http\nDELETE /chat/queue/{chatId} (chatId: string, name?: string) -> The dequeue result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /chat/queue`"}},"/chat/config/{chatId}":{"get":{"operationId":"ChatController_getChatConfig","summary":"Get chat configuration","description":"The configuration for a chat session — its routing, branding and behaviour settings.\n\n#### Signature\n\n```http\nGET /chat/config/{chatId} (chatId: string) -> The chat configuration\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /chat/sessions`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"chatId","required":true,"in":"path","description":"Chat session id.","schema":{"type":"string"},"example":"CHT-4821"}],"responses":{"200":{"description":"The chat configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/config/{chatId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/get-profile/{userId}":{"get":{"operationId":"ChatController_getUserProfile","summary":"Get a chat user profile","description":"The profile of a chat participant — who the agent is actually talking to.\n\n#### Signature\n\n```http\nGET /chat/get-profile/{userId} (userId: string) -> The user profile\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | User not found | No user has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /chat/customers/{email}/journey`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"userId","required":true,"in":"path","description":"User identifier.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"The user profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"User not found — No user has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"User not found","path":"/chat/get-profile/{userId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/sessions":{"get":{"operationId":"ChatController_activeSessions","summary":"Get active chat sessions","description":"The chat sessions currently in progress across the org — the supervisor view of what is live right now.\n\n#### Signature\n\n```http\nGET /chat/sessions () -> Active sessions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/history/{chatId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Active sessions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/upload/{chatId}/{userId}":{"post":{"operationId":"ChatController_upload","summary":"Upload files to a chat","description":"Uploads one or more files into a chat session — screenshots, documents, whatever the customer needs to show. Multipart, and several files can be sent at once.\n\n#### Signature\n\n```http\nPOST /chat/upload/{chatId}/{userId} (chatId: string, userId: string, body) -> The uploaded files\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- This route does not read the `orgid` header — unlike the rest of the controller.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /chat/live/{chatId}/{userId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"chatId","required":true,"in":"path","description":"Chat session id.","schema":{"type":"string"},"example":"CHT-4821"},{"name":"userId","required":true,"in":"path","description":"Who is uploading.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"201":{"description":"The uploaded files","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"requestBody":{"description":"Multipart form with one or more files.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"The files to upload."}}}}}}}},"/chat/live/{chatId}/{userId}":{"post":{"operationId":"ChatController_liveChat","summary":"Send a live chat message","description":"Sends a message into a live chat session.\n\nDelivery to connected clients happens over WebSocket; this is the HTTP path for a client that cannot hold a socket open, and for server-side sends.\n\n#### Signature\n\n```http\nPOST /chat/live/{chatId}/{userId} (chatId: string, userId: string, body) -> The sent message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /chat/save/{chatId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"chatId","required":true,"in":"path","description":"Chat session id.","schema":{"type":"string"},"example":"CHT-4821"},{"name":"userId","required":true,"in":"path","description":"Who is sending.","schema":{"type":"string"},"example":"agent@acme.com"}],"requestBody":{"description":"The message to send.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"text":{"type":"string","example":"Happy to help — can you confirm your order number?"}}},"example":{"text":"Happy to help — can you confirm your order number?"}}}},"responses":{"201":{"description":"The sent message","content":{"application/json":{"schema":{"type":"object","description":"A chat message.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"chatId":{"type":"string","example":"CHT-4821"},"userId":{"type":"string","example":"ada@example.com"},"text":{"type":"string","example":"Is anyone there?"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/live/{chatId}/{userId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/messages/{email}/{createdAfter}":{"get":{"operationId":"ChatController_getUserMessages","summary":"Get a user's messages","description":"Every chat message for an email address, across sessions. Supply `createdAfter` to fetch only what has arrived since a point in time — the polling path for a client without a live socket.\n\n#### Signature\n\n```http\nGET /chat/messages/{email}/{createdAfter} (email: string, createdAfter: string) -> The user's messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Omitting `createdAfter` returns the full history — always send it when polling.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/history/{chatId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"email","required":true,"in":"path","description":"User email.","schema":{"type":"string"},"example":"ada@example.com"},{"name":"createdAfter","required":true,"in":"path","schema":{"type":"string"},"description":"Return only messages after this timestamp.","example":"2026-08-30T09:00:00.000Z"}],"responses":{"200":{"description":"The user's messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A chat message.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"chatId":{"type":"string","example":"CHT-4821"},"userId":{"type":"string","example":"ada@example.com"},"text":{"type":"string","example":"Is anyone there?"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/history/{chatId}":{"get":{"operationId":"ChatController_getChatHistory","summary":"Get chat history","description":"Every message in one chat session, in order.\n\n#### Signature\n\n```http\nGET /chat/history/{chatId} (chatId: string) -> The chat history\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /chat/transcript/send`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"chatId","required":true,"in":"path","description":"Chat session id.","schema":{"type":"string"},"example":"CHT-4821"}],"responses":{"200":{"description":"The chat history","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A chat message.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"chatId":{"type":"string","example":"CHT-4821"},"userId":{"type":"string","example":"ada@example.com"},"text":{"type":"string","example":"Is anyone there?"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/history/{chatId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/save/{chatId}":{"post":{"operationId":"ChatController_saveMessage","summary":"Save a chat message","description":"Persists a message to a chat's history without sending it live — for recording messages that arrived by another route, or reconstructing a transcript.\n\n#### Signature\n\n```http\nPOST /chat/save/{chatId} (chatId: string, body) -> The saved message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Saves only — connected clients are not notified. Use `live` to actually deliver a message.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /chat/live/{chatId}/{userId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"chatId","required":true,"in":"path","description":"Chat session id.","schema":{"type":"string"},"example":"CHT-4821"}],"responses":{"201":{"description":"The saved message","content":{"application/json":{"schema":{"type":"object","description":"A chat message.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"chatId":{"type":"string","example":"CHT-4821"},"userId":{"type":"string","example":"ada@example.com"},"text":{"type":"string","example":"Is anyone there?"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/save/{chatId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"requestBody":{"description":"The message to store.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"ada@example.com","text":"Is anyone there?"}}}}}},"/chat/update/{chatId}":{"put":{"operationId":"ChatController_updateMessage","summary":"Update a chat message","description":"Edits a stored message. The transcript is what a dispute is settled on, so edit it only to correct a genuine error.\n\n#### Signature\n\n```http\nPUT /chat/update/{chatId} (chatId: string, body) -> The updated message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/history/{chatId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"chatId","required":true,"in":"path","description":"Chat session id.","schema":{"type":"string"},"example":"CHT-4821"}],"responses":{"200":{"description":"The updated message","content":{"application/json":{"schema":{"type":"object","description":"A chat message.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"chatId":{"type":"string","example":"CHT-4821"},"userId":{"type":"string","example":"ada@example.com"},"text":{"type":"string","example":"Is anyone there?"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/update/{chatId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"],"requestBody":{"description":"The message to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"messageId":"MSG-9912","text":"Corrected text"}}}}}},"/chat/transcript/send":{"post":{"operationId":"ChatController_sendTranscript","summary":"Send a chat transcript","description":"Emails the full transcript of a conversation to an address — what a customer gets after a chat ends, and what an agent forwards when escalating.\n\nThe transcript is the whole conversation. Check it contains nothing that should not leave the org before sending it to an external address.\n\n#### Signature\n\n```http\nPOST /chat/transcript/send (body) -> Dispatch result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Sends the entire conversation, including anything an agent said assuming it was internal.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Chat not found | No chat has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/history/{chatId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-authorization","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"Which chat, and where to send it.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"chatId":{"type":"string","example":"CHT-4821"},"email":{"type":"string","description":"Recipient.","example":"ada@example.com"}}},"example":{"chatId":"CHT-4821","email":"ada@example.com"}}}},"responses":{"201":{"description":"Dispatch result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Chat not found — No chat has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Chat not found","path":"/chat/transcript/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/chat/ai-active":{"get":{"operationId":"ChatController_getActiveAiChats","summary":"Check whether AI chat is active","description":"Whether the AI assistant is currently handling chats for this org — the flag a UI reads to decide whether to show \"you are talking to an assistant\".\n\n#### Signature\n\n```http\nGET /chat/ai-active () -> AI chat state\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /chat/sessions`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"AI chat state","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Chat"]}},"/profile/mailboxes":{"get":{"operationId":"UsersController_myMailboxes","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Users"]}},"/user/mailboxes":{"get":{"operationId":"UsersController_myMailboxes","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Users"]}},"/profile/system-orgs":{"get":{"operationId":"UsersController_getSystemOrgs","summary":"List system organizations","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Organizations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"The organizations visible to the caller — what a global login offers as an org picker.\n\n#### Signature\n\n```http\nGET /profile/system-orgs () -> Organizations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /global-login`"}},"/user/system-orgs":{"get":{"operationId":"UsersController_getSystemOrgs","summary":"List system organizations","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Organizations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"The organizations visible to the caller — what a global login offers as an org picker.\n\n#### Signature\n\n```http\nGET /user/system-orgs () -> Organizations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /global-login`"}},"/profile/whoami":{"get":{"operationId":"UsersController_whoAmI","summary":"Get the current user","description":"Returns the caller's own identity as the server sees it — the read a client makes on load to establish who is signed in.\n\n#### Signature\n\n```http\nGET /profile/whoami () -> The current user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /who-is`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The current user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"]}},"/user/whoami":{"get":{"operationId":"UsersController_whoAmI","summary":"Get the current user","description":"Returns the caller's own identity as the server sees it — the read a client makes on load to establish who is signed in.\n\n#### Signature\n\n```http\nGET /user/whoami () -> The current user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /who-is`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The current user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"]}},"/profile/who-is":{"get":{"operationId":"UsersController_whoIs","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}},{"name":"token","required":true,"in":"query","schema":{"type":"string"}},{"name":"value","in":"query","required":false,"description":"Identifier to resolve.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"The identified user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Identify a user","description":"Resolves who a given identifier belongs to.\n\n#### Signature\n\n```http\nGET /profile/who-is (value?: string) -> The identified user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /whoami`"}},"/user/who-is":{"get":{"operationId":"UsersController_whoIs","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}},{"name":"token","required":true,"in":"query","schema":{"type":"string"}},{"name":"value","in":"query","required":false,"description":"Identifier to resolve.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"The identified user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Identify a user","description":"Resolves who a given identifier belongs to.\n\n#### Signature\n\n```http\nGET /user/who-is (value?: string) -> The identified user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /whoami`"}},"/profile/signout":{"post":{"operationId":"UsersController_signOut","summary":"Sign out","description":"Ends the current session and invalidates its tokens.\n\n#### Signature\n\n```http\nPOST /profile/signout (body) -> Sign-out result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /logout/{userId}`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Sign-out result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"Optional session detail.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/user/signout":{"post":{"operationId":"UsersController_signOut","summary":"Sign out","description":"Ends the current session and invalidates its tokens.\n\n#### Signature\n\n```http\nPOST /user/signout (body) -> Sign-out result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /logout/{userId}`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Sign-out result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"Optional session detail.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/profile/guest/auth":{"post":{"operationId":"UsersController_guestAuth","summary":"Authenticate as a guest","description":"Issues a limited token for an unauthenticated visitor, so a storefront can act on their behalf before they have an account.\n\n#### Signature\n\n```http\nPOST /profile/guest/auth (body) -> A guest token\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Guest tokens are still credentials — scope them narrowly.\n- Requires the app's own token (Authorization: Bearer) from POST /app/attest or POST /app/key. A site widget gets it with POST /app/attest `platform: \"web\"`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | app_token_required | Guest sign-in needs this app's token. | The request has no app token for this app and org. | Sign the app in (POST /app/attest or POST /app/key) and send its token as the Bearer token. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/register`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"appKey","in":"header","description":"Application Key","required":true,"schema":{"type":"string"}},{"name":"appId","in":"header","description":"The app requesting guest access: its App ID (username) or its record id.","required":true,"schema":{"type":"string"},"example":"storefront-web"}],"requestBody":{"description":"Guest context.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}},"responses":{"201":{"description":"A guest token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"description":"Guest sign-in needs this app's token. — The request has no app token for this app and org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Guest sign-in needs this app's token.","path":"/profile/guest/auth","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/guest/auth":{"post":{"operationId":"UsersController_guestAuth","summary":"Authenticate as a guest","description":"Issues a limited token for an unauthenticated visitor, so a storefront can act on their behalf before they have an account.\n\n#### Signature\n\n```http\nPOST /user/guest/auth (body) -> A guest token\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Guest tokens are still credentials — scope them narrowly.\n- Requires the app's own token (Authorization: Bearer) from POST /app/attest or POST /app/key. A site widget gets it with POST /app/attest `platform: \"web\"`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | app_token_required | Guest sign-in needs this app's token. | The request has no app token for this app and org. | Sign the app in (POST /app/attest or POST /app/key) and send its token as the Bearer token. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/register`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"appKey","in":"header","description":"Application Key","required":true,"schema":{"type":"string"}},{"name":"appId","in":"header","description":"The app requesting guest access: its App ID (username) or its record id.","required":true,"schema":{"type":"string"},"example":"storefront-web"}],"requestBody":{"description":"Guest context.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}},"responses":{"201":{"description":"A guest token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"description":"Guest sign-in needs this app's token. — The request has no app token for this app and org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Guest sign-in needs this app's token.","path":"/user/guest/auth","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/signin":{"post":{"operationId":"UsersController_signin","summary":"Sign in","description":"Authenticates a user and issues tokens.\n\n**Without an `orgid` header** the email finds the org through the account directory: when the password matches in exactly one org the session is issued for it (with `orgName`); when it matches in several the answer is `{ requiresOrgChoice: true, orgs }` (each with `orgId`, `displayName` and a `label` to show) and the client signs in again with the chosen `orgid`.\n\n**With an `orgid` header**, a password that is wrong there but right for the same email's account at another business answers 400 `{ code: \"password_other_account\", error, accounts: [{ orgId, displayName, label, role }], orgId }` (`error` is the sentence to show) — no session is issued; the client picks that account and the person presses Sign In again. Only someone who typed that account's password gets this answer; a miss there counts toward its lock as a sign-in would.\n\nThe answer may be a step rather than a session: a second-factor challenge (`requiresTwoFactor`, `challengeToken`, `twoFactorMethod` — the code is already sent unless the method is `authenticator`), a new-device check (`isNewDevice: true`, when the org turns on new-device verification), or tokens with `requiresPasswordChange: true` after a temporary password. Otherwise it is `{ user, orgId, rootOrg, sharedOrg, token, refreshToken }`.\n\nA wrong password and an unknown account produce the **same** error, deliberately — distinguishing them would let an attacker enumerate accounts. Do not add a more helpful message on the client. (`password_other_account` above is not that: it only follows a password proven for the other account.)\n\nRepeated failures can lock the account, and a blocked device is refused before credentials are even checked.\n\n#### Signature\n\n```http\nPOST /profile/user/signin (body) -> A session, or the next step to take\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit this endpoint — the error deliberately gives an attacker nothing, but attempts are still cheap.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/refresh`\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":false,"in":"header","description":"The org to sign into. Omit it to let the email find the org (see the description).","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string"},"password":{"type":"string","format":"password"}}},"example":{"email":"ada@example.com","password":"correct horse battery staple"}}}},"responses":{"201":{"description":"A session, or the next step to take","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}},"examples":{"signedIn":{"summary":"Signed in","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","orgId":"acme","user":{"sk":"65f0c2a1e4b0a1b2c3d4e5f6","data":{"email":"ada@example.com"}}}},"secondFactor":{"summary":"Second factor required","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","message":"Verification code sent to your email"}},"newDevice":{"summary":"New device (when the org verifies new devices)","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","isNewDevice":true,"message":"New device detected. Verification code sent to your email."}},"temporaryPassword":{"summary":"Temporary password — change it now","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","requiresPasswordChange":true,"message":"Temporary password used. Please set a new password.","userId":"65f0c2a1e4b0a1b2c3d4e5f6","email":"ada@example.com"}},"chooseOrg":{"summary":"No orgid sent, several orgs match","value":{"requiresOrgChoice":true,"orgs":[{"orgId":"acme","displayName":"Acme"},{"orgId":"acme-eu","displayName":"Acme EU"}]}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/profile/user/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/profile/user/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/signin":{"post":{"operationId":"UsersController_signin","summary":"Sign in","description":"Authenticates a user and issues tokens.\n\n**Without an `orgid` header** the email finds the org through the account directory: when the password matches in exactly one org the session is issued for it (with `orgName`); when it matches in several the answer is `{ requiresOrgChoice: true, orgs }` (each with `orgId`, `displayName` and a `label` to show) and the client signs in again with the chosen `orgid`.\n\n**With an `orgid` header**, a password that is wrong there but right for the same email's account at another business answers 400 `{ code: \"password_other_account\", error, accounts: [{ orgId, displayName, label, role }], orgId }` (`error` is the sentence to show) — no session is issued; the client picks that account and the person presses Sign In again. Only someone who typed that account's password gets this answer; a miss there counts toward its lock as a sign-in would.\n\nThe answer may be a step rather than a session: a second-factor challenge (`requiresTwoFactor`, `challengeToken`, `twoFactorMethod` — the code is already sent unless the method is `authenticator`), a new-device check (`isNewDevice: true`, when the org turns on new-device verification), or tokens with `requiresPasswordChange: true` after a temporary password. Otherwise it is `{ user, orgId, rootOrg, sharedOrg, token, refreshToken }`.\n\nA wrong password and an unknown account produce the **same** error, deliberately — distinguishing them would let an attacker enumerate accounts. Do not add a more helpful message on the client. (`password_other_account` above is not that: it only follows a password proven for the other account.)\n\nRepeated failures can lock the account, and a blocked device is refused before credentials are even checked.\n\n#### Signature\n\n```http\nPOST /profile/signin (body) -> A session, or the next step to take\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit this endpoint — the error deliberately gives an attacker nothing, but attempts are still cheap.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/refresh`\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":false,"in":"header","description":"The org to sign into. Omit it to let the email find the org (see the description).","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string"},"password":{"type":"string","format":"password"}}},"example":{"email":"ada@example.com","password":"correct horse battery staple"}}}},"responses":{"201":{"description":"A session, or the next step to take","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}},"examples":{"signedIn":{"summary":"Signed in","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","orgId":"acme","user":{"sk":"65f0c2a1e4b0a1b2c3d4e5f6","data":{"email":"ada@example.com"}}}},"secondFactor":{"summary":"Second factor required","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","message":"Verification code sent to your email"}},"newDevice":{"summary":"New device (when the org verifies new devices)","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","isNewDevice":true,"message":"New device detected. Verification code sent to your email."}},"temporaryPassword":{"summary":"Temporary password — change it now","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","requiresPasswordChange":true,"message":"Temporary password used. Please set a new password.","userId":"65f0c2a1e4b0a1b2c3d4e5f6","email":"ada@example.com"}},"chooseOrg":{"summary":"No orgid sent, several orgs match","value":{"requiresOrgChoice":true,"orgs":[{"orgId":"acme","displayName":"Acme"},{"orgId":"acme-eu","displayName":"Acme EU"}]}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/profile/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/profile/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/signin":{"post":{"operationId":"UsersController_signin","summary":"Sign in","description":"Authenticates a user and issues tokens.\n\n**Without an `orgid` header** the email finds the org through the account directory: when the password matches in exactly one org the session is issued for it (with `orgName`); when it matches in several the answer is `{ requiresOrgChoice: true, orgs }` (each with `orgId`, `displayName` and a `label` to show) and the client signs in again with the chosen `orgid`.\n\n**With an `orgid` header**, a password that is wrong there but right for the same email's account at another business answers 400 `{ code: \"password_other_account\", error, accounts: [{ orgId, displayName, label, role }], orgId }` (`error` is the sentence to show) — no session is issued; the client picks that account and the person presses Sign In again. Only someone who typed that account's password gets this answer; a miss there counts toward its lock as a sign-in would.\n\nThe answer may be a step rather than a session: a second-factor challenge (`requiresTwoFactor`, `challengeToken`, `twoFactorMethod` — the code is already sent unless the method is `authenticator`), a new-device check (`isNewDevice: true`, when the org turns on new-device verification), or tokens with `requiresPasswordChange: true` after a temporary password. Otherwise it is `{ user, orgId, rootOrg, sharedOrg, token, refreshToken }`.\n\nA wrong password and an unknown account produce the **same** error, deliberately — distinguishing them would let an attacker enumerate accounts. Do not add a more helpful message on the client. (`password_other_account` above is not that: it only follows a password proven for the other account.)\n\nRepeated failures can lock the account, and a blocked device is refused before credentials are even checked.\n\n#### Signature\n\n```http\nPOST /user/user/signin (body) -> A session, or the next step to take\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit this endpoint — the error deliberately gives an attacker nothing, but attempts are still cheap.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/refresh`\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":false,"in":"header","description":"The org to sign into. Omit it to let the email find the org (see the description).","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string"},"password":{"type":"string","format":"password"}}},"example":{"email":"ada@example.com","password":"correct horse battery staple"}}}},"responses":{"201":{"description":"A session, or the next step to take","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}},"examples":{"signedIn":{"summary":"Signed in","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","orgId":"acme","user":{"sk":"65f0c2a1e4b0a1b2c3d4e5f6","data":{"email":"ada@example.com"}}}},"secondFactor":{"summary":"Second factor required","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","message":"Verification code sent to your email"}},"newDevice":{"summary":"New device (when the org verifies new devices)","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","isNewDevice":true,"message":"New device detected. Verification code sent to your email."}},"temporaryPassword":{"summary":"Temporary password — change it now","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","requiresPasswordChange":true,"message":"Temporary password used. Please set a new password.","userId":"65f0c2a1e4b0a1b2c3d4e5f6","email":"ada@example.com"}},"chooseOrg":{"summary":"No orgid sent, several orgs match","value":{"requiresOrgChoice":true,"orgs":[{"orgId":"acme","displayName":"Acme"},{"orgId":"acme-eu","displayName":"Acme EU"}]}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/user/user/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/user/user/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/signin":{"post":{"operationId":"UsersController_signin","summary":"Sign in","description":"Authenticates a user and issues tokens.\n\n**Without an `orgid` header** the email finds the org through the account directory: when the password matches in exactly one org the session is issued for it (with `orgName`); when it matches in several the answer is `{ requiresOrgChoice: true, orgs }` (each with `orgId`, `displayName` and a `label` to show) and the client signs in again with the chosen `orgid`.\n\n**With an `orgid` header**, a password that is wrong there but right for the same email's account at another business answers 400 `{ code: \"password_other_account\", error, accounts: [{ orgId, displayName, label, role }], orgId }` (`error` is the sentence to show) — no session is issued; the client picks that account and the person presses Sign In again. Only someone who typed that account's password gets this answer; a miss there counts toward its lock as a sign-in would.\n\nThe answer may be a step rather than a session: a second-factor challenge (`requiresTwoFactor`, `challengeToken`, `twoFactorMethod` — the code is already sent unless the method is `authenticator`), a new-device check (`isNewDevice: true`, when the org turns on new-device verification), or tokens with `requiresPasswordChange: true` after a temporary password. Otherwise it is `{ user, orgId, rootOrg, sharedOrg, token, refreshToken }`.\n\nA wrong password and an unknown account produce the **same** error, deliberately — distinguishing them would let an attacker enumerate accounts. Do not add a more helpful message on the client. (`password_other_account` above is not that: it only follows a password proven for the other account.)\n\nRepeated failures can lock the account, and a blocked device is refused before credentials are even checked.\n\n#### Signature\n\n```http\nPOST /user/signin (body) -> A session, or the next step to take\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit this endpoint — the error deliberately gives an attacker nothing, but attempts are still cheap.\n- Access gate: when an active requirement rule has `enforcement.access` block/override with `gatedRoles`/`gatedGroups` this person holds, and the requirement is unmet with no active override, those roles (and every role those groups grant) are withheld from the resolved grants. `user.data.readinessWithheld = { roles[], groups[], reasons[] }` says why. Root* grants are never withheld; root-org protection is unchanged.\n- Workforce Readiness: with no requirement rules this endpoint behaves exactly as before. `warn` never stops anything — it comes back as `readiness.warnings` in the response.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/refresh`\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":false,"in":"header","description":"The org to sign into. Omit it to let the email find the org (see the description).","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string"},"password":{"type":"string","format":"password"}}},"example":{"email":"ada@example.com","password":"correct horse battery staple"}}}},"responses":{"201":{"description":"A session, or the next step to take","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}},"examples":{"signedIn":{"summary":"Signed in","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","orgId":"acme","user":{"sk":"65f0c2a1e4b0a1b2c3d4e5f6","data":{"email":"ada@example.com"}}}},"secondFactor":{"summary":"Second factor required","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","message":"Verification code sent to your email"}},"newDevice":{"summary":"New device (when the org verifies new devices)","value":{"requiresTwoFactor":true,"challengeToken":"chl_9k2m4h1p7q","twoFactorMethod":"email","isNewDevice":true,"message":"New device detected. Verification code sent to your email."}},"temporaryPassword":{"summary":"Temporary password — change it now","value":{"token":"eyJhbGciOi…","refreshToken":"eyJhbGciOi…","requiresPasswordChange":true,"message":"Temporary password used. Please set a new password.","userId":"65f0c2a1e4b0a1b2c3d4e5f6","email":"ada@example.com"}},"chooseOrg":{"summary":"No orgid sent, several orgs match","value":{"requiresOrgChoice":true,"orgs":[{"orgId":"acme","displayName":"Acme"},{"orgId":"acme-eu","displayName":"Acme EU"}]}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/user/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/user/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/signin/passcode":{"post":{"operationId":"UsersController_signinPasscode","summary":"Sign in with a passcode","description":"Authenticates with a numeric passcode rather than a password — the shop-floor and shared-terminal flow, where typing a long password on a till is impractical.\n\n#### Signature\n\n```http\nPOST /profile/user/signin/passcode (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A six-digit passcode is far weaker than a password — pair it with device restrictions.\n- Passcodes are stored only as a salted scrypt hash and checked in constant time. A passcode stored in clear by an older version still signs in, and that sign-in replaces it with its hash. The passcode is never returned by any endpoint.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /passcode/set`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Passcode credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/profile/user/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/profile/user/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/signin/passcode":{"post":{"operationId":"UsersController_signinPasscode","summary":"Sign in with a passcode","description":"Authenticates with a numeric passcode rather than a password — the shop-floor and shared-terminal flow, where typing a long password on a till is impractical.\n\n#### Signature\n\n```http\nPOST /profile/signin/passcode (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A six-digit passcode is far weaker than a password — pair it with device restrictions.\n- Passcodes are stored only as a salted scrypt hash and checked in constant time. A passcode stored in clear by an older version still signs in, and that sign-in replaces it with its hash. The passcode is never returned by any endpoint.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /passcode/set`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Passcode credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/profile/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/profile/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/signin/passcode":{"post":{"operationId":"UsersController_signinPasscode","summary":"Sign in with a passcode","description":"Authenticates with a numeric passcode rather than a password — the shop-floor and shared-terminal flow, where typing a long password on a till is impractical.\n\n#### Signature\n\n```http\nPOST /user/user/signin/passcode (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A six-digit passcode is far weaker than a password — pair it with device restrictions.\n- Passcodes are stored only as a salted scrypt hash and checked in constant time. A passcode stored in clear by an older version still signs in, and that sign-in replaces it with its hash. The passcode is never returned by any endpoint.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /passcode/set`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Passcode credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/user/user/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/user/user/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/signin/passcode":{"post":{"operationId":"UsersController_signinPasscode","summary":"Sign in with a passcode","description":"Authenticates with a numeric passcode rather than a password — the shop-floor and shared-terminal flow, where typing a long password on a till is impractical.\n\n#### Signature\n\n```http\nPOST /user/signin/passcode (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A six-digit passcode is far weaker than a password — pair it with device restrictions.\n- Passcodes are stored only as a salted scrypt hash and checked in constant time. A passcode stored in clear by an older version still signs in, and that sign-in replaces it with its hash. The passcode is never returned by any endpoint.\n- Same as POST /signin/passcode: `surface: \"pos\"` applies the POS readiness gate.\n- Workforce Readiness: with no requirement rules this endpoint behaves exactly as before. `warn` never stops anything — it comes back as `readiness.warnings` in the response.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n| `423` | READINESS_BLOCK | <name> can't sign in to the POS: <requirement titles>. | A requirement rule whose `enforcement.pos` effect is block (or override-with-reason) is unmet for this person, and no override is active. | Show `message` and `reasons`. A location manager or HR can resend the same request with `override: { reasonCode, reason, expiresAt }` — it is written to the readiness ledger with the approver and expiry. The person’s own override is refused. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /passcode/set`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Passcode credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/user/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/user/signin/passcode","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"423":{"description":"<name> can't sign in to the POS: <requirement titles>. — A requirement rule whose `enforcement.pos` effect is block (or override-with-reason) is unmet for this person, and no override is active.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"reason":"readiness_block","code":"READINESS_BLOCK","gate":"pos","message":"Luis Ramirez can't clock in: Food handler card.","employeeId":"E012","employeeName":"Luis Ramirez","effect":"block","blocking":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","expiresAt":"2026-09-20T00:00:00.000Z"}],"warnings":[],"reasons":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","severity":"block"}],"canOverride":true,"override":{"how":"Send the same request again with override: { reasonCode, reason, expiresAt }.","fields":["reasonCode","reason","expiresAt"],"reasonCodes":["renewal_booked","awaiting_document","training_scheduled","business_need","not_applicable","system_error","other"],"approver":"A location manager or HR. The person’s own supervisor alone cannot approve."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/passcode/set":{"post":{"operationId":"UsersController_setPasscode","summary":"Set a passcode","description":"Sets a numeric passcode for terminal sign-in. **Must be exactly six digits** — the check is strict, so a shorter or non-numeric value is refused.\n\n#### Signature\n\n```http\nPOST /profile/passcode/set (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSCODE | Passcode must be exactly 6 digits | The passcode is not six digits. | Exactly six numeric digits. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The passcode.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Passcode must be exactly 6 digits — The passcode is not six digits.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Passcode must be exactly 6 digits","path":"/profile/passcode/set","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/passcode/set":{"post":{"operationId":"UsersController_setPasscode","summary":"Set a passcode","description":"Sets a numeric passcode for terminal sign-in. **Must be exactly six digits** — the check is strict, so a shorter or non-numeric value is refused.\n\n#### Signature\n\n```http\nPOST /profile/user/passcode/set (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSCODE | Passcode must be exactly 6 digits | The passcode is not six digits. | Exactly six numeric digits. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The passcode.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Passcode must be exactly 6 digits — The passcode is not six digits.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Passcode must be exactly 6 digits","path":"/profile/user/passcode/set","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/passcode/set":{"post":{"operationId":"UsersController_setPasscode","summary":"Set a passcode","description":"Sets a numeric passcode for terminal sign-in. **Must be exactly six digits** — the check is strict, so a shorter or non-numeric value is refused.\n\n#### Signature\n\n```http\nPOST /user/passcode/set (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSCODE | Passcode must be exactly 6 digits | The passcode is not six digits. | Exactly six numeric digits. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The passcode.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Passcode must be exactly 6 digits — The passcode is not six digits.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Passcode must be exactly 6 digits","path":"/user/passcode/set","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/passcode/set":{"post":{"operationId":"UsersController_setPasscode","summary":"Set a passcode","description":"Sets a numeric passcode for terminal sign-in. **Must be exactly six digits** — the check is strict, so a shorter or non-numeric value is refused.\n\n#### Signature\n\n```http\nPOST /user/user/passcode/set (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSCODE | Passcode must be exactly 6 digits | The passcode is not six digits. | Exactly six numeric digits. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin/passcode`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The passcode.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","passcode":"481625"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Passcode must be exactly 6 digits — The passcode is not six digits.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Passcode must be exactly 6 digits","path":"/user/user/passcode/set","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/passcode/remove":{"post":{"operationId":"UsersController_removePasscode","summary":"Remove a passcode","description":"Removes a passcode, disabling terminal sign-in for that employee. Do this as part of offboarding.\n\n#### Signature\n\n```http\nPOST /profile/passcode/remove (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /business-made/offboarding/{id}/revoke-access`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Whose passcode to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/passcode/remove":{"post":{"operationId":"UsersController_removePasscode","summary":"Remove a passcode","description":"Removes a passcode, disabling terminal sign-in for that employee. Do this as part of offboarding.\n\n#### Signature\n\n```http\nPOST /profile/user/passcode/remove (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /business-made/offboarding/{id}/revoke-access`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Whose passcode to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/passcode/remove":{"post":{"operationId":"UsersController_removePasscode","summary":"Remove a passcode","description":"Removes a passcode, disabling terminal sign-in for that employee. Do this as part of offboarding.\n\n#### Signature\n\n```http\nPOST /user/passcode/remove (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /business-made/offboarding/{id}/revoke-access`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Whose passcode to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/passcode/remove":{"post":{"operationId":"UsersController_removePasscode","summary":"Remove a passcode","description":"Removes a passcode, disabling terminal sign-in for that employee. Do this as part of offboarding.\n\n#### Signature\n\n```http\nPOST /user/user/passcode/remove (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /business-made/offboarding/{id}/revoke-access`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Whose passcode to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/passcode/card/register":{"post":{"operationId":"UsersController_registerCard","summary":"Register a passcode card","description":"Registers a physical card or fob for terminal sign-in.\n\n#### Signature\n\n```http\nPOST /profile/passcode/card/register (body) -> The registered card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","cardIdentifier":"CARD-9K2M4H"}}}},"responses":{"201":{"description":"The registered card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/passcode/card/register":{"post":{"operationId":"UsersController_registerCard","summary":"Register a passcode card","description":"Registers a physical card or fob for terminal sign-in.\n\n#### Signature\n\n```http\nPOST /profile/user/passcode/card/register (body) -> The registered card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","cardIdentifier":"CARD-9K2M4H"}}}},"responses":{"201":{"description":"The registered card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/passcode/card/register":{"post":{"operationId":"UsersController_registerCard","summary":"Register a passcode card","description":"Registers a physical card or fob for terminal sign-in.\n\n#### Signature\n\n```http\nPOST /user/passcode/card/register (body) -> The registered card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","cardIdentifier":"CARD-9K2M4H"}}}},"responses":{"201":{"description":"The registered card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/passcode/card/register":{"post":{"operationId":"UsersController_registerCard","summary":"Register a passcode card","description":"Registers a physical card or fob for terminal sign-in.\n\n#### Signature\n\n```http\nPOST /user/user/passcode/card/register (body) -> The registered card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"E-00412","cardIdentifier":"CARD-9K2M4H"}}}},"responses":{"201":{"description":"The registered card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/passcode/card/status":{"post":{"operationId":"UsersController_setCardStatus","summary":"Set a card status","description":"Enables or disables a registered card. Disabling is the immediate response to a lost card — faster and more reversible than deleting it.\n\n#### Signature\n\n```http\nPOST /profile/passcode/card/status (body) -> The updated card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/card/{identifier}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card and its new status.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"cardIdentifier":"CARD-9K2M4H","status":"disabled"}}}},"responses":{"201":{"description":"The updated card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/passcode/card/status":{"post":{"operationId":"UsersController_setCardStatus","summary":"Set a card status","description":"Enables or disables a registered card. Disabling is the immediate response to a lost card — faster and more reversible than deleting it.\n\n#### Signature\n\n```http\nPOST /profile/user/passcode/card/status (body) -> The updated card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/card/{identifier}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card and its new status.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"cardIdentifier":"CARD-9K2M4H","status":"disabled"}}}},"responses":{"201":{"description":"The updated card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/passcode/card/status":{"post":{"operationId":"UsersController_setCardStatus","summary":"Set a card status","description":"Enables or disables a registered card. Disabling is the immediate response to a lost card — faster and more reversible than deleting it.\n\n#### Signature\n\n```http\nPOST /user/passcode/card/status (body) -> The updated card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/card/{identifier}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card and its new status.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"cardIdentifier":"CARD-9K2M4H","status":"disabled"}}}},"responses":{"201":{"description":"The updated card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/passcode/card/status":{"post":{"operationId":"UsersController_setCardStatus","summary":"Set a card status","description":"Enables or disables a registered card. Disabling is the immediate response to a lost card — faster and more reversible than deleting it.\n\n#### Signature\n\n```http\nPOST /user/user/passcode/card/status (body) -> The updated card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/card/{identifier}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The card and its new status.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"cardIdentifier":"CARD-9K2M4H","status":"disabled"}}}},"responses":{"201":{"description":"The updated card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/passcode/cards/{employeeId}":{"get":{"operationId":"UsersController_listCards","summary":"List an employee's cards","description":"The cards registered to an employee. Omitting the segment lists cards more broadly.\n\n#### Signature\n\n```http\nGET /profile/passcode/cards/{employeeId} (employeeId: string) -> Registered cards\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/register`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"employeeId","required":true,"in":"path","description":"Employee id. Optional segment.","schema":{"type":"string"},"example":"E-00412"}],"responses":{"200":{"description":"Registered cards","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/passcode/cards/{employeeId}":{"get":{"operationId":"UsersController_listCards","summary":"List an employee's cards","description":"The cards registered to an employee. Omitting the segment lists cards more broadly.\n\n#### Signature\n\n```http\nGET /profile/user/passcode/cards/{employeeId} (employeeId: string) -> Registered cards\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/register`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"employeeId","required":true,"in":"path","description":"Employee id. Optional segment.","schema":{"type":"string"},"example":"E-00412"}],"responses":{"200":{"description":"Registered cards","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/passcode/cards/{employeeId}":{"get":{"operationId":"UsersController_listCards","summary":"List an employee's cards","description":"The cards registered to an employee. Omitting the segment lists cards more broadly.\n\n#### Signature\n\n```http\nGET /user/passcode/cards/{employeeId} (employeeId: string) -> Registered cards\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/register`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"employeeId","required":true,"in":"path","description":"Employee id. Optional segment.","schema":{"type":"string"},"example":"E-00412"}],"responses":{"200":{"description":"Registered cards","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/passcode/cards/{employeeId}":{"get":{"operationId":"UsersController_listCards","summary":"List an employee's cards","description":"The cards registered to an employee. Omitting the segment lists cards more broadly.\n\n#### Signature\n\n```http\nGET /user/user/passcode/cards/{employeeId} (employeeId: string) -> Registered cards\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /passcode/card/register`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"employeeId","required":true,"in":"path","description":"Employee id. Optional segment.","schema":{"type":"string"},"example":"E-00412"}],"responses":{"200":{"description":"Registered cards","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/passcode/card/{identifier}":{"get":{"operationId":"UsersController_getPasscodeCardInfo","summary":"Get card information","description":"Looks up a registered card by its identifier — what a terminal does when a card is presented.\n\n#### Signature\n\n```http\nGET /profile/passcode/card/{identifier} (identifier: string) -> The card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/cards/{employeeId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"identifier","required":true,"in":"path","description":"Card identifier.","schema":{"type":"string"},"example":"CARD-9K2M4H"}],"responses":{"200":{"description":"The card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/passcode/card/{identifier}":{"get":{"operationId":"UsersController_getPasscodeCardInfo","summary":"Get card information","description":"Looks up a registered card by its identifier — what a terminal does when a card is presented.\n\n#### Signature\n\n```http\nGET /profile/user/passcode/card/{identifier} (identifier: string) -> The card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/cards/{employeeId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"identifier","required":true,"in":"path","description":"Card identifier.","schema":{"type":"string"},"example":"CARD-9K2M4H"}],"responses":{"200":{"description":"The card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/passcode/card/{identifier}":{"get":{"operationId":"UsersController_getPasscodeCardInfo","summary":"Get card information","description":"Looks up a registered card by its identifier — what a terminal does when a card is presented.\n\n#### Signature\n\n```http\nGET /user/passcode/card/{identifier} (identifier: string) -> The card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/cards/{employeeId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"identifier","required":true,"in":"path","description":"Card identifier.","schema":{"type":"string"},"example":"CARD-9K2M4H"}],"responses":{"200":{"description":"The card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/passcode/card/{identifier}":{"get":{"operationId":"UsersController_getPasscodeCardInfo","summary":"Get card information","description":"Looks up a registered card by its identifier — what a terminal does when a card is presented.\n\n#### Signature\n\n```http\nGET /user/user/passcode/card/{identifier} (identifier: string) -> The card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /passcode/cards/{employeeId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"identifier","required":true,"in":"path","description":"Card identifier.","schema":{"type":"string"},"example":"CARD-9K2M4H"}],"responses":{"200":{"description":"The card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/employee/candidates/{userId}":{"get":{"operationId":"UsersController_employeeCandidatesForUser","summary":"Get employee candidates for a user","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"userId","required":true,"in":"path","schema":{"type":"string"},"description":"User id.","example":"USR-4821"}],"responses":{"200":{"description":"Candidate employees","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Suggests employee records that might correspond to a user account — the matching aid when linking the two.\n\n#### Signature\n\n```http\nGET /profile/user/employee/candidates/{userId} (userId: string) -> Candidate employees\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/employee/link`"}},"/user/user/employee/candidates/{userId}":{"get":{"operationId":"UsersController_employeeCandidatesForUser","summary":"Get employee candidates for a user","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"userId","required":true,"in":"path","schema":{"type":"string"},"description":"User id.","example":"USR-4821"}],"responses":{"200":{"description":"Candidate employees","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Suggests employee records that might correspond to a user account — the matching aid when linking the two.\n\n#### Signature\n\n```http\nGET /user/user/employee/candidates/{userId} (userId: string) -> Candidate employees\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/employee/link`"}},"/profile/user/employee/{employeeId}/user-candidates":{"get":{"operationId":"UsersController_userCandidatesForEmployee","summary":"Get user candidates for an employee","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"employeeId","required":true,"in":"path","schema":{"type":"string"},"description":"Employee id.","example":"EMP-4821"}],"responses":{"200":{"description":"Candidate users","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"The reverse lookup: user accounts that might correspond to an employee record.\n\n#### Signature\n\n```http\nGET /profile/user/employee/{employeeId}/user-candidates (employeeId: string) -> Candidate users\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/employee/link`"}},"/user/user/employee/{employeeId}/user-candidates":{"get":{"operationId":"UsersController_userCandidatesForEmployee","summary":"Get user candidates for an employee","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"employeeId","required":true,"in":"path","schema":{"type":"string"},"description":"Employee id.","example":"EMP-4821"}],"responses":{"200":{"description":"Candidate users","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"The reverse lookup: user accounts that might correspond to an employee record.\n\n#### Signature\n\n```http\nGET /user/user/employee/{employeeId}/user-candidates (employeeId: string) -> Candidate users\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/employee/link`"}},"/profile/user/employee/link":{"post":{"operationId":"UsersController_linkUserEmployee","summary":"Link a user to an employee","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The user and employee to link.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"USR-4821","employeeId":"EMP-4821"}}}},"responses":{"201":{"description":"The link result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Connects a login account to an HR employee record, so the same person is one identity across both.\n\n#### Signature\n\n```http\nPOST /profile/user/employee/link (body) -> The link result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /user/employee/candidates/{userId}`"}},"/user/user/employee/link":{"post":{"operationId":"UsersController_linkUserEmployee","summary":"Link a user to an employee","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The user and employee to link.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"USR-4821","employeeId":"EMP-4821"}}}},"responses":{"201":{"description":"The link result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Connects a login account to an HR employee record, so the same person is one identity across both.\n\n#### Signature\n\n```http\nPOST /user/user/employee/link (body) -> The link result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /user/employee/candidates/{userId}`"}},"/profile/user/employee/create-from-user":{"post":{"operationId":"UsersController_createEmployeeFromUser","summary":"Create an employee from a user","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The user to base it on.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"USR-4821"}}}},"responses":{"201":{"description":"The created employee","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Creates an HR employee record from an existing login account, carrying the details across.\n\n#### Signature\n\n```http\nPOST /profile/user/employee/create-from-user (body) -> The created employee\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/employee/create-from-employee`"}},"/user/user/employee/create-from-user":{"post":{"operationId":"UsersController_createEmployeeFromUser","summary":"Create an employee from a user","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The user to base it on.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"USR-4821"}}}},"responses":{"201":{"description":"The created employee","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Creates an HR employee record from an existing login account, carrying the details across.\n\n#### Signature\n\n```http\nPOST /user/user/employee/create-from-user (body) -> The created employee\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/employee/create-from-employee`"}},"/profile/user/employee/create-from-employee":{"post":{"operationId":"UsersController_createUserFromEmployee","summary":"Create a user from an employee","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The employee to base it on.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"EMP-4821"}}}},"responses":{"201":{"description":"The created user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Creates a login account for an existing employee — the step that gives a new hire access once their HR record exists.\n\n#### Signature\n\n```http\nPOST /profile/user/employee/create-from-employee (body) -> The created user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/send`"}},"/user/user/employee/create-from-employee":{"post":{"operationId":"UsersController_createUserFromEmployee","summary":"Create a user from an employee","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The employee to base it on.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"employeeId":"EMP-4821"}}}},"responses":{"201":{"description":"The created user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Creates a login account for an existing employee — the step that gives a new hire access once their HR record exists.\n\n#### Signature\n\n```http\nPOST /user/user/employee/create-from-employee (body) -> The created user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/send`"}},"/profile/user/employee/{employeeId}/customer":{"get":{"operationId":"UsersController_employeeCustomer","summary":"An employee's customer account","description":"Answers { employeeId, customer: { customerId, name, email, phone } | null, hasLogin }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"employeeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Users"]}},"/user/user/employee/{employeeId}/customer":{"get":{"operationId":"UsersController_employeeCustomer","summary":"An employee's customer account","description":"Answers { employeeId, customer: { customerId, name, email, phone } | null, hasLogin }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"employeeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Users"]}},"/profile/user/employee/customer/link":{"post":{"operationId":"UsersController_linkEmployeeCustomer","summary":"Link an employee to a customer account","description":"Body: { employeeId, customerId? }. Without customerId, the customer with the employee's email is linked, made when there is none. The customer then signs in on the site with the employee's login password, and holds no password of its own.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/user/user/employee/customer/link":{"post":{"operationId":"UsersController_linkEmployeeCustomer","summary":"Link an employee to a customer account","description":"Body: { employeeId, customerId? }. Without customerId, the customer with the employee's email is linked, made when there is none. The customer then signs in on the site with the employee's login password, and holds no password of its own.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/profile/user/employee/customer/unlink":{"post":{"operationId":"UsersController_unlinkEmployeeCustomer","summary":"Unlink an employee from their customer account","description":"Body: { employeeId }. The customer stays; it sets its own password with Forgot password.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/user/user/employee/customer/unlink":{"post":{"operationId":"UsersController_unlinkEmployeeCustomer","summary":"Unlink an employee from their customer account","description":"Body: { employeeId }. The customer stays; it sets its own password with Forgot password.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/profile/user/refresh":{"post":{"operationId":"UsersController_refreshToken","summary":"Refresh an access token","description":"Exchanges a refresh token for a new access token. The refresh token is longer-lived and therefore the more valuable credential — store it more carefully than the access token.\n\n#### Signature\n\n```http\nPOST /profile/user/refresh (body) -> New tokens\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signin`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The refresh token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"refreshToken":"eyJhbGciOi…"}}}},"responses":{"201":{"description":"New tokens","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/refresh":{"post":{"operationId":"UsersController_refreshToken","summary":"Refresh token","description":"Refreshes an authentication token","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Refresh token details","content":{"application/json":{"schema":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","description":"Refresh token"}}}}}},"responses":{"200":{"description":"Token successfully refreshed"}},"tags":["Users"]}},"/user/user/refresh":{"post":{"operationId":"UsersController_refreshToken","summary":"Refresh an access token","description":"Exchanges a refresh token for a new access token. The refresh token is longer-lived and therefore the more valuable credential — store it more carefully than the access token.\n\n#### Signature\n\n```http\nPOST /user/user/refresh (body) -> New tokens\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signin`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The refresh token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"refreshToken":"eyJhbGciOi…"}}}},"responses":{"201":{"description":"New tokens","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/refresh":{"post":{"operationId":"UsersController_refreshToken","summary":"Refresh token","description":"Refreshes an authentication token","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Refresh token details","content":{"application/json":{"schema":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","description":"Refresh token"}}}}}},"responses":{"200":{"description":"Token successfully refreshed"}},"tags":["Users"]}},"/profile/user/meta":{"post":{"operationId":"UsersController_updateMyMeta","summary":"Update my metadata","description":"Writes arbitrary metadata against the caller's account, namespaced so different features do not collide. `mode` chooses whether the value merges into what is there or replaces it outright.\n\n#### Signature\n\n```http\nPOST /profile/user/meta (body) -> The updated metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `mode: \"replace\"` discards everything else in the namespace.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAMESPACE_REQUIRED | A valid meta namespace is required | `namespace` is missing or invalid. | Namespaces keep features from overwriting each other. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/{userId}/meta`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The metadata to write.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","value"],"properties":{"namespace":{"type":"string","description":"Namespace to write under.","example":"preferences"},"value":{"type":"object","additionalProperties":true,"description":"Must be an object."},"mode":{"type":"string","enum":["merge","replace"],"default":"merge","example":"merge"}}},"example":{"namespace":"preferences","value":{"theme":"dark"},"mode":"merge"}}}},"responses":{"201":{"description":"The updated metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid meta namespace is required — `namespace` is missing or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid meta namespace is required","path":"/profile/user/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"]}},"/profile/meta":{"post":{"operationId":"UsersController_updateMyMeta","summary":"Update my metadata","description":"Writes arbitrary metadata against the caller's account, namespaced so different features do not collide. `mode` chooses whether the value merges into what is there or replaces it outright.\n\n#### Signature\n\n```http\nPOST /profile/meta (body) -> The updated metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `mode: \"replace\"` discards everything else in the namespace.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAMESPACE_REQUIRED | A valid meta namespace is required | `namespace` is missing or invalid. | Namespaces keep features from overwriting each other. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/{userId}/meta`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The metadata to write.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","value"],"properties":{"namespace":{"type":"string","description":"Namespace to write under.","example":"preferences"},"value":{"type":"object","additionalProperties":true,"description":"Must be an object."},"mode":{"type":"string","enum":["merge","replace"],"default":"merge","example":"merge"}}},"example":{"namespace":"preferences","value":{"theme":"dark"},"mode":"merge"}}}},"responses":{"201":{"description":"The updated metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid meta namespace is required — `namespace` is missing or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid meta namespace is required","path":"/profile/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"]}},"/user/user/meta":{"post":{"operationId":"UsersController_updateMyMeta","summary":"Update my metadata","description":"Writes arbitrary metadata against the caller's account, namespaced so different features do not collide. `mode` chooses whether the value merges into what is there or replaces it outright.\n\n#### Signature\n\n```http\nPOST /user/user/meta (body) -> The updated metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `mode: \"replace\"` discards everything else in the namespace.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAMESPACE_REQUIRED | A valid meta namespace is required | `namespace` is missing or invalid. | Namespaces keep features from overwriting each other. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/{userId}/meta`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The metadata to write.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","value"],"properties":{"namespace":{"type":"string","description":"Namespace to write under.","example":"preferences"},"value":{"type":"object","additionalProperties":true,"description":"Must be an object."},"mode":{"type":"string","enum":["merge","replace"],"default":"merge","example":"merge"}}},"example":{"namespace":"preferences","value":{"theme":"dark"},"mode":"merge"}}}},"responses":{"201":{"description":"The updated metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid meta namespace is required — `namespace` is missing or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid meta namespace is required","path":"/user/user/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"]}},"/user/meta":{"post":{"operationId":"UsersController_updateMyMeta","summary":"Update my metadata","description":"Writes arbitrary metadata against the caller's account, namespaced so different features do not collide. `mode` chooses whether the value merges into what is there or replaces it outright.\n\n#### Signature\n\n```http\nPOST /user/meta (body) -> The updated metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `mode: \"replace\"` discards everything else in the namespace.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAMESPACE_REQUIRED | A valid meta namespace is required | `namespace` is missing or invalid. | Namespaces keep features from overwriting each other. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/{userId}/meta`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The metadata to write.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","value"],"properties":{"namespace":{"type":"string","description":"Namespace to write under.","example":"preferences"},"value":{"type":"object","additionalProperties":true,"description":"Must be an object."},"mode":{"type":"string","enum":["merge","replace"],"default":"merge","example":"merge"}}},"example":{"namespace":"preferences","value":{"theme":"dark"},"mode":"merge"}}}},"responses":{"201":{"description":"The updated metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid meta namespace is required — `namespace` is missing or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid meta namespace is required","path":"/user/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"]}},"/profile/user/{userId}/meta":{"post":{"operationId":"UsersController_updateUserMetaAsAdmin","summary":"Update another user's metadata","description":"Writes metadata against another user's account. Admin-only, unlike the self-service form.\n\n#### Signature\n\n```http\nPOST /profile/user/{userId}/meta (userId: string, body) -> The updated metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | ADMIN_ONLY | Only an admin can <action> | The caller lacks the admin rights the action requires. | The message names the action that was refused. |\n| `400` | USER_ID_REQUIRED | User id required | The user id is missing. | Supply it in the path. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /meta`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"userId","required":true,"in":"path","description":"User id.","schema":{"type":"string"},"example":"USR-4821"}],"responses":{"201":{"description":"The updated metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"User id required — The user id is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User id required","path":"/profile/user/{userId}/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only an admin can <action> — The caller lacks the admin rights the action requires.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only an admin can <action>","path":"/profile/user/{userId}/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"The metadata to write.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","value"],"properties":{"namespace":{"type":"string","example":"preferences"},"value":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["merge","replace"],"example":"merge"}}},"example":{"namespace":"preferences","value":{"theme":"dark"}}}}}}},"/user/user/{userId}/meta":{"post":{"operationId":"UsersController_updateUserMetaAsAdmin","summary":"Update another user's metadata","description":"Writes metadata against another user's account. Admin-only, unlike the self-service form.\n\n#### Signature\n\n```http\nPOST /user/user/{userId}/meta (userId: string, body) -> The updated metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | ADMIN_ONLY | Only an admin can <action> | The caller lacks the admin rights the action requires. | The message names the action that was refused. |\n| `400` | USER_ID_REQUIRED | User id required | The user id is missing. | Supply it in the path. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /meta`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"userId","required":true,"in":"path","description":"User id.","schema":{"type":"string"},"example":"USR-4821"}],"responses":{"201":{"description":"The updated metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"User id required — The user id is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User id required","path":"/user/user/{userId}/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only an admin can <action> — The caller lacks the admin rights the action requires.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only an admin can <action>","path":"/user/user/{userId}/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"The metadata to write.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","value"],"properties":{"namespace":{"type":"string","example":"preferences"},"value":{"type":"object","additionalProperties":true},"mode":{"type":"string","enum":["merge","replace"],"example":"merge"}}},"example":{"namespace":"preferences","value":{"theme":"dark"}}}}}}},"/profile/signup":{"post":{"operationId":"UsersController_signup","summary":"Add a staff user","description":"Creates a staff user in the organization (Admin › Users › Add User). Staff only: shoppers use `POST /customer/signup`. `password` is optional; left out, the account gets a random password nobody knows (invite them or set one later). Given, it is whatever the administrator chose — the org password policy is not applied to it — and must equal `confirmPassword` when that is sent. The person's own later changes and resets still meet their policy. `requirePasswordChange: true` makes it a temporary password: signing in with it answers `requiresPasswordChange` and the person sets their own before anything else. The answer never carries a password, hash or token.\n\n#### Signature\n\n```http\nPOST /profile/signup (body) -> The created user (no credential fields)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The error confirms whether an address is registered, unlike sign-in. That is an enumeration surface — rate-limit it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PASSWORD_MISMATCH | The two passwords do not match. | `confirmPassword` differs from `password`. | — |\n| `409` | USER_EXISTS | A user with this email already exists. Set their password from their profile instead. | A password was given for an email that already has an account. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin`\n- `POST /user/invite/send`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The account to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace","groups":["User"],"password":"…","confirmPassword":"…","requirePasswordChange":true}}}},"responses":{"201":{"description":"The created user (no credential fields)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The two passwords do not match. — `confirmPassword` differs from `password`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The two passwords do not match.","path":"/profile/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"A user with this email already exists. Set their password from their profile instead. — A password was given for an email that already has an account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A user with this email already exists. Set their password from their profile instead.","path":"/profile/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/signup":{"post":{"operationId":"UsersController_signup","summary":"Add a staff user","description":"Creates a staff user in the organization (Admin › Users › Add User). Staff only: shoppers use `POST /customer/signup`. `password` is optional; left out, the account gets a random password nobody knows (invite them or set one later). Given, it is whatever the administrator chose — the org password policy is not applied to it — and must equal `confirmPassword` when that is sent. The person's own later changes and resets still meet their policy. `requirePasswordChange: true` makes it a temporary password: signing in with it answers `requiresPasswordChange` and the person sets their own before anything else. The answer never carries a password, hash or token.\n\n#### Signature\n\n```http\nPOST /profile/user/signup (body) -> The created user (no credential fields)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The error confirms whether an address is registered, unlike sign-in. That is an enumeration surface — rate-limit it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PASSWORD_MISMATCH | The two passwords do not match. | `confirmPassword` differs from `password`. | — |\n| `409` | USER_EXISTS | A user with this email already exists. Set their password from their profile instead. | A password was given for an email that already has an account. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin`\n- `POST /user/invite/send`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The account to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace","groups":["User"],"password":"…","confirmPassword":"…","requirePasswordChange":true}}}},"responses":{"201":{"description":"The created user (no credential fields)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The two passwords do not match. — `confirmPassword` differs from `password`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The two passwords do not match.","path":"/profile/user/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"A user with this email already exists. Set their password from their profile instead. — A password was given for an email that already has an account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A user with this email already exists. Set their password from their profile instead.","path":"/profile/user/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/signup":{"post":{"operationId":"UsersController_signup","summary":"Add a staff user","description":"Creates a staff user in the organization (Admin › Users › Add User). Staff only: shoppers use `POST /customer/signup`. `password` is optional; left out, the account gets a random password nobody knows (invite them or set one later). Given, it is whatever the administrator chose — the org password policy is not applied to it — and must equal `confirmPassword` when that is sent. The person's own later changes and resets still meet their policy. `requirePasswordChange: true` makes it a temporary password: signing in with it answers `requiresPasswordChange` and the person sets their own before anything else. The answer never carries a password, hash or token.\n\n#### Signature\n\n```http\nPOST /user/signup (body) -> The created user (no credential fields)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The error confirms whether an address is registered, unlike sign-in. That is an enumeration surface — rate-limit it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PASSWORD_MISMATCH | The two passwords do not match. | `confirmPassword` differs from `password`. | — |\n| `409` | USER_EXISTS | A user with this email already exists. Set their password from their profile instead. | A password was given for an email that already has an account. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin`\n- `POST /user/invite/send`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The account to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace","groups":["User"],"password":"…","confirmPassword":"…","requirePasswordChange":true}}}},"responses":{"201":{"description":"The created user (no credential fields)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The two passwords do not match. — `confirmPassword` differs from `password`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The two passwords do not match.","path":"/user/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"A user with this email already exists. Set their password from their profile instead. — A password was given for an email that already has an account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A user with this email already exists. Set their password from their profile instead.","path":"/user/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/signup":{"post":{"operationId":"UsersController_signup","summary":"Add a staff user","description":"Creates a staff user in the organization (Admin › Users › Add User). Staff only: shoppers use `POST /customer/signup`. `password` is optional; left out, the account gets a random password nobody knows (invite them or set one later). Given, it is whatever the administrator chose — the org password policy is not applied to it — and must equal `confirmPassword` when that is sent. The person's own later changes and resets still meet their policy. `requirePasswordChange: true` makes it a temporary password: signing in with it answers `requiresPasswordChange` and the person sets their own before anything else. The answer never carries a password, hash or token.\n\n#### Signature\n\n```http\nPOST /user/user/signup (body) -> The created user (no credential fields)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The error confirms whether an address is registered, unlike sign-in. That is an enumeration surface — rate-limit it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PASSWORD_MISMATCH | The two passwords do not match. | `confirmPassword` differs from `password`. | — |\n| `409` | USER_EXISTS | A user with this email already exists. Set their password from their profile instead. | A password was given for an email that already has an account. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /signin`\n- `POST /user/invite/send`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The account to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace","groups":["User"],"password":"…","confirmPassword":"…","requirePasswordChange":true}}}},"responses":{"201":{"description":"The created user (no credential fields)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The two passwords do not match. — `confirmPassword` differs from `password`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The two passwords do not match.","path":"/user/user/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"A user with this email already exists. Set their password from their profile instead. — A password was given for an email that already has an account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A user with this email already exists. Set their password from their profile instead.","path":"/user/user/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/logout/{userId}":{"get":{"operationId":"UsersController_logout","summary":"Log a user out","description":"Ends a user's session by id. Note this is a `GET` that changes state, so it can be triggered by anything following a link.\n\n#### Signature\n\n```http\nGET /profile/logout/{userId} (userId: string) -> Logout result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- State change on `GET` — do not place behind a prefetchable link.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signout`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"userId","required":true,"in":"path","description":"User id or email.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"Logout result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/logout/{userId}":{"get":{"operationId":"UsersController_logout","summary":"Log a user out","description":"Ends a user's session by id. Note this is a `GET` that changes state, so it can be triggered by anything following a link.\n\n#### Signature\n\n```http\nGET /profile/user/logout/{userId} (userId: string) -> Logout result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- State change on `GET` — do not place behind a prefetchable link.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signout`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"userId","required":true,"in":"path","description":"User id or email.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"Logout result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/logout/{userId}":{"get":{"operationId":"UsersController_logout","summary":"Log a user out","description":"Ends a user's session by id. Note this is a `GET` that changes state, so it can be triggered by anything following a link.\n\n#### Signature\n\n```http\nGET /user/logout/{userId} (userId: string) -> Logout result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- State change on `GET` — do not place behind a prefetchable link.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signout`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"userId","required":true,"in":"path","description":"User id or email.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"Logout result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/logout/{userId}":{"get":{"operationId":"UsersController_logout","summary":"Log a user out","description":"Ends a user's session by id. Note this is a `GET` that changes state, so it can be triggered by anything following a link.\n\n#### Signature\n\n```http\nGET /user/user/logout/{userId} (userId: string) -> Logout result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- State change on `GET` — do not place behind a prefetchable link.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signout`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"userId","required":true,"in":"path","description":"User id or email.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"Logout result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/password/change":{"post":{"operationId":"UsersController_passwordChange","summary":"Change a password","description":"Any signed-in person may call it. **Below ConfigAdmin** you change your own password only: a `userId` other than your own `sk` is refused (403); omit it to mean yourself. Your current password is required unless the account is on a temporary password. The password policy that governs you (see *Password policies* below) must allow self-service change — except a temporary-password account finishing its forced first change, which is always allowed — and the new password must meet that policy's length and complexity rules. **ConfigAdmin and above** change other people's passwords without the policy switch, with two limits: an **owner's** password (the org owner, anyone with the Owner role or group, root/system accounts) is never set by anyone else — 403; send them a reset link (`GET /password/forgot/:email`) instead — and setting a staff member's password needs `confirmed: true` in the body (400 without it), because it signs them out on every device. Success clears `temporaryPassword` — except when an administrator sets someone else's password with `requirePasswordChange: true`: it is then a temporary password (as Add user's \"Require change at first sign-in\"), signing in with it asks for a new one first, and the policy's rules apply to that new one instead.\n\n#### Signature\n\n```http\nPOST /profile/password/change (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Password policies: a `passwordpolicy` record carries `allowSelfServiceChange` / `allowSelfServiceReset` (both default on) and the rules (`minLenght`, `minLowercase`, `minUppercase`, `minNumbers`, `minSymbols`, `exclude`, `pattern`). A user, group or role points at one through `data.passwordPolicy` (the policy name); a policy with `isDefault: true` covers everyone else. Precedence: user > group > role > org default; within a level the first by name. **No policy applies = full self-service, no rules.**\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSWORD | password not correct | The current password is wrong. | The change is refused; the existing password stands. |\n| `403` | NOT_YOURS | You can only change your own password | A non-admin named someone else's `userId`. | Ask an administrator. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`\n- `GET /user/password-policy/assignments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Target (optional, `sk`), current and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","password":"…","newPassword":"…"}}}},"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"password not correct — The current password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"password not correct","path":"/profile/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"You can only change your own password — A non-admin named someone else's `userId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You can only change your own password","path":"/profile/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/password/change":{"post":{"operationId":"UsersController_passwordChange","summary":"Change a password","description":"Any signed-in person may call it. **Below ConfigAdmin** you change your own password only: a `userId` other than your own `sk` is refused (403); omit it to mean yourself. Your current password is required unless the account is on a temporary password. The password policy that governs you (see *Password policies* below) must allow self-service change — except a temporary-password account finishing its forced first change, which is always allowed — and the new password must meet that policy's length and complexity rules. **ConfigAdmin and above** change other people's passwords without the policy switch, with two limits: an **owner's** password (the org owner, anyone with the Owner role or group, root/system accounts) is never set by anyone else — 403; send them a reset link (`GET /password/forgot/:email`) instead — and setting a staff member's password needs `confirmed: true` in the body (400 without it), because it signs them out on every device. Success clears `temporaryPassword` — except when an administrator sets someone else's password with `requirePasswordChange: true`: it is then a temporary password (as Add user's \"Require change at first sign-in\"), signing in with it asks for a new one first, and the policy's rules apply to that new one instead.\n\n#### Signature\n\n```http\nPOST /profile/user/password/change (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Password policies: a `passwordpolicy` record carries `allowSelfServiceChange` / `allowSelfServiceReset` (both default on) and the rules (`minLenght`, `minLowercase`, `minUppercase`, `minNumbers`, `minSymbols`, `exclude`, `pattern`). A user, group or role points at one through `data.passwordPolicy` (the policy name); a policy with `isDefault: true` covers everyone else. Precedence: user > group > role > org default; within a level the first by name. **No policy applies = full self-service, no rules.**\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSWORD | password not correct | The current password is wrong. | The change is refused; the existing password stands. |\n| `403` | NOT_YOURS | You can only change your own password | A non-admin named someone else's `userId`. | Ask an administrator. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`\n- `GET /user/password-policy/assignments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Target (optional, `sk`), current and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","password":"…","newPassword":"…"}}}},"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"password not correct — The current password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"password not correct","path":"/profile/user/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"You can only change your own password — A non-admin named someone else's `userId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You can only change your own password","path":"/profile/user/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/password/change":{"post":{"operationId":"UsersController_passwordChange","summary":"Change a password","description":"Any signed-in person may call it. **Below ConfigAdmin** you change your own password only: a `userId` other than your own `sk` is refused (403); omit it to mean yourself. Your current password is required unless the account is on a temporary password. The password policy that governs you (see *Password policies* below) must allow self-service change — except a temporary-password account finishing its forced first change, which is always allowed — and the new password must meet that policy's length and complexity rules. **ConfigAdmin and above** change other people's passwords without the policy switch, with two limits: an **owner's** password (the org owner, anyone with the Owner role or group, root/system accounts) is never set by anyone else — 403; send them a reset link (`GET /password/forgot/:email`) instead — and setting a staff member's password needs `confirmed: true` in the body (400 without it), because it signs them out on every device. Success clears `temporaryPassword` — except when an administrator sets someone else's password with `requirePasswordChange: true`: it is then a temporary password (as Add user's \"Require change at first sign-in\"), signing in with it asks for a new one first, and the policy's rules apply to that new one instead.\n\n#### Signature\n\n```http\nPOST /user/password/change (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Password policies: a `passwordpolicy` record carries `allowSelfServiceChange` / `allowSelfServiceReset` (both default on) and the rules (`minLenght`, `minLowercase`, `minUppercase`, `minNumbers`, `minSymbols`, `exclude`, `pattern`). A user, group or role points at one through `data.passwordPolicy` (the policy name); a policy with `isDefault: true` covers everyone else. Precedence: user > group > role > org default; within a level the first by name. **No policy applies = full self-service, no rules.**\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSWORD | password not correct | The current password is wrong. | The change is refused; the existing password stands. |\n| `403` | NOT_YOURS | You can only change your own password | A non-admin named someone else's `userId`. | Ask an administrator. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`\n- `GET /user/password-policy/assignments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Target (optional, `sk`), current and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","password":"…","newPassword":"…"}}}},"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"password not correct — The current password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"password not correct","path":"/user/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"You can only change your own password — A non-admin named someone else's `userId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You can only change your own password","path":"/user/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/password/change":{"post":{"operationId":"UsersController_passwordChange","summary":"Change a password","description":"Any signed-in person may call it. **Below ConfigAdmin** you change your own password only: a `userId` other than your own `sk` is refused (403); omit it to mean yourself. Your current password is required unless the account is on a temporary password. The password policy that governs you (see *Password policies* below) must allow self-service change — except a temporary-password account finishing its forced first change, which is always allowed — and the new password must meet that policy's length and complexity rules. **ConfigAdmin and above** change other people's passwords without the policy switch, with two limits: an **owner's** password (the org owner, anyone with the Owner role or group, root/system accounts) is never set by anyone else — 403; send them a reset link (`GET /password/forgot/:email`) instead — and setting a staff member's password needs `confirmed: true` in the body (400 without it), because it signs them out on every device. Success clears `temporaryPassword` — except when an administrator sets someone else's password with `requirePasswordChange: true`: it is then a temporary password (as Add user's \"Require change at first sign-in\"), signing in with it asks for a new one first, and the policy's rules apply to that new one instead.\n\n#### Signature\n\n```http\nPOST /user/user/password/change (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Password policies: a `passwordpolicy` record carries `allowSelfServiceChange` / `allowSelfServiceReset` (both default on) and the rules (`minLenght`, `minLowercase`, `minUppercase`, `minNumbers`, `minSymbols`, `exclude`, `pattern`). A user, group or role points at one through `data.passwordPolicy` (the policy name); a policy with `isDefault: true` covers everyone else. Precedence: user > group > role > org default; within a level the first by name. **No policy applies = full self-service, no rules.**\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_PASSWORD | password not correct | The current password is wrong. | The change is refused; the existing password stands. |\n| `403` | NOT_YOURS | You can only change your own password | A non-admin named someone else's `userId`. | Ask an administrator. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`\n- `GET /user/password-policy/assignments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Target (optional, `sk`), current and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","password":"…","newPassword":"…"}}}},"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"password not correct — The current password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"password not correct","path":"/user/user/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"You can only change your own password — A non-admin named someone else's `userId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You can only change your own password","path":"/user/user/password/change","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/signin-invite/resend":{"post":{"operationId":"UsersController_resendSignInInvitation","summary":"Resend the sign-in invitation","description":"For a user who has never signed in (e.g. the login HR › Add person created): emails them a fresh temporary password — the same \"Your Temporary Password\" email the login was created with. Signing in with it asks for a new password first; the earlier temporary password stops working. ConfigAdmin.\n\n#### Signature\n\n```http\nPOST /profile/user/signin-invite/resend (body) -> `{ success, email }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ALREADY_SIGNED_IN | They have already signed in. Use Change Password, or send a reset link. | The user has signed in before. | Set their password or send a reset link. |\n| `404` | USER_NOT_FOUND | User not found | No user has that id. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/password/change`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"`{ success, email }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"They have already signed in. Use Change Password, or send a reset link. — The user has signed in before.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"They have already signed in. Use Change Password, or send a reset link.","path":"/profile/user/signin-invite/resend","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"User not found — No user has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"User not found","path":"/profile/user/signin-invite/resend","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"The user (`sk`).","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6"}}}}}},"/user/user/signin-invite/resend":{"post":{"operationId":"UsersController_resendSignInInvitation","summary":"Resend the sign-in invitation","description":"For a user who has never signed in (e.g. the login HR › Add person created): emails them a fresh temporary password — the same \"Your Temporary Password\" email the login was created with. Signing in with it asks for a new password first; the earlier temporary password stops working. ConfigAdmin.\n\n#### Signature\n\n```http\nPOST /user/user/signin-invite/resend (body) -> `{ success, email }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ALREADY_SIGNED_IN | They have already signed in. Use Change Password, or send a reset link. | The user has signed in before. | Set their password or send a reset link. |\n| `404` | USER_NOT_FOUND | User not found | No user has that id. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/password/change`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"`{ success, email }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"They have already signed in. Use Change Password, or send a reset link. — The user has signed in before.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"They have already signed in. Use Change Password, or send a reset link.","path":"/user/user/signin-invite/resend","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"User not found — No user has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"User not found","path":"/user/user/signin-invite/resend","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"The user (`sk`).","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6"}}}}}},"/profile/user/password-policy/assignments":{"get":{"operationId":"UsersController_passwordPolicyAssignments","summary":"Password policies and who they apply to","description":"Every password policy with the people, groups and roles that carry it (`data.passwordPolicy`), whether it is the org default, and its self-service switches — plus `options` (all users, groups, roles with their current policy) for assigning one. Precedence when several apply: user > group > role > org default.\n\n#### Signature\n\n```http\nGET /profile/user/password-policy/assignments () -> { precedence, policies[], options }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- ConfigAdmin.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/password-policy/assign`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"{ precedence, policies[], options }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/user/password-policy/assignments":{"get":{"operationId":"UsersController_passwordPolicyAssignments","summary":"Password policies and who they apply to","description":"Every password policy with the people, groups and roles that carry it (`data.passwordPolicy`), whether it is the org default, and its self-service switches — plus `options` (all users, groups, roles with their current policy) for assigning one. Precedence when several apply: user > group > role > org default.\n\n#### Signature\n\n```http\nGET /user/user/password-policy/assignments () -> { precedence, policies[], options }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- ConfigAdmin.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/password-policy/assign`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"{ precedence, policies[], options }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/user/password-policy/assign":{"post":{"operationId":"UsersController_assignPasswordPolicy","summary":"Assign a password policy","description":"Puts a policy on one user, group or role (sets its `data.passwordPolicy` to the policy name), or clears it with an empty `policy`. Returns the refreshed assignments.\n\n#### Signature\n\n```http\nPOST /profile/user/password-policy/assign (body) -> Same shape as the assignments listing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- ConfigAdmin. Root groups and roles can only be changed from the root organisation.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | No password policy named floor-staff | The policy or the target does not exist. | Check the name / sk. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /user/password-policy/assignments`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Same shape as the assignments listing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No password policy named floor-staff — The policy or the target does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No password policy named floor-staff","path":"/profile/user/password-policy/assign","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"What to assign to, and which policy.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"kind":"group","target":"65f0c2a1e4b0a1b2c3d4e5f6","policy":"floor-staff"}}}}}},"/user/user/password-policy/assign":{"post":{"operationId":"UsersController_assignPasswordPolicy","summary":"Assign a password policy","description":"Puts a policy on one user, group or role (sets its `data.passwordPolicy` to the policy name), or clears it with an empty `policy`. Returns the refreshed assignments.\n\n#### Signature\n\n```http\nPOST /user/user/password-policy/assign (body) -> Same shape as the assignments listing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- ConfigAdmin. Root groups and roles can only be changed from the root organisation.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | No password policy named floor-staff | The policy or the target does not exist. | Check the name / sk. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /user/password-policy/assignments`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Same shape as the assignments listing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No password policy named floor-staff — The policy or the target does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No password policy named floor-staff","path":"/user/user/password-policy/assign","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"What to assign to, and which policy.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"kind":"group","target":"65f0c2a1e4b0a1b2c3d4e5f6","policy":"floor-staff"}}}}}},"/profile/user/two-factor/status/{userType}/{userId}":{"get":{"operationId":"UsersController_twoFactorStatusForAccount","summary":"Read another account's second-factor state","description":"For an administrator looking at someone else's profile: whether 2FA is on, the method, when it was verified, how many backup codes remain, which methods the org offers, and the enrolled factors (`factors`, `defaultFactorId`, `twoFactorEnabled`). No secrets and no phone numbers beyond the factor label.\n\n#### Signature\n\n```http\nGET /profile/user/two-factor/status/{userType}/{userId} (userType: string, userId: string) -> Second-factor state\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/two-factor/reset`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"userType","required":true,"in":"path","schema":{"type":"string","enum":["user","customer"]},"description":"`customer` for a customer; anything else means a staff user.","example":"user"},{"name":"userId","required":true,"in":"path","schema":{"type":"string"},"description":"The account `sk`.","example":"65f0c2a1e4b0a1b2c3d4e5f6"}],"responses":{"200":{"description":"Second-factor state","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"enabled":true,"method":"authenticator","backupCodesRemaining":7,"availableMethods":["authenticator","email"],"twoFactorEnabled":true,"defaultFactorId":"f1","factors":[{"id":"f1","type":"authenticator","label":"Authenticator app","status":"verified","isDefault":true}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"]}},"/user/user/two-factor/status/{userType}/{userId}":{"get":{"operationId":"UsersController_twoFactorStatusForAccount","summary":"Read another account's second-factor state","description":"For an administrator looking at someone else's profile: whether 2FA is on, the method, when it was verified, how many backup codes remain, which methods the org offers, and the enrolled factors (`factors`, `defaultFactorId`, `twoFactorEnabled`). No secrets and no phone numbers beyond the factor label.\n\n#### Signature\n\n```http\nGET /user/user/two-factor/status/{userType}/{userId} (userType: string, userId: string) -> Second-factor state\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/two-factor/reset`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"userType","required":true,"in":"path","schema":{"type":"string","enum":["user","customer"]},"description":"`customer` for a customer; anything else means a staff user.","example":"user"},{"name":"userId","required":true,"in":"path","schema":{"type":"string"},"description":"The account `sk`.","example":"65f0c2a1e4b0a1b2c3d4e5f6"}],"responses":{"200":{"description":"Second-factor state","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"enabled":true,"method":"authenticator","backupCodesRemaining":7,"availableMethods":["authenticator","email"],"twoFactorEnabled":true,"defaultFactorId":"f1","factors":[{"id":"f1","type":"authenticator","label":"Authenticator app","status":"verified","isDefault":true}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"]}},"/profile/user/two-factor/reset":{"post":{"operationId":"UsersController_resetTwoFactor","summary":"Clear an account's second factor","description":"For an account locked out of its own 2FA — a lost authenticator with no backup codes left. Removes every enrolled factor and the backup codes and turns 2FA off; the owner enrols again from their own session. The reset is logged with the administrator and the reason.\n\n#### Signature\n\n```http\nPOST /profile/user/two-factor/reset (body) -> { userId, userType, twoFactorEnabled: false, reset: true }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NO_SECURITY_RECORD | No security record for that account | The account has never had security settings. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /user/two-factor/status/{userType}/{userId}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ userId, userType, twoFactorEnabled: false, reset: true }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No security record for that account — The account has never had security settings.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No security record for that account","path":"/profile/user/two-factor/reset","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"Whose factor to clear.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string"},"userType":{"type":"string","enum":["user","customer"],"default":"user"},"reason":{"type":"string"}}},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","userType":"user","reason":"Lost phone, identity checked by phone call"}}}}}},"/user/user/two-factor/reset":{"post":{"operationId":"UsersController_resetTwoFactor","summary":"Clear an account's second factor","description":"For an account locked out of its own 2FA — a lost authenticator with no backup codes left. Removes every enrolled factor and the backup codes and turns 2FA off; the owner enrols again from their own session. The reset is logged with the administrator and the reason.\n\n#### Signature\n\n```http\nPOST /user/user/two-factor/reset (body) -> { userId, userType, twoFactorEnabled: false, reset: true }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NO_SECURITY_RECORD | No security record for that account | The account has never had security settings. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /user/two-factor/status/{userType}/{userId}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ userId, userType, twoFactorEnabled: false, reset: true }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No security record for that account — The account has never had security settings.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No security record for that account","path":"/user/user/two-factor/reset","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"Whose factor to clear.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string"},"userType":{"type":"string","enum":["user","customer"],"default":"user"},"reason":{"type":"string"}}},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","userType":"user","reason":"Lost phone, identity checked by phone call"}}}}}},"/profile/user/profile/{emailOrUsername}":{"get":{"operationId":"UsersController_userProfile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"}],"responses":{"200":{"description":"The user profile","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Get a user profile (admins only)","description":"Fetches a user’s full profile by email or username. Admins only (ConfigAdmin) — anyone else gets 403. To look up a colleague (name, title, email, phone) use `POST /repository/find/user` with `{ \"query\": { \"data.email\": \"someone@company.com\" } }`.\n\n#### Signature\n\n```http\nGET /profile/user/profile/{emailOrUsername} (emailOrUsername: string) -> The user profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/find/{datatype}`\n- `POST /update`"}},"/user/user/profile/{emailOrUsername}":{"get":{"operationId":"UsersController_userProfile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"}],"responses":{"200":{"description":"The user profile","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Get a user profile (admins only)","description":"Fetches a user’s full profile by email or username. Admins only (ConfigAdmin) — anyone else gets 403. To look up a colleague (name, title, email, phone) use `POST /repository/find/user` with `{ \"query\": { \"data.email\": \"someone@company.com\" } }`.\n\n#### Signature\n\n```http\nGET /user/user/profile/{emailOrUsername} (emailOrUsername: string) -> The user profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /repository/find/{datatype}`\n- `POST /update`"}},"/profile/user/delete/{emailOrUsername}":{"delete":{"operationId":"UsersController_deleteUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"},{"name":"reason","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Delete a user","description":"Deletes a user account properly — notifying them, unwinding sessions and recording the removal. This is the endpoint the generic repository delete refuses in favour of.\n\n#### Signature\n\n```http\nDELETE /profile/user/delete/{emailOrUsername} (emailOrUsername: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Use this rather than deleting the record through the repository API.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/delete/{datatype}/{id}`"}},"/user/user/delete/{emailOrUsername}":{"delete":{"operationId":"UsersController_deleteUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"},{"name":"reason","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Delete a user","description":"Deletes a user account properly — notifying them, unwinding sessions and recording the removal. This is the endpoint the generic repository delete refuses in favour of.\n\n#### Signature\n\n```http\nDELETE /user/user/delete/{emailOrUsername} (emailOrUsername: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Use this rather than deleting the record through the repository API.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/delete/{datatype}/{id}`"}},"/profile/user/self":{"delete":{"operationId":"UsersController_deleteSelfUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Delete my account","description":"Deletes the caller's own account. Irreversible, and the caller is signed out as a consequence.\n\n#### Signature\n\n```http\nDELETE /profile/user/self () -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /user/delete/{emailOrUsername}`"}},"/user/user/self":{"delete":{"operationId":"UsersController_deleteSelfUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Delete my account","description":"Deletes the caller's own account. Irreversible, and the caller is signed out as a consequence.\n\n#### Signature\n\n```http\nDELETE /user/user/self () -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /user/delete/{emailOrUsername}`"}},"/profile/password/forgot/{email}":{"get":{"operationId":"UsersController_passwordForgot","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"},{"name":"strategy","required":true,"in":"query","schema":{"type":"string"}},{"name":"password","required":true,"in":"query","schema":{"type":"string"}},{"name":"redirectUrl","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Request a password reset","description":"Sends a password reset link (or, with `strategy=temporary_password`, a temporary password) to a staff user. When the password policy governing that person has `allowSelfServiceReset: false`, nothing is sent, the refusal is logged, and the response is exactly the one an unknown address gets — the switch cannot be used to learn which addresses have accounts. HR issuing a new hire's temporary password does not go through this route and is not affected.\n\n#### Signature\n\n```http\nGET /profile/password/forgot/{email} (email: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit it — otherwise it doubles as an email-bombing tool.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`"}},"/profile/user/password/forgot/{email}":{"get":{"operationId":"UsersController_passwordForgot","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"},{"name":"strategy","required":true,"in":"query","schema":{"type":"string"}},{"name":"password","required":true,"in":"query","schema":{"type":"string"}},{"name":"redirectUrl","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Request a password reset","description":"Sends a password reset link (or, with `strategy=temporary_password`, a temporary password) to a staff user. When the password policy governing that person has `allowSelfServiceReset: false`, nothing is sent, the refusal is logged, and the response is exactly the one an unknown address gets — the switch cannot be used to learn which addresses have accounts. HR issuing a new hire's temporary password does not go through this route and is not affected.\n\n#### Signature\n\n```http\nGET /profile/user/password/forgot/{email} (email: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit it — otherwise it doubles as an email-bombing tool.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`"}},"/user/password/forgot/{email}":{"get":{"operationId":"UsersController_passwordForgot","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"},{"name":"strategy","required":true,"in":"query","schema":{"type":"string"}},{"name":"password","required":true,"in":"query","schema":{"type":"string"}},{"name":"redirectUrl","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Request a password reset","description":"Sends a password reset link (or, with `strategy=temporary_password`, a temporary password) to a staff user. When the password policy governing that person has `allowSelfServiceReset: false`, nothing is sent, the refusal is logged, and the response is exactly the one an unknown address gets — the switch cannot be used to learn which addresses have accounts. HR issuing a new hire's temporary password does not go through this route and is not affected.\n\n#### Signature\n\n```http\nGET /user/password/forgot/{email} (email: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit it — otherwise it doubles as an email-bombing tool.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`"}},"/user/user/password/forgot/{email}":{"get":{"operationId":"UsersController_passwordForgot","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"},{"name":"strategy","required":true,"in":"query","schema":{"type":"string"}},{"name":"password","required":true,"in":"query","schema":{"type":"string"}},{"name":"redirectUrl","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Request a password reset","description":"Sends a password reset link (or, with `strategy=temporary_password`, a temporary password) to a staff user. When the password policy governing that person has `allowSelfServiceReset: false`, nothing is sent, the refusal is logged, and the response is exactly the one an unknown address gets — the switch cannot be used to learn which addresses have accounts. HR issuing a new hire's temporary password does not go through this route and is not affected.\n\n#### Signature\n\n```http\nGET /user/user/password/forgot/{email} (email: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit it — otherwise it doubles as an email-bombing tool.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`"}},"/profile/password/reset":{"post":{"operationId":"UsersController_passwordReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Reset a password","description":"Sets a new password using a reset token. The token should be single-use and short-lived; validate it first if you want to check before asking for the new password. For a staff user the governing password policy is checked again: with self-service reset switched off the token is refused as invalid (a link issued before the switch no longer works), and the new password must meet the policy's rules.\n\n#### Signature\n\n```http\nPOST /profile/password/reset (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/validate-token`","requestBody":{"description":"Token and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q","newPassword":"…"}}}}}},"/profile/user/password/reset":{"post":{"operationId":"UsersController_passwordReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Reset a password","description":"Sets a new password using a reset token. The token should be single-use and short-lived; validate it first if you want to check before asking for the new password. For a staff user the governing password policy is checked again: with self-service reset switched off the token is refused as invalid (a link issued before the switch no longer works), and the new password must meet the policy's rules.\n\n#### Signature\n\n```http\nPOST /profile/user/password/reset (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/validate-token`","requestBody":{"description":"Token and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q","newPassword":"…"}}}}}},"/user/password/reset":{"post":{"operationId":"UsersController_passwordReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Reset a password","description":"Sets a new password using a reset token. The token should be single-use and short-lived; validate it first if you want to check before asking for the new password. For a staff user the governing password policy is checked again: with self-service reset switched off the token is refused as invalid (a link issued before the switch no longer works), and the new password must meet the policy's rules.\n\n#### Signature\n\n```http\nPOST /user/password/reset (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/validate-token`","requestBody":{"description":"Token and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q","newPassword":"…"}}}}}},"/user/user/password/reset":{"post":{"operationId":"UsersController_passwordReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Reset a password","description":"Sets a new password using a reset token. The token should be single-use and short-lived; validate it first if you want to check before asking for the new password. For a staff user the governing password policy is checked again: with self-service reset switched off the token is refused as invalid (a link issued before the switch no longer works), and the new password must meet the policy's rules.\n\n#### Signature\n\n```http\nPOST /user/user/password/reset (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/validate-token`","requestBody":{"description":"Token and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q","newPassword":"…"}}}}}},"/profile/password/validate-token":{"post":{"operationId":"UsersController_validateResetToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the token is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Validate a reset token","description":"Checks a password reset token before showing the reset form, so an expired link fails early rather than after the user has typed a new password.\n\n#### Signature\n\n```http\nPOST /profile/password/validate-token (body) -> Whether the token is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`","requestBody":{"description":"The token to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q"}}}}}},"/profile/user/password/validate-token":{"post":{"operationId":"UsersController_validateResetToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the token is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Validate a reset token","description":"Checks a password reset token before showing the reset form, so an expired link fails early rather than after the user has typed a new password.\n\n#### Signature\n\n```http\nPOST /profile/user/password/validate-token (body) -> Whether the token is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`","requestBody":{"description":"The token to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q"}}}}}},"/user/password/validate-token":{"post":{"operationId":"UsersController_validateResetToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the token is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Validate a reset token","description":"Checks a password reset token before showing the reset form, so an expired link fails early rather than after the user has typed a new password.\n\n#### Signature\n\n```http\nPOST /user/password/validate-token (body) -> Whether the token is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`","requestBody":{"description":"The token to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q"}}}}}},"/user/user/password/validate-token":{"post":{"operationId":"UsersController_validateResetToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the token is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Validate a reset token","description":"Checks a password reset token before showing the reset form, so an expired link fails early rather than after the user has typed a new password.\n\n#### Signature\n\n```http\nPOST /user/user/password/validate-token (body) -> Whether the token is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /password/reset`","requestBody":{"description":"The token to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q"}}}}}},"/profile/user/invite/validate":{"post":{"operationId":"UsersController_inviteValidate","summary":"Validate an invitation","description":"Checks an invitation token before showing the acceptance form, so an expired or used invitation fails before the user fills anything in.\n\n#### Signature\n\n```http\nPOST /profile/user/invite/validate (body) -> Whether the invitation is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_TOKEN | Invalid or expired invitation token | The token is unrecognised or has expired. | Ask an admin to resend the invitation. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/complete`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the invitation is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid or expired invitation token — The token is unrecognised or has expired.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid or expired invitation token","path":"/profile/user/invite/validate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"The token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"inv_9k2m4h1p7q"}}}}}},"/user/user/invite/validate":{"post":{"operationId":"UsersController_inviteValidate","summary":"Validate an invitation","description":"Checks an invitation token before showing the acceptance form, so an expired or used invitation fails before the user fills anything in.\n\n#### Signature\n\n```http\nPOST /user/user/invite/validate (body) -> Whether the invitation is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_TOKEN | Invalid or expired invitation token | The token is unrecognised or has expired. | Ask an admin to resend the invitation. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/complete`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the invitation is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid or expired invitation token — The token is unrecognised or has expired.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid or expired invitation token","path":"/user/user/invite/validate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"The token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"inv_9k2m4h1p7q"}}}}}},"/profile/user/invite/complete":{"post":{"operationId":"UsersController_inviteComplete","summary":"Complete an invitation","description":"Accepts an invitation and creates the account. An invitation can only be completed once.\n\n#### Signature\n\n```http\nPOST /profile/user/invite/complete (body) -> The created account and tokens\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ALREADY_COMPLETED | This invitation has already been completed | The invitation was used. | Sign in instead. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/validate`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created account and tokens","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"This invitation has already been completed — The invitation was used.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This invitation has already been completed","path":"/profile/user/invite/complete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"The token and account details.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"inv_9k2m4h1p7q","password":"…","firstName":"Grace","lastName":"Hopper"}}}}}},"/user/user/invite/complete":{"post":{"operationId":"UsersController_inviteComplete","summary":"Complete an invitation","description":"Accepts an invitation and creates the account. An invitation can only be completed once.\n\n#### Signature\n\n```http\nPOST /user/user/invite/complete (body) -> The created account and tokens\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ALREADY_COMPLETED | This invitation has already been completed | The invitation was used. | Sign in instead. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/validate`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created account and tokens","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"This invitation has already been completed — The invitation was used.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This invitation has already been completed","path":"/user/user/invite/complete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"requestBody":{"description":"The token and account details.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"inv_9k2m4h1p7q","password":"…","firstName":"Grace","lastName":"Hopper"}}}}}},"/profile/user/invite/resend/{invitationId}":{"post":{"operationId":"UsersController_inviteResend","summary":"Resend an invitation","description":"Re-sends an outstanding invitation — the correct response when the first was not received, since a second `send` is refused.\n\n#### Signature\n\n```http\nPOST /profile/user/invite/resend/{invitationId} (invitationId: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVITATION_NOT_FOUND | Invitation not found | No invitation has that id. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/send`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"invitationId","required":true,"in":"path","description":"Invitation id.","schema":{"type":"string"},"example":"INV-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invitation not found — No invitation has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invitation not found","path":"/profile/user/invite/resend/{invitationId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"]}},"/user/user/invite/resend/{invitationId}":{"post":{"operationId":"UsersController_inviteResend","summary":"Resend an invitation","description":"Re-sends an outstanding invitation — the correct response when the first was not received, since a second `send` is refused.\n\n#### Signature\n\n```http\nPOST /user/user/invite/resend/{invitationId} (invitationId: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVITATION_NOT_FOUND | Invitation not found | No invitation has that id. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/send`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"invitationId","required":true,"in":"path","description":"Invitation id.","schema":{"type":"string"},"example":"INV-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invitation not found — No invitation has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invitation not found","path":"/user/user/invite/resend/{invitationId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"]}},"/profile/user/invite/send":{"post":{"operationId":"UsersController_inviteSend","summary":"Send an invitation","description":"Invites someone to join the organization. Only one active invitation per address at a time — a second is refused rather than sending a duplicate.\n\n#### Signature\n\n```http\nPOST /profile/user/invite/send (body) -> The invitation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVITE_EXISTS | An active invitation already exists for this email. Please wait for it to expire. | An unexpired invitation is already outstanding. | Resend the existing invitation rather than creating another. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/resend/{invitationId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The invitation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"An active invitation already exists for this email. Please wait for it to expire. — An unexpired invitation is already outstanding.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"An active invitation already exists for this email. Please wait for it to expire.","path":"/profile/user/invite/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"Who to invite.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"grace@example.com","roles":["User"],"message":"Welcome aboard"}}}}}},"/user/user/invite/send":{"post":{"operationId":"UsersController_inviteSend","summary":"Send an invitation","description":"Invites someone to join the organization. Only one active invitation per address at a time — a second is refused rather than sending a duplicate.\n\n#### Signature\n\n```http\nPOST /user/user/invite/send (body) -> The invitation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVITE_EXISTS | An active invitation already exists for this email. Please wait for it to expire. | An unexpired invitation is already outstanding. | Resend the existing invitation rather than creating another. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/invite/resend/{invitationId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The invitation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"An active invitation already exists for this email. Please wait for it to expire. — An unexpired invitation is already outstanding.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"An active invitation already exists for this email. Please wait for it to expire.","path":"/user/user/invite/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"requestBody":{"description":"Who to invite.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"grace@example.com","roles":["User"],"message":"Welcome aboard"}}}}}},"/profile/user/directory/lookup":{"post":{"operationId":"UsersController_directoryLookup","summary":"Find the orgs an email belongs to","parameters":[],"responses":{"201":{"description":"{ orgs }","content":{"application/json":{"schema":{"type":"object","properties":{"orgs":{"type":"array","items":{"type":"object","properties":{"orgId":{"type":"string"},"displayName":{"type":"string"},"label":{"type":"string"},"recent":{"type":"boolean"}}}}}},"example":{"orgs":[{"orgId":"acme","displayName":"Acme","label":"Acme · Aurora","recent":true},{"orgId":"acme-north","displayName":"Acme","label":"Acme · Naperville"}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"description":"Sign-in step one when the org is not known: the organizations this email has an account in, most recently used first, as `{ orgId, displayName, label }`. `label` is what to show: the business name, and when two names match, the city, else the day joined (\"Larkfield Heating and Cooling · Aurora\") — never the org ID, and never the person's role (this route is public; the role is only given after a correct password, in `requiresOrgChoice` and `password_other_account`). With several accounts the most recently used one is marked `recent: true` (a \"last used\" time in the future is not trusted). An unknown email answers `{ orgs: [] }`.\n\n#### Signature\n\n```http\nPOST /profile/user/directory/lookup (body) -> { orgs }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated, and it reveals which orgs an address belongs to — an enumeration surface.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signin`","requestBody":{"description":"The email.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}}},"example":{"email":"ada@example.com"}}}}}},"/user/user/directory/lookup":{"post":{"operationId":"UsersController_directoryLookup","summary":"Find the orgs an email belongs to","parameters":[],"responses":{"201":{"description":"{ orgs }","content":{"application/json":{"schema":{"type":"object","properties":{"orgs":{"type":"array","items":{"type":"object","properties":{"orgId":{"type":"string"},"displayName":{"type":"string"},"label":{"type":"string"},"recent":{"type":"boolean"}}}}}},"example":{"orgs":[{"orgId":"acme","displayName":"Acme","label":"Acme · Aurora","recent":true},{"orgId":"acme-north","displayName":"Acme","label":"Acme · Naperville"}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"description":"Sign-in step one when the org is not known: the organizations this email has an account in, most recently used first, as `{ orgId, displayName, label }`. `label` is what to show: the business name, and when two names match, the city, else the day joined (\"Larkfield Heating and Cooling · Aurora\") — never the org ID, and never the person's role (this route is public; the role is only given after a correct password, in `requiresOrgChoice` and `password_other_account`). With several accounts the most recently used one is marked `recent: true` (a \"last used\" time in the future is not trusted). An unknown email answers `{ orgs: [] }`.\n\n#### Signature\n\n```http\nPOST /user/user/directory/lookup (body) -> { orgs }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated, and it reveals which orgs an address belongs to — an enumeration surface.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signin`","requestBody":{"description":"The email.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}}},"example":{"email":"ada@example.com"}}}}}},"/profile/user/directory/backfill":{"post":{"operationId":"UsersController_directoryBackfill","summary":"Rebuild the account directory","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"{ orgs, users }","content":{"application/json":{"schema":{"type":"object","properties":{"orgs":{"type":"integer"},"users":{"type":"integer"}}},"example":{"orgs":42,"users":1310}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Indexes every user of every org into the account directory that sign-in without an `orgid` uses. A one-off after the directory was introduced; sign-ins keep it current afterwards. Returns how many orgs and users were indexed.\n\n#### Signature\n\n```http\nPOST /profile/user/directory/backfill () -> { orgs, users }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Platform-wide: it reads every org, not just the caller's.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/directory/lookup`"}},"/user/user/directory/backfill":{"post":{"operationId":"UsersController_directoryBackfill","summary":"Rebuild the account directory","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"{ orgs, users }","content":{"application/json":{"schema":{"type":"object","properties":{"orgs":{"type":"integer"},"users":{"type":"integer"}}},"example":{"orgs":42,"users":1310}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"description":"Indexes every user of every org into the account directory that sign-in without an `orgid` uses. A one-off after the directory was introduced; sign-ins keep it current afterwards. Returns how many orgs and users were indexed.\n\n#### Signature\n\n```http\nPOST /user/user/directory/backfill () -> { orgs, users }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Platform-wide: it reads every org, not just the caller's.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/directory/lookup`"}},"/profile/session-access":{"post":{"operationId":"UsersController_sessionAccessToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The scoped token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Get a session access token","description":"Issues a scoped access token for the current session — used where a component needs a narrower token than the caller holds.\n\n#### Signature\n\n```http\nPOST /profile/session-access (body) -> The scoped token\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/refresh`","requestBody":{"description":"What the token is for.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"scope":"storefront"}}}}}},"/user/session-access":{"post":{"operationId":"UsersController_sessionAccessToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The scoped token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Get a session access token","description":"Issues a scoped access token for the current session — used where a component needs a narrower token than the caller holds.\n\n#### Signature\n\n```http\nPOST /user/session-access (body) -> The scoped token\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /user/refresh`","requestBody":{"description":"What the token is for.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"scope":"storefront"}}}}}},"/profile/update":{"post":{"operationId":"UsersController_update","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Update a user","description":"Updates a user record: the body is merged over the stored record, so roles and groups sent here are written too. Admin only, and root roles or root groups in `data.roles` / `data.groups` are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/update (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/add`","requestBody":{"description":"The user to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace"}}}}}},"/profile/user/update":{"post":{"operationId":"UsersController_update","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/user/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Update a user","description":"Updates a user record: the body is merged over the stored record, so roles and groups sent here are written too. Admin only, and root roles or root groups in `data.roles` / `data.groups` are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/user/update (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/add`","requestBody":{"description":"The user to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace"}}}}}},"/user/update":{"post":{"operationId":"UsersController_update","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Update a user","description":"Updates a user record: the body is merged over the stored record, so roles and groups sent here are written too. Admin only, and root roles or root groups in `data.roles` / `data.groups` are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/update (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/add`","requestBody":{"description":"The user to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace"}}}}}},"/user/user/update":{"post":{"operationId":"UsersController_update","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/user/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Profiles"],"summary":"Update a user","description":"Updates a user record: the body is merged over the stored record, so roles and groups sent here are written too. Admin only, and root roles or root groups in `data.roles` / `data.groups` are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/user/update (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/add`","requestBody":{"description":"The user to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace"}}}}}},"/profile/user/group/add":{"post":{"operationId":"UsersController_groupAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/profile/user/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/user/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Add a user to a group","description":"Adds a staff user (found by `email`, `username` or `id`) to one or more groups, by group name or `sk`. Group membership carries the group's roles and permissions, so this is a privilege change — admin only. A group that grants a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/user/group/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/remove`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["groups"],"properties":{"email":{"type":"string"},"username":{"type":"string"},"id":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/profile/group/add":{"post":{"operationId":"UsersController_groupAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/profile/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Add a user to a group","description":"Adds a staff user (found by `email`, `username` or `id`) to one or more groups, by group name or `sk`. Group membership carries the group's roles and permissions, so this is a privilege change — admin only. A group that grants a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/group/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/remove`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["groups"],"properties":{"email":{"type":"string"},"username":{"type":"string"},"id":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/user/user/group/add":{"post":{"operationId":"UsersController_groupAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/user/user/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/user/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Add a user to a group","description":"Adds a staff user (found by `email`, `username` or `id`) to one or more groups, by group name or `sk`. Group membership carries the group's roles and permissions, so this is a privilege change — admin only. A group that grants a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/user/group/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/remove`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["groups"],"properties":{"email":{"type":"string"},"username":{"type":"string"},"id":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/user/group/add":{"post":{"operationId":"UsersController_groupAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/user/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/group/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Add a user to a group","description":"Adds a staff user (found by `email`, `username` or `id`) to one or more groups, by group name or `sk`. Group membership carries the group's roles and permissions, so this is a privilege change — admin only. A group that grants a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/group/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/remove`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["groups"],"properties":{"email":{"type":"string"},"username":{"type":"string"},"id":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/profile/user/group/remove":{"post":{"operationId":"UsersController_groupRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/profile/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"user not found — No staff user with that email.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"user not found","path":"/profile/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove a user from a group","description":"Removes a staff user (by `email`) from one or more groups, withdrawing the access they conferred. Taking someone out of a root group is refused outside the root org, same as putting them in.\n\n#### Signature\n\n```http\nPOST /profile/user/group/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `404` | USER_NOT_FOUND | user not found | No staff user with that email. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/add`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","groups"],"properties":{"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/profile/group/remove":{"post":{"operationId":"UsersController_groupRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/profile/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"user not found — No staff user with that email.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"user not found","path":"/profile/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove a user from a group","description":"Removes a staff user (by `email`) from one or more groups, withdrawing the access they conferred. Taking someone out of a root group is refused outside the root org, same as putting them in.\n\n#### Signature\n\n```http\nPOST /profile/group/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `404` | USER_NOT_FOUND | user not found | No staff user with that email. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/add`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","groups"],"properties":{"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/user/user/group/remove":{"post":{"operationId":"UsersController_groupRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/user/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"user not found — No staff user with that email.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"user not found","path":"/user/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove a user from a group","description":"Removes a staff user (by `email`) from one or more groups, withdrawing the access they conferred. Taking someone out of a root group is refused outside the root org, same as putting them in.\n\n#### Signature\n\n```http\nPOST /user/user/group/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `404` | USER_NOT_FOUND | user not found | No staff user with that email. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/add`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","groups"],"properties":{"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/user/group/remove":{"post":{"operationId":"UsersController_groupRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Groups are required — `groups` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Groups are required","path":"/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"user not found — No staff user with that email.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"user not found","path":"/user/group/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove a user from a group","description":"Removes a staff user (by `email`) from one or more groups, withdrawing the access they conferred. Taking someone out of a root group is refused outside the root org, same as putting them in.\n\n#### Signature\n\n```http\nPOST /user/group/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_REQUIRED | Groups are required | `groups` is empty. | — |\n| `404` | USER_NOT_FOUND | user not found | No staff user with that email. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /group/add`","requestBody":{"description":"The user and groups.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","groups"],"properties":{"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","groups":["engineering"]}}}}}},"/profile/user/lockout":{"post":{"operationId":"UsersController_setUserLockout","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The user record","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"User ID and a boolean locked value are required — `userId` is empty or `locked` is not a boolean.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User ID and a boolean locked value are required","path":"/profile/user/lockout","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only an organization owner can change account access — The caller is not an Owner of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only an organization owner can change account access","path":"/profile/user/lockout","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"User not found — No staff user with that id in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"User not found","path":"/profile/user/lockout","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Switch a user's access off or on","description":"An org owner locks (or unlocks) another staff user of the same org. A locked user is refused at sign-in and on every session check with \"This account is locked. Ask the business owner to unlock it.\" (on a session: 403 { code: \"account_locked\", action: \"sign_in\" }, and the app signs out). Access that offboarding ended answers { code: \"access_ended\", message: \"Your access to <business> has ended. If you think this is a mistake, contact your manager.\" } instead; locking also pushes a realtime sign-out to their open sessions. Owners and system accounts cannot be locked, and nobody can lock themselves. Returns the refreshed user record.\n\n#### Signature\n\n```http\nPOST /profile/user/lockout (body) -> The user record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | LOCKOUT_INVALID | User ID and a boolean locked value are required | `userId` is empty or `locked` is not a boolean. | — |\n| `403` | NOT_OWNER | Only an organization owner can change account access | The caller is not an Owner of this org. | — |\n| `404` | USER_NOT_FOUND | User not found | No staff user with that id in this org. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","requestBody":{"description":"Who, and which way.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","locked"],"properties":{"userId":{"type":"string","description":"User `sk`."},"locked":{"type":"boolean"}}},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","locked":true}}}}}},"/user/user/lockout":{"post":{"operationId":"UsersController_setUserLockout","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The user record","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"User ID and a boolean locked value are required — `userId` is empty or `locked` is not a boolean.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User ID and a boolean locked value are required","path":"/user/user/lockout","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only an organization owner can change account access — The caller is not an Owner of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only an organization owner can change account access","path":"/user/user/lockout","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"User not found — No staff user with that id in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"User not found","path":"/user/user/lockout","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Switch a user's access off or on","description":"An org owner locks (or unlocks) another staff user of the same org. A locked user is refused at sign-in and on every session check with \"This account is locked. Ask the business owner to unlock it.\" (on a session: 403 { code: \"account_locked\", action: \"sign_in\" }, and the app signs out). Access that offboarding ended answers { code: \"access_ended\", message: \"Your access to <business> has ended. If you think this is a mistake, contact your manager.\" } instead; locking also pushes a realtime sign-out to their open sessions. Owners and system accounts cannot be locked, and nobody can lock themselves. Returns the refreshed user record.\n\n#### Signature\n\n```http\nPOST /user/user/lockout (body) -> The user record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | LOCKOUT_INVALID | User ID and a boolean locked value are required | `userId` is empty or `locked` is not a boolean. | — |\n| `403` | NOT_OWNER | Only an organization owner can change account access | The caller is not an Owner of this org. | — |\n| `404` | USER_NOT_FOUND | User not found | No staff user with that id in this org. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","requestBody":{"description":"Who, and which way.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","locked"],"properties":{"userId":{"type":"string","description":"User `sk`."},"locked":{"type":"boolean"}}},"example":{"userId":"65f0c2a1e4b0a1b2c3d4e5f6","locked":true}}}}}},"/profile/user/role/add":{"post":{"operationId":"UsersController_roleAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"User and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User and roles are required","path":"/profile/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"role not found ContentReviewer — A custom role name does not exist in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"role not found ContentReviewer","path":"/profile/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Grant a role","description":"Grants one or more roles to a staff user (`email` may also be the user `sk`). Built-in roles are used as named; a custom role is resolved in this org by name or `sk` and stored by its name. **This is a direct privilege escalation** — admin only, and root roles are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/user/role/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | User and roles are required | `email` or `roles` is empty. | — |\n| `404` | ROLE_NOT_FOUND | role not found ContentReviewer | A custom role name does not exist in this org. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/remove`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/profile/role/add":{"post":{"operationId":"UsersController_roleAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"User and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User and roles are required","path":"/profile/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"role not found ContentReviewer — A custom role name does not exist in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"role not found ContentReviewer","path":"/profile/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Grant a role","description":"Grants one or more roles to a staff user (`email` may also be the user `sk`). Built-in roles are used as named; a custom role is resolved in this org by name or `sk` and stored by its name. **This is a direct privilege escalation** — admin only, and root roles are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/role/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | User and roles are required | `email` or `roles` is empty. | — |\n| `404` | ROLE_NOT_FOUND | role not found ContentReviewer | A custom role name does not exist in this org. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/remove`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/user/user/role/add":{"post":{"operationId":"UsersController_roleAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"User and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User and roles are required","path":"/user/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"role not found ContentReviewer — A custom role name does not exist in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"role not found ContentReviewer","path":"/user/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Grant a role","description":"Grants one or more roles to a staff user (`email` may also be the user `sk`). Built-in roles are used as named; a custom role is resolved in this org by name or `sk` and stored by its name. **This is a direct privilege escalation** — admin only, and root roles are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/user/role/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | User and roles are required | `email` or `roles` is empty. | — |\n| `404` | ROLE_NOT_FOUND | role not found ContentReviewer | A custom role name does not exist in this org. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/remove`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/user/role/add":{"post":{"operationId":"UsersController_roleAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"User and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"User and roles are required","path":"/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"role not found ContentReviewer — A custom role name does not exist in this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"role not found ContentReviewer","path":"/user/role/add","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Grant a role","description":"Grants one or more roles to a staff user (`email` may also be the user `sk`). Built-in roles are used as named; a custom role is resolved in this org by name or `sk` and stored by its name. **This is a direct privilege escalation** — admin only, and root roles are refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/role/add (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | User and roles are required | `email` or `roles` is empty. | — |\n| `404` | ROLE_NOT_FOUND | role not found ContentReviewer | A custom role name does not exist in this org. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /role/remove`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/profile/user/role/remove":{"post":{"operationId":"UsersController_roleRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Email and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Email and roles are required","path":"/profile/user/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/user/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Revoke a role","description":"Removes one or more roles from a staff user, withdrawing the access they granted. Takes effect on their next token — an existing access token may retain the role until it expires. Revoking a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/user/role/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Revocation is not instant if the user holds a valid token — force a sign-out where it matters.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | Email and roles are required | `email` or `roles` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `GET /logout/{userId}`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/profile/role/remove":{"post":{"operationId":"UsersController_roleRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Email and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Email and roles are required","path":"/profile/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/profile/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Revoke a role","description":"Removes one or more roles from a staff user, withdrawing the access they granted. Takes effect on their next token — an existing access token may retain the role until it expires. Revoking a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /profile/role/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Revocation is not instant if the user holds a valid token — force a sign-out where it matters.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | Email and roles are required | `email` or `roles` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `GET /logout/{userId}`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/user/user/role/remove":{"post":{"operationId":"UsersController_roleRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Email and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Email and roles are required","path":"/user/user/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/user/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Revoke a role","description":"Removes one or more roles from a staff user, withdrawing the access they granted. Takes effect on their next token — an existing access token may retain the role until it expires. Revoking a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/user/role/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Revocation is not instant if the user holds a valid token — force a sign-out where it matters.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | Email and roles are required | `email` or `roles` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `GET /logout/{userId}`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/user/role/remove":{"post":{"operationId":"UsersController_roleRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated user","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"400":{"description":"Email and roles are required — `email` or `roles` is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Email and roles are required","path":"/user/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the root organization can give a user a root role. Blocked: RootAdmin. — A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the root organization can give a user a root role. Blocked: RootAdmin.","path":"/user/role/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Revoke a role","description":"Removes one or more roles from a staff user, withdrawing the access they granted. Takes effect on their next token — an existing access token may retain the role until it expires. Revoking a root role is refused outside the root org.\n\n#### Signature\n\n```http\nPOST /user/role/remove (body) -> The updated user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ConfigAdmin`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Revocation is not instant if the user holds a valid token — force a sign-out where it matters.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ROLES_REQUIRED | Email and roles are required | `email` or `roles` is empty. | — |\n| `403` | ROOT_ORG_REQUIRED | Only the root organization can give a user a root role. Blocked: RootAdmin. | A root role or root group is named (or a custom role/group resolves to one) and the caller's org is not the root org. The sentence names the act and the blocked names; the body also carries `code: \"ROOT_ORG_REQUIRED\"` and `blocked`. | Root access is managed from the root org only. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `GET /logout/{userId}`","requestBody":{"description":"The user and roles.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"example":{"email":"ada@example.com","roles":["ContentAdmin"]}}}}}},"/profile/app/register":{"post":{"operationId":"UsersController_appRegister","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"reset","required":false,"in":"query","schema":{"type":"string"},"description":"Rotate the existing key.","example":"true"},{"name":"id","required":false,"in":"query","schema":{"type":"string"},"description":"Existing app id to update.","example":"APP-4821"}],"responses":{"201":{"description":"The registered application and its key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"app config <appId> not found for org <orgId> — The app id does not resolve for the organization.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"app config <appId> not found for org <orgId>","path":"/profile/app/register","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Register an application","description":"Registers a client application and issues its credentials. Pass `reset` to rotate an existing app's key.\n\n#### Signature\n\n```http\nPOST /profile/app/register (reset?: string, id?: string, body) -> The registered application and its key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Rotating a key invalidates the old one — deploy the new key before rotating.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | APP_CONFIG_NOT_FOUND | app config <appId> not found for org <orgId> | The app id does not resolve for the organization. | The message names both the app and the org it looked in. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /app/key`","requestBody":{"description":"The application to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Storefront web","appId":"storefront-web"}}}}}},"/user/app/register":{"post":{"operationId":"UsersController_appRegister","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"reset","required":false,"in":"query","schema":{"type":"string"},"description":"Rotate the existing key.","example":"true"},{"name":"id","required":false,"in":"query","schema":{"type":"string"},"description":"Existing app id to update.","example":"APP-4821"}],"responses":{"201":{"description":"The registered application and its key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"app config <appId> not found for org <orgId> — The app id does not resolve for the organization.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"app config <appId> not found for org <orgId>","path":"/user/app/register","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Register an application","description":"Registers a client application and issues its credentials. Pass `reset` to rotate an existing app's key.\n\n#### Signature\n\n```http\nPOST /user/app/register (reset?: string, id?: string, body) -> The registered application and its key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Rotating a key invalidates the old one — deploy the new key before rotating.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | APP_CONFIG_NOT_FOUND | app config <appId> not found for org <orgId> | The app id does not resolve for the organization. | The message names both the app and the org it looked in. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /app/key`","requestBody":{"description":"The application to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Storefront web","appId":"storefront-web"}}}}}},"/profile/app/key":{"post":{"operationId":"UsersController_appKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The application key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Get an application key","description":"Retrieves an application's key. The key authenticates the application, so handle the response as a secret.\n\n#### Signature\n\n```http\nPOST /profile/app/key (body) -> The application key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /validate-app-key`","requestBody":{"description":"Which application.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"storefront-web"}}}}}},"/user/app/key":{"post":{"operationId":"UsersController_appKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The application key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Get an application key","description":"Retrieves an application's key. The key authenticates the application, so handle the response as a secret.\n\n#### Signature\n\n```http\nPOST /user/app/key (body) -> The application key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /validate-app-key`","requestBody":{"description":"Which application.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"storefront-web"}}}}}},"/profile/app/challenge":{"post":{"operationId":"UsersController_appChallenge","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"`{ nonce, expiresAt }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"No app <appId> in this organization — The appId is not an app credential of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No app <appId> in this organization","path":"/profile/app/challenge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Get an app sign-in challenge","description":"A one-use challenge (nonce) for a phone app to sign in without a secret: the app passes it to Apple App Attest or Google Play Integrity, then sends the result to `POST /app/attest`. Valid for 2 minutes.\n\n#### Signature\n\n```http\nPOST /profile/app/challenge (body) -> `{ nonce, expiresAt }`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | APP_NOT_FOUND | No app <appId> in this organization | The appId is not an app credential of this org. | Use the App ID from App Credentials. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/attest`","requestBody":{"description":"Which app.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"shop-app"}}}}}},"/user/app/challenge":{"post":{"operationId":"UsersController_appChallenge","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"`{ nonce, expiresAt }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"No app <appId> in this organization — The appId is not an app credential of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No app <appId> in this organization","path":"/user/app/challenge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Get an app sign-in challenge","description":"A one-use challenge (nonce) for a phone app to sign in without a secret: the app passes it to Apple App Attest or Google Play Integrity, then sends the result to `POST /app/attest`. Valid for 2 minutes.\n\n#### Signature\n\n```http\nPOST /user/app/challenge (body) -> `{ nonce, expiresAt }`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | APP_NOT_FOUND | No app <appId> in this organization | The appId is not an app credential of this org. | Use the App ID from App Credentials. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/attest`","requestBody":{"description":"Which app.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"shop-app"}}}}}},"/profile/app/attest":{"post":{"operationId":"UsersController_appAttest","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"origin","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"`{ token, expiresIn: 3600, platform }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"A definite message, with `reason` (challenge_invalid, attestation_off, app_id_mismatch, nonce_mismatch, counter_not_increasing, cert_mismatch, package_mismatch, not_play_recognized, device_integrity, debug_token_invalid, web_not_configured, domain_not_allowed, missing_proof…) — The proof did not hold, the challenge was used or expired, attestation is off for the app, or (web) the page's domain is not allowed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"A definite message, with `reason` (challenge_invalid, attestation_off, app_id_mismatch, nonce_mismatch, counter_not_increasing, cert_mismatch, package_mismatch, not_play_recognized, device_integrity, debug_token_invalid, web_not_configured, domain_not_allowed, missing_proof…)","path":"/profile/app/attest","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Sign an app in with App Attest / Play Integrity","description":"Proves the calling app is the genuine build and returns a 1-hour app token (the same System token `POST /app/key` gives, with an `attest` claim naming the platform and method). iOS: send `keyId` and `attestation` the first time, then `assertion`. Android: send the Play Integrity `integrityToken` (classic request, nonce = the challenge). Development: `platform: \"debug\"` with a debug token, when the app allows them. `appId` is the app's App ID (username) or its record id. Web (the site chat widget): `platform: \"web\"`, no challenge. The site is read from the request's Origin header (set by the browser), never from the body, and must be one of the app's allowed domains (`web.domains`).\n\n#### Signature\n\n```http\nPOST /profile/app/attest (body) -> `{ token, expiresIn: 3600, platform }`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Each challenge works once.\n- Refusals are counted in the app's sign-ins (GET /app/{id}/signins).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | app_attestation_failed | A definite message, with `reason` (challenge_invalid, attestation_off, app_id_mismatch, nonce_mismatch, counter_not_increasing, cert_mismatch, package_mismatch, not_play_recognized, device_integrity, debug_token_invalid, web_not_configured, domain_not_allowed, missing_proof…) | The proof did not hold, the challenge was used or expired, attestation is off for the app, or (web) the page's domain is not allowed. | Get a new challenge and try again; check the app identity in App Credentials. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/challenge`\n- `POST /guest/auth`","requestBody":{"description":"The challenge and the platform proof.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"shop-app","nonce":"q7Vb3Zk1nXw0n5gYc2qJ8r9tLh4mPz6aEoU1sD3fGh0","platform":"ios","keyId":"base64-key-id","attestation":"base64-attestation-object"}}}}}},"/user/app/attest":{"post":{"operationId":"UsersController_appAttest","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"origin","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"`{ token, expiresIn: 3600, platform }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"A definite message, with `reason` (challenge_invalid, attestation_off, app_id_mismatch, nonce_mismatch, counter_not_increasing, cert_mismatch, package_mismatch, not_play_recognized, device_integrity, debug_token_invalid, web_not_configured, domain_not_allowed, missing_proof…) — The proof did not hold, the challenge was used or expired, attestation is off for the app, or (web) the page's domain is not allowed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"A definite message, with `reason` (challenge_invalid, attestation_off, app_id_mismatch, nonce_mismatch, counter_not_increasing, cert_mismatch, package_mismatch, not_play_recognized, device_integrity, debug_token_invalid, web_not_configured, domain_not_allowed, missing_proof…)","path":"/user/app/attest","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Sign an app in with App Attest / Play Integrity","description":"Proves the calling app is the genuine build and returns a 1-hour app token (the same System token `POST /app/key` gives, with an `attest` claim naming the platform and method). iOS: send `keyId` and `attestation` the first time, then `assertion`. Android: send the Play Integrity `integrityToken` (classic request, nonce = the challenge). Development: `platform: \"debug\"` with a debug token, when the app allows them. `appId` is the app's App ID (username) or its record id. Web (the site chat widget): `platform: \"web\"`, no challenge. The site is read from the request's Origin header (set by the browser), never from the body, and must be one of the app's allowed domains (`web.domains`).\n\n#### Signature\n\n```http\nPOST /user/app/attest (body) -> `{ token, expiresIn: 3600, platform }`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Each challenge works once.\n- Refusals are counted in the app's sign-ins (GET /app/{id}/signins).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | app_attestation_failed | A definite message, with `reason` (challenge_invalid, attestation_off, app_id_mismatch, nonce_mismatch, counter_not_increasing, cert_mismatch, package_mismatch, not_play_recognized, device_integrity, debug_token_invalid, web_not_configured, domain_not_allowed, missing_proof…) | The proof did not hold, the challenge was used or expired, attestation is off for the app, or (web) the page's domain is not allowed. | Get a new challenge and try again; check the app identity in App Credentials. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/challenge`\n- `POST /guest/auth`","requestBody":{"description":"The challenge and the platform proof.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"shop-app","nonce":"q7Vb3Zk1nXw0n5gYc2qJ8r9tLh4mPz6aEoU1sD3fGh0","platform":"ios","keyId":"base64-key-id","attestation":"base64-attestation-object"}}}}}},"/profile/app/{id}/identity":{"put":{"operationId":"UsersController_appIdentity","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"}],"responses":{"200":{"description":"The app record; Play keys shown only as `android.keysSet`, debug tokens without their hash","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Set an app's identity","description":"Partial update of how a phone app proves itself: `attestation` (off | monitor | enforce), `allowDebugTokens`, `ios { teamId, bundleId }`, `android { packageName, certSha256[], decryptionKey, verificationKey }`, `web { domains[] }`. Parts not sent stay as they are; the Play keys are replaced only when sent non-empty.\n\n#### Signature\n\n```http\nPUT /profile/app/{id}/identity (id: string, body) -> The app record; Play keys shown only as `android.keysSet`, debug tokens without their hash\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- monitor: the secret still works and attestation sign-ins and failures are recorded. enforce: `POST /app/key` is refused.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /app/attest`","requestBody":{"description":"The parts to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"attestation":"monitor","ios":{"teamId":"ABCDE12345","bundleId":"com.example.shop"}}}}}}},"/user/app/{id}/identity":{"put":{"operationId":"UsersController_appIdentity","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"}],"responses":{"200":{"description":"The app record; Play keys shown only as `android.keysSet`, debug tokens without their hash","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Set an app's identity","description":"Partial update of how a phone app proves itself: `attestation` (off | monitor | enforce), `allowDebugTokens`, `ios { teamId, bundleId }`, `android { packageName, certSha256[], decryptionKey, verificationKey }`, `web { domains[] }`. Parts not sent stay as they are; the Play keys are replaced only when sent non-empty.\n\n#### Signature\n\n```http\nPUT /user/app/{id}/identity (id: string, body) -> The app record; Play keys shown only as `android.keysSet`, debug tokens without their hash\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- monitor: the secret still works and attestation sign-ins and failures are recorded. enforce: `POST /app/key` is refused.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /app/attest`","requestBody":{"description":"The parts to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"attestation":"monitor","ios":{"teamId":"ABCDE12345","bundleId":"com.example.shop"}}}}}}},"/profile/app/{id}/debug-token":{"post":{"operationId":"UsersController_appDebugTokenCreate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"}],"responses":{"201":{"description":"`{ id, name, token }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Create a debug token","description":"A token a development build (simulator, emulator, CI) signs in with instead of App Attest / Play Integrity, while the app allows debug tokens. The token is shown once; only its hash is kept.\n\n#### Signature\n\n```http\nPOST /profile/app/{id}/debug-token (id: string, body) -> `{ id, name, token }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /app/{id}/debug-token/{tokenId}`","requestBody":{"description":"A name for the token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Ada simulator"}}}}}},"/user/app/{id}/debug-token":{"post":{"operationId":"UsersController_appDebugTokenCreate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"}],"responses":{"201":{"description":"`{ id, name, token }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Create a debug token","description":"A token a development build (simulator, emulator, CI) signs in with instead of App Attest / Play Integrity, while the app allows debug tokens. The token is shown once; only its hash is kept.\n\n#### Signature\n\n```http\nPOST /user/app/{id}/debug-token (id: string, body) -> `{ id, name, token }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /app/{id}/debug-token/{tokenId}`","requestBody":{"description":"A name for the token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Ada simulator"}}}}}},"/profile/app/{id}/debug-token/{tokenId}":{"delete":{"operationId":"UsersController_appDebugTokenDelete","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"},{"name":"tokenId","required":true,"in":"path","schema":{"type":"string"},"description":"The debug token id.","example":"9f2c4d1a7b3e5f60"}],"responses":{"200":{"description":"`{ id, deleted: true }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove a debug token","description":"The token stops signing in at once.\n\n#### Signature\n\n```http\nDELETE /profile/app/{id}/debug-token/{tokenId} (id: string, tokenId: string) -> `{ id, deleted: true }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /app/{id}/debug-token`"}},"/user/app/{id}/debug-token/{tokenId}":{"delete":{"operationId":"UsersController_appDebugTokenDelete","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"},{"name":"tokenId","required":true,"in":"path","schema":{"type":"string"},"description":"The debug token id.","example":"9f2c4d1a7b3e5f60"}],"responses":{"200":{"description":"`{ id, deleted: true }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove a debug token","description":"The token stops signing in at once.\n\n#### Signature\n\n```http\nDELETE /user/app/{id}/debug-token/{tokenId} (id: string, tokenId: string) -> `{ id, deleted: true }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /app/{id}/debug-token`"}},"/profile/app/{id}/signins":{"get":{"operationId":"UsersController_appSignins","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"},{"name":"days","required":false,"in":"query","schema":{"type":"number"},"description":"How many days (1–30, default 30).","example":"30"}],"responses":{"200":{"description":"`{ days: [{ date, secret, ios, android, debug, web, failed }], recentFailures: [{ at, platform, reason }] }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"App sign-ins by method","description":"Sign-ins per day by method (secret, iOS, Android, debug, web) and failures, for up to the last 30 days, with the 20 latest failures.\n\n#### Signature\n\n```http\nGET /profile/app/{id}/signins (id: string, days?: number) -> `{ days: [{ date, secret, ios, android, debug, web, failed }], recentFailures: [{ at, platform, reason }] }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/user/app/{id}/signins":{"get":{"operationId":"UsersController_appSignins","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The app credential record id (sk).","example":"66f1c2a9e4b0a1b2c3d4e5f6"},{"name":"days","required":false,"in":"query","schema":{"type":"number"},"description":"How many days (1–30, default 30).","example":"30"}],"responses":{"200":{"description":"`{ days: [{ date, secret, ios, android, debug, web, failed }], recentFailures: [{ at, platform, reason }] }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"App sign-ins by method","description":"Sign-ins per day by method (secret, iOS, Android, debug, web) and failures, for up to the last 30 days, with the 20 latest failures.\n\n#### Signature\n\n```http\nGET /user/app/{id}/signins (id: string, days?: number) -> `{ days: [{ date, secret, ios, android, debug, web, failed }], recentFailures: [{ at, platform, reason }] }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/profile/validate-app-key":{"post":{"operationId":"UsersController_validateAppKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the key is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Validate an application key","description":"Checks whether an application key is valid and active — what a client calls to confirm its credentials before relying on them.\n\n#### Signature\n\n```http\nPOST /profile/validate-app-key (body) -> Whether the key is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/key`","requestBody":{"description":"The key to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"storefront-web","key":"ak_9k2m4h1p7q"}}}}}},"/user/validate-app-key":{"post":{"operationId":"UsersController_validateAppKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the key is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Validate an application key","description":"Checks whether an application key is valid and active — what a client calls to confirm its credentials before relying on them.\n\n#### Signature\n\n```http\nPOST /user/validate-app-key (body) -> Whether the key is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /app/key`","requestBody":{"description":"The key to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"appId":"storefront-web","key":"ak_9k2m4h1p7q"}}}}}},"/profile/customer/signin":{"post":{"operationId":"UsersController_customerSignin","summary":"Customer sign in","description":"Authenticates a customer. Customers are a separate population from users — a customer account does not grant access to the back office.\n\n#### Signature\n\n```http\nPOST /profile/customer/signin (body) -> Tokens and the customer\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signup`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","password":"…"}}}},"responses":{"201":{"description":"Tokens and the customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/profile/customer/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/profile/customer/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"]}},"/user/customer/signin":{"post":{"operationId":"UsersController_customerSignin","summary":"Customer sign in","description":"Authenticates a customer. Customers are a separate population from users — a customer account does not grant access to the back office.\n\n#### Signature\n\n```http\nPOST /user/customer/signin (body) -> Tokens and the customer\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n| `403` | ACCOUNT_LOCKED | This account is locked. Ask the business owner to unlock it. | The account has been locked, typically after repeated failed attempts. | An operator must unlock it. Retrying does not help. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signup`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","password":"…"}}}},"responses":{"201":{"description":"Tokens and the customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/user/customer/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This account is locked. Ask the business owner to unlock it. — The account has been locked, typically after repeated failed attempts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This account is locked. Ask the business owner to unlock it.","path":"/user/customer/signin","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"]}},"/profile/customer/shared-account":{"post":{"operationId":"UsersController_setSharedAccount","summary":"Choose the account a customer buys for","description":"Switches a signed-in customer between buying as themselves and buying for a shared account they are associated with (`data.sharedAccounts`). Returns the customer with a re-issued token pair carrying the choice — store them in place of the current ones. Send no `accountId` to go back to buying as themselves.\n\n#### Signature\n\n```http\nPOST /profile/customer/shared-account (body) -> { customer, token, refreshToken, orgId }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | NOT_SIGNED_IN | Not signed in | No customer session. | — |\n| `403` | NOT_ASSOCIATED | You are not associated with this account | `accountId` is not one of the customer's shared accounts. | — |\n| `404` | CUSTOMER_NOT_FOUND | Customer not found | The customer record is gone. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ customer, token, refreshToken, orgId }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Not signed in — No customer session.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Not signed in","path":"/profile/customer/shared-account","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"You are not associated with this account — `accountId` is not one of the customer's shared accounts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You are not associated with this account","path":"/profile/customer/shared-account","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Customer not found — The customer record is gone.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Customer not found","path":"/profile/customer/shared-account","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"requestBody":{"description":"The shared account, or nothing.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"}}},"example":{"accountId":"acct_9k2m4h"}}}}}},"/user/customer/shared-account":{"post":{"operationId":"UsersController_setSharedAccount","summary":"Choose the account a customer buys for","description":"Switches a signed-in customer between buying as themselves and buying for a shared account they are associated with (`data.sharedAccounts`). Returns the customer with a re-issued token pair carrying the choice — store them in place of the current ones. Send no `accountId` to go back to buying as themselves.\n\n#### Signature\n\n```http\nPOST /user/customer/shared-account (body) -> { customer, token, refreshToken, orgId }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | NOT_SIGNED_IN | Not signed in | No customer session. | — |\n| `403` | NOT_ASSOCIATED | You are not associated with this account | `accountId` is not one of the customer's shared accounts. | — |\n| `404` | CUSTOMER_NOT_FOUND | Customer not found | The customer record is gone. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ customer, token, refreshToken, orgId }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Not signed in — No customer session.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Not signed in","path":"/user/customer/shared-account","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"You are not associated with this account — `accountId` is not one of the customer's shared accounts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You are not associated with this account","path":"/user/customer/shared-account","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Customer not found — The customer record is gone.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Customer not found","path":"/user/customer/shared-account","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"requestBody":{"description":"The shared account, or nothing.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"}}},"example":{"accountId":"acct_9k2m4h"}}}}}},"/profile/customer/dashboard/auth/{authOrgId}":{"post":{"operationId":"UsersController_customerDashboardAuth","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"authOrgId","required":true,"in":"path","schema":{"type":"string"},"description":"Organization to authenticate against.","example":"acme-retail"}],"responses":{"201":{"description":"Tokens for that organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Authenticate a customer for a dashboard","description":"Authenticates a customer against another organization's dashboard — the cross-org hop for a shared portal.\n\n#### Signature\n\n```http\nPOST /profile/customer/dashboard/auth/{authOrgId} (authOrgId: string, body) -> Tokens for that organization\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/signin`","requestBody":{"description":"Auth context.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/user/customer/dashboard/auth/{authOrgId}":{"post":{"operationId":"UsersController_customerDashboardAuth","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"authOrgId","required":true,"in":"path","schema":{"type":"string"},"description":"Organization to authenticate against.","example":"acme-retail"}],"responses":{"201":{"description":"Tokens for that organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Authenticate a customer for a dashboard","description":"Authenticates a customer against another organization's dashboard — the cross-org hop for a shared portal.\n\n#### Signature\n\n```http\nPOST /user/customer/dashboard/auth/{authOrgId} (authOrgId: string, body) -> Tokens for that organization\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/signin`","requestBody":{"description":"Auth context.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/profile/user/shared-site-auth/{token}":{"get":{"operationId":"UsersController_userSharedSiteAuth","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"Shared-site auth token.","example":"sst_9k2m4h1p7q"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Authenticate via a shared-site token","description":"Signs a user in from a token issued by another site in the same estate — the cross-site single sign-on hop. The token is a bearer credential in a URL, so it should be short-lived and single-use.\n\n#### Signature\n\n```http\nGET /profile/user/shared-site-auth/{token} (token: string) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Credentials in URLs leak through logs and referrers — keep the lifetime short.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signin`"}},"/user/user/shared-site-auth/{token}":{"get":{"operationId":"UsersController_userSharedSiteAuth","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"Shared-site auth token.","example":"sst_9k2m4h1p7q"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Authenticate via a shared-site token","description":"Signs a user in from a token issued by another site in the same estate — the cross-site single sign-on hop. The token is a bearer credential in a URL, so it should be short-lived and single-use.\n\n#### Signature\n\n```http\nGET /user/user/shared-site-auth/{token} (token: string) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Credentials in URLs leak through logs and referrers — keep the lifetime short.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /signin`"}},"/profile/global-login":{"post":{"operationId":"UsersController_globalLogin","summary":"Global login","description":"Authenticates across organizations rather than within one — for a user who belongs to several and has not yet chosen.\n\n#### Signature\n\n```http\nPOST /profile/global-login (body) -> Tokens and the organizations available\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /system-orgs`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","password":"…"}}}},"responses":{"201":{"description":"Tokens and the organizations available","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/profile/global-login","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/global-login":{"post":{"operationId":"UsersController_globalLogin","summary":"Global login","description":"Authenticates across organizations rather than within one — for a user who belongs to several and has not yet chosen.\n\n#### Signature\n\n```http\nPOST /user/global-login (body) -> Tokens and the organizations available\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_CREDENTIALS | Invalid username or password | The identifier or password is wrong. | Deliberately does not distinguish an unknown account from a wrong password — do not surface a more specific message to the caller. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /system-orgs`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Credentials.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","password":"…"}}}},"responses":{"201":{"description":"Tokens and the organizations available","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"Invalid username or password — The identifier or password is wrong.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid username or password","path":"/user/global-login","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/customer/signup":{"post":{"operationId":"UsersController_customerSignup","summary":"Customer sign up","description":"Registers a customer account.\n\n#### Signature\n\n```http\nPOST /profile/customer/signup (body) -> The created customer\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CUSTOMER_EXISTS | A customer with this email already exists in the organization | The email is already registered as a customer. | Sign in instead. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signin`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The account to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","password":"…","firstName":"Ada"}}}},"responses":{"201":{"description":"The created customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"A customer with this email already exists in the organization — The email is already registered as a customer.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A customer with this email already exists in the organization","path":"/profile/customer/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"]}},"/user/customer/signup":{"post":{"operationId":"UsersController_customerSignup","summary":"Customer sign up","description":"Registers a customer account.\n\n#### Signature\n\n```http\nPOST /user/customer/signup (body) -> The created customer\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CUSTOMER_EXISTS | A customer with this email already exists in the organization | The email is already registered as a customer. | Sign in instead. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signin`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The account to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","password":"…","firstName":"Ada"}}}},"responses":{"201":{"description":"The created customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"400":{"description":"A customer with this email already exists in the organization — The email is already registered as a customer.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A customer with this email already exists in the organization","path":"/user/customer/signup","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"]}},"/profile/customer/refresh":{"post":{"operationId":"UsersController_customerRefreshToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"New tokens","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Refresh a customer token","description":"Exchanges a customer refresh token for a new access token.\n\n#### Signature\n\n```http\nPOST /profile/customer/refresh (body) -> New tokens\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signin`","requestBody":{"description":"The refresh token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"refreshToken":"eyJhbGciOi…"}}}}}},"/user/customer/refresh":{"post":{"operationId":"UsersController_customerRefreshToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"New tokens","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Refresh a customer token","description":"Exchanges a customer refresh token for a new access token.\n\n#### Signature\n\n```http\nPOST /user/customer/refresh (body) -> New tokens\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signin`","requestBody":{"description":"The refresh token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"refreshToken":"eyJhbGciOi…"}}}}}},"/profile/customer/subscribe":{"post":{"operationId":"UsersController_customerSubscribe","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Subscribe a customer","description":"Records a customer opting in to marketing. Capture what they consented to — see the promotions endpoints, which store the consent text.\n\n#### Signature\n\n```http\nPOST /profile/customer/subscribe (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/promotions/{name}/subscribe`","requestBody":{"description":"The subscription.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}}}},"/user/customer/subscribe":{"post":{"operationId":"UsersController_customerSubscribe","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Subscribe a customer","description":"Records a customer opting in to marketing. Capture what they consented to — see the promotions endpoints, which store the consent text.\n\n#### Signature\n\n```http\nPOST /user/customer/subscribe (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/promotions/{name}/subscribe`","requestBody":{"description":"The subscription.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}}}},"/profile/customer/unsubscribe":{"post":{"operationId":"UsersController_customerUnsubscribe","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Unsubscribe a customer","description":"Records a customer opting out. Honour it promptly and completely.\n\n#### Signature\n\n```http\nPOST /profile/customer/unsubscribe (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/subscribe`","requestBody":{"description":"The unsubscribe request.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}}}},"/user/customer/unsubscribe":{"post":{"operationId":"UsersController_customerUnsubscribe","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Unsubscribe a customer","description":"Records a customer opting out. Honour it promptly and completely.\n\n#### Signature\n\n```http\nPOST /user/customer/unsubscribe (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/subscribe`","requestBody":{"description":"The unsubscribe request.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}}}},"/profile/customer/update":{"post":{"operationId":"UsersController_customerUpdate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated customer","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Update a customer","description":"Updates a customer record.\n\n#### Signature\n\n```http\nPOST /profile/customer/update (body) -> The updated customer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /customer/profile/{emailOrUsername}`","requestBody":{"description":"The customer to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada"}}}}}},"/user/customer/update":{"post":{"operationId":"UsersController_customerUpdate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated customer","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Update a customer","description":"Updates a customer record.\n\n#### Signature\n\n```http\nPOST /user/customer/update (body) -> The updated customer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /customer/profile/{emailOrUsername}`","requestBody":{"description":"The customer to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada"}}}}}},"/profile/customer/merge":{"post":{"operationId":"UsersController_customerMerge","summary":"Merge duplicate contacts","description":"Saves the merged fields on the contact being kept first, then moves the duplicates to the trash. An email or username the kept contact takes over from a duplicate is handed across. Body: { keepId, mergeIds: [...], data: { changed fields } }. Answers { customer, removed, failed }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/user/customer/merge":{"post":{"operationId":"UsersController_customerMerge","summary":"Merge duplicate contacts","description":"Saves the merged fields on the contact being kept first, then moves the duplicates to the trash. An email or username the kept contact takes over from a duplicate is handed across. Body: { keepId, mergeIds: [...], data: { changed fields } }. Answers { customer, removed, failed }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/profile/customer/password/temporary":{"post":{"operationId":"UsersController_customerTemporaryPassword","summary":"Give a contact a temporary password","description":"Staff set a one-time password the contact must change at next sign-in. The password is sent in the body (never the URL), must meet the contact's password policy, and needs confirmed: true. Body: { customerId, password, confirmed }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/user/customer/password/temporary":{"post":{"operationId":"UsersController_customerTemporaryPassword","summary":"Give a contact a temporary password","description":"Staff set a one-time password the contact must change at next sign-in. The password is sent in the body (never the URL), must meet the contact's password policy, and needs confirmed: true. Body: { customerId, password, confirmed }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Users"]}},"/profile/customer/password/change":{"post":{"operationId":"UsersController_customerPasswordChange","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Change a customer password","description":"Changes a customer's password, requiring the current one.\n\n#### Signature\n\n```http\nPOST /profile/customer/password/change (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/reset`","requestBody":{"description":"Current and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"currentPassword":"…","newPassword":"…"}}}}}},"/user/customer/password/change":{"post":{"operationId":"UsersController_customerPasswordChange","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Change a customer password","description":"Changes a customer's password, requiring the current one.\n\n#### Signature\n\n```http\nPOST /user/customer/password/change (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/reset`","requestBody":{"description":"Current and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"currentPassword":"…","newPassword":"…"}}}}}},"/profile/customer/password/reset":{"post":{"operationId":"UsersController_customerPasswordReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Reset a customer password","description":"Sets a new customer password using a reset token.\n\n#### Signature\n\n```http\nPOST /profile/customer/password/reset (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/validate-token`","requestBody":{"description":"Token and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q","newPassword":"…"}}}}}},"/user/customer/password/reset":{"post":{"operationId":"UsersController_customerPasswordReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"Client context recorded against the attempt — used for device tracking and blocking.","schema":{"type":"string"},"example":"web/1.4.2"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Reset a customer password","description":"Sets a new customer password using a reset token.\n\n#### Signature\n\n```http\nPOST /user/customer/password/reset (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/validate-token`","requestBody":{"description":"Token and new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q","newPassword":"…"}}}}}},"/profile/customer/password/validate-token":{"post":{"operationId":"UsersController_customerValidateResetToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the token is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Validate a customer reset token","description":"Checks a customer reset token before showing the reset form.\n\n#### Signature\n\n```http\nPOST /profile/customer/password/validate-token (body) -> Whether the token is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/reset`","requestBody":{"description":"The token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q"}}}}}},"/user/customer/password/validate-token":{"post":{"operationId":"UsersController_customerValidateResetToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the token is valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Validate a customer reset token","description":"Checks a customer reset token before showing the reset form.\n\n#### Signature\n\n```http\nPOST /user/customer/password/validate-token (body) -> Whether the token is valid\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/reset`","requestBody":{"description":"The token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"rst_9k2m4h1p7q"}}}}}},"/profile/customer/social-login":{"post":{"operationId":"UsersController_customerValidateSocialLobin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Tokens and the customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Validate a customer social login","description":"Completes a social sign-in for a customer across providers. Server-to-server only: the caller must be the org's own site/app login (its app token in Authorization, for the org in the orgid header). Anonymous callers get 401; customers, staff and other orgs' app tokens get 403. The site's server reads the profile from the provider itself.\n\n#### Signature\n\n```http\nPOST /profile/customer/social-login (body) -> Tokens and the customer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/google/token`","requestBody":{"description":"The profile the site's server read from the provider.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"user":{"email":"pat@example.com","name":"Pat Lee","emailVerified":true},"account":{"provider":"github","providerAccountId":"12345"}}}}}}},"/user/customer/social-login":{"post":{"operationId":"UsersController_customerValidateSocialLobin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Tokens and the customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Validate a customer social login","description":"Completes a social sign-in for a customer across providers. Server-to-server only: the caller must be the org's own site/app login (its app token in Authorization, for the org in the orgid header). Anonymous callers get 401; customers, staff and other orgs' app tokens get 403. The site's server reads the profile from the provider itself.\n\n#### Signature\n\n```http\nPOST /user/customer/social-login (body) -> Tokens and the customer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/google/token`","requestBody":{"description":"The profile the site's server read from the provider.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"user":{"email":"pat@example.com","name":"Pat Lee","emailVerified":true},"account":{"provider":"github","providerAccountId":"12345"}}}}}}},"/profile/customer/password/forgot/{email}/{redirectUrl}":{"get":{"operationId":"UsersController_customerPasswordForgot","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"},{"name":"redirectUrl","required":true,"in":"path","schema":{"type":"string"},"description":"Where to return the customer after reset.","example":"https%3A%2F%2Fshop.example.com%2Freset"},{"name":"strategy","required":true,"in":"query","schema":{"type":"string"}},{"name":"password","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Request a customer password reset","description":"Sends a customer a reset link, returning them to the supplied URL. **Validate `redirectUrl` against an allowlist** — an unchecked redirect in a password-reset email is a phishing vector.\n\n#### Signature\n\n```http\nGET /profile/customer/password/forgot/{email}/{redirectUrl} (email: string, redirectUrl: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- An open redirect here lands in a trusted email. Restrict the accepted hosts.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/reset`"}},"/user/customer/password/forgot/{email}/{redirectUrl}":{"get":{"operationId":"UsersController_customerPasswordForgot","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"},{"name":"redirectUrl","required":true,"in":"path","schema":{"type":"string"},"description":"Where to return the customer after reset.","example":"https%3A%2F%2Fshop.example.com%2Freset"},{"name":"strategy","required":true,"in":"query","schema":{"type":"string"}},{"name":"password","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Request a customer password reset","description":"Sends a customer a reset link, returning them to the supplied URL. **Validate `redirectUrl` against an allowlist** — an unchecked redirect in a password-reset email is a phishing vector.\n\n#### Signature\n\n```http\nGET /user/customer/password/forgot/{email}/{redirectUrl} (email: string, redirectUrl: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- An open redirect here lands in a trusted email. Restrict the accepted hosts.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/password/reset`"}},"/profile/customers/{attr}/{value}":{"get":{"operationId":"UsersController_customers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"attr","required":true,"in":"path","schema":{"type":"string"},"description":"Attribute to match.","example":"city"},{"name":"value","required":true,"in":"path","schema":{"type":"string"},"description":"Value to match.","example":"London"}],"responses":{"200":{"description":"Matching customers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Find customers by attribute","description":"Finds customers matching an attribute and value.\n\n#### Signature\n\n```http\nGET /profile/customers/{attr}/{value} (attr: string, value: string) -> Matching customers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /customer/profile/{emailOrUsername}`"}},"/user/customers/{attr}/{value}":{"get":{"operationId":"UsersController_customers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"attr","required":true,"in":"path","schema":{"type":"string"},"description":"Attribute to match.","example":"city"},{"name":"value","required":true,"in":"path","schema":{"type":"string"},"description":"Value to match.","example":"London"}],"responses":{"200":{"description":"Matching customers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Find customers by attribute","description":"Finds customers matching an attribute and value.\n\n#### Signature\n\n```http\nGET /user/customers/{attr}/{value} (attr: string, value: string) -> Matching customers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /customer/profile/{emailOrUsername}`"}},"/profile/customer/exist/{emailOrUsername}":{"get":{"operationId":"UsersController_customerExist","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"}],"responses":{"200":{"description":"Whether the customer exists","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Check whether a customer exists","description":"Reports whether a customer account exists. This confirms account existence to an unauthenticated caller — rate-limit anything built on it.\n\n#### Signature\n\n```http\nGET /profile/customer/exist/{emailOrUsername} (emailOrUsername: string) -> Whether the customer exists\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- An enumeration surface by design — treat it accordingly.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signup`"}},"/user/customer/exist/{emailOrUsername}":{"get":{"operationId":"UsersController_customerExist","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"}],"responses":{"200":{"description":"Whether the customer exists","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Check whether a customer exists","description":"Reports whether a customer account exists. This confirms account existence to an unauthenticated caller — rate-limit anything built on it.\n\n#### Signature\n\n```http\nGET /user/customer/exist/{emailOrUsername} (emailOrUsername: string) -> Whether the customer exists\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- An enumeration surface by design — treat it accordingly.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/signup`"}},"/profile/customer/profile/{emailOrUsername}":{"get":{"operationId":"UsersController_customerProfile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"}],"responses":{"200":{"description":"The customer profile","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Get a customer profile","description":"Fetches a customer profile by email or username.\n\n#### Signature\n\n```http\nGET /profile/customer/profile/{emailOrUsername} (emailOrUsername: string) -> The customer profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/update`"},"delete":{"operationId":"UsersController_deleteCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"},{"name":"reason","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Delete a customer","description":"Deletes a customer account properly — the endpoint the generic repository delete points at rather than dropping the row.\n\n#### Signature\n\n```http\nDELETE /profile/customer/profile/{emailOrUsername} (emailOrUsername: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/delete/{datatype}/{id}`"}},"/user/customer/profile/{emailOrUsername}":{"get":{"operationId":"UsersController_customerProfile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"}],"responses":{"200":{"description":"The customer profile","content":{"application/json":{"schema":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Get a customer profile","description":"Fetches a customer profile by email or username.\n\n#### Signature\n\n```http\nGET /user/customer/profile/{emailOrUsername} (emailOrUsername: string) -> The customer profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /customer/update`"},"delete":{"operationId":"UsersController_deleteCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"emailOrUsername","required":true,"in":"path","schema":{"type":"string"},"description":"Email address or username.","example":"ada@example.com"},{"name":"reason","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Delete a customer","description":"Deletes a customer account properly — the endpoint the generic repository delete points at rather than dropping the row.\n\n#### Signature\n\n```http\nDELETE /user/customer/profile/{emailOrUsername} (emailOrUsername: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /repository/delete/{datatype}/{id}`"}},"/profile/customer/self":{"delete":{"operationId":"UsersController_deleteSelfCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Delete my customer account","description":"Deletes the calling customer's own account. Irreversible.\n\n#### Signature\n\n```http\nDELETE /profile/customer/self () -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /customer/profile/{emailOrUsername}`"}},"/user/customer/self":{"delete":{"operationId":"UsersController_deleteSelfCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Delete my customer account","description":"Deletes the calling customer's own account. Irreversible.\n\n#### Signature\n\n```http\nDELETE /user/customer/self () -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /customer/profile/{emailOrUsername}`"}},"/profile/blacklist/get":{"get":{"operationId":"UsersController_blacklistGet","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Blacklist entries","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Get the blacklist","description":"The blocked devices, addresses and API keys. Blocked entries are refused at sign-in before credentials are checked.\n\n#### Signature\n\n```http\nGET /profile/blacklist/get () -> Blacklist entries\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /blacklist/add`"}},"/user/blacklist/get":{"get":{"operationId":"UsersController_blacklistGet","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Blacklist entries","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Get the blacklist","description":"The blocked devices, addresses and API keys. Blocked entries are refused at sign-in before credentials are checked.\n\n#### Signature\n\n```http\nGET /user/blacklist/get () -> Blacklist entries\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /blacklist/add`"}},"/profile/blacklist/add":{"post":{"operationId":"UsersController_blacklistAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The blacklist entry","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Add to the blacklist","description":"Blocks a device or identifier from authenticating. Takes effect immediately and refuses sign-in before credentials are evaluated.\n\n#### Signature\n\n```http\nPOST /profile/blacklist/add (body) -> The blacklist entry\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Blocking broadly — a shared IP, say — can lock out legitimate users.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /blacklist/delete/{value}`","requestBody":{"description":"What to block.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"value":"203.0.113.42","type":"ip","reason":"Credential stuffing"}}}}}},"/user/blacklist/add":{"post":{"operationId":"UsersController_blacklistAdd","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The blacklist entry","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Add to the blacklist","description":"Blocks a device or identifier from authenticating. Takes effect immediately and refuses sign-in before credentials are evaluated.\n\n#### Signature\n\n```http\nPOST /user/blacklist/add (body) -> The blacklist entry\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Blocking broadly — a shared IP, say — can lock out legitimate users.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /blacklist/delete/{value}`","requestBody":{"description":"What to block.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"value":"203.0.113.42","type":"ip","reason":"Credential stuffing"}}}}}},"/profile/blacklist/delete/{value}":{"delete":{"operationId":"UsersController_blacklistRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"value","required":true,"in":"path","schema":{"type":"string"},"description":"The blacklisted value.","example":"203.0.113.42"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove from the blacklist","description":"Unblocks a previously blacklisted value.\n\n#### Signature\n\n```http\nDELETE /profile/blacklist/delete/{value} (value: string) -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /blacklist/add`"}},"/user/blacklist/delete/{value}":{"delete":{"operationId":"UsersController_blacklistRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"value","required":true,"in":"path","schema":{"type":"string"},"description":"The blacklisted value.","example":"203.0.113.42"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Remove from the blacklist","description":"Unblocks a previously blacklisted value.\n\n#### Signature\n\n```http\nDELETE /user/blacklist/delete/{value} (value: string) -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /blacklist/add`"}},"/profile/blacklist/apikey/add":{"post":{"operationId":"UsersController_blacklistApiKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The blacklist entry","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Blacklist an API key","description":"Blocks an API key — the immediate response to a leaked credential, and faster than rotating it everywhere.\n\n#### Signature\n\n```http\nPOST /profile/blacklist/apikey/add (body) -> The blacklist entry\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /blacklist/apikey/delete/{apiKey}`","requestBody":{"description":"The key to block.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"apiKey":"ak_9k2m4h1p7q","reason":"Leaked in a public repository"}}}}}},"/user/blacklist/apikey/add":{"post":{"operationId":"UsersController_blacklistApiKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The blacklist entry","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Blacklist an API key","description":"Blocks an API key — the immediate response to a leaked credential, and faster than rotating it everywhere.\n\n#### Signature\n\n```http\nPOST /user/blacklist/apikey/add (body) -> The blacklist entry\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /blacklist/apikey/delete/{apiKey}`","requestBody":{"description":"The key to block.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"apiKey":"ak_9k2m4h1p7q","reason":"Leaked in a public repository"}}}}}},"/profile/blacklist/apikey/delete/{apiKey}":{"delete":{"operationId":"UsersController_unblacklistApiKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"apiKey","required":true,"in":"path","schema":{"type":"string"},"description":"The blocked key.","example":"ak_9k2m4h1p7q"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Unblacklist an API key","description":"Restores a blocked API key.\n\n#### Signature\n\n```http\nDELETE /profile/blacklist/apikey/delete/{apiKey} (apiKey: string) -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /blacklist/apikey/add`"}},"/user/blacklist/apikey/delete/{apiKey}":{"delete":{"operationId":"UsersController_unblacklistApiKey","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"apiKey","required":true,"in":"path","schema":{"type":"string"},"description":"The blocked key.","example":"ak_9k2m4h1p7q"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Administration"],"summary":"Unblacklist an API key","description":"Restores a blocked API key.\n\n#### Signature\n\n```http\nDELETE /user/blacklist/apikey/delete/{apiKey} (apiKey: string) -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /blacklist/apikey/add`"}},"/profile/code/{email}":{"get":{"operationId":"UsersController_codeLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Request a login code","description":"Sends a one-time login code to an email address — passwordless sign-in.\n\n#### Signature\n\n```http\nGET /profile/code/{email} (email: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit per address and per IP.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /magic-link`"}},"/user/code/{email}":{"get":{"operationId":"UsersController_codeLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Email address.","example":"ada@example.com"}],"responses":{"200":{"description":"The request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Request a login code","description":"Sends a one-time login code to an email address — passwordless sign-in.\n\n#### Signature\n\n```http\nGET /user/code/{email} (email: string) -> The request result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rate-limit per address and per IP.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /magic-link`"}},"/profile/magic-link":{"get":{"operationId":"UsersController_magicLinkLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"email","required":true,"in":"query","schema":{"type":"string"}},{"name":"type","required":true,"in":"query","schema":{"type":"string"}},{"name":"deliveryType","required":true,"in":"query","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"Magic link token.","schema":{"type":"string"},"example":"mlk_9k2m4h1p7q"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Sign in with a magic link","description":"Completes a passwordless sign-in from an emailed link. The link is a credential — anyone with it is signed in, so keep it short-lived.\n\n#### Signature\n\n```http\nGET /profile/magic-link (token?: string) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /magic-link/redirect`"}},"/user/magic-link":{"get":{"operationId":"UsersController_magicLinkLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"email","required":true,"in":"query","schema":{"type":"string"}},{"name":"type","required":true,"in":"query","schema":{"type":"string"}},{"name":"deliveryType","required":true,"in":"query","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"Magic link token.","schema":{"type":"string"},"example":"mlk_9k2m4h1p7q"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Sign in with a magic link","description":"Completes a passwordless sign-in from an emailed link. The link is a credential — anyone with it is signed in, so keep it short-lived.\n\n#### Signature\n\n```http\nGET /user/magic-link (token?: string) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /magic-link/redirect`"}},"/profile/magic-link/redirect":{"post":{"operationId":"UsersController_magicLinkLoginRedirect","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"The redirect result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Redirect after a magic link","description":"Completes the magic-link flow and redirects the browser onward.\n\n#### Signature\n\n```http\nPOST /profile/magic-link/redirect (body) -> The redirect result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /magic-link`","requestBody":{"description":"The token and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"mlk_9k2m4h1p7q","redirectUrl":"https://app.example.com/"}}}}}},"/user/magic-link/redirect":{"post":{"operationId":"UsersController_magicLinkLoginRedirect","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"The redirect result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Redirect after a magic link","description":"Completes the magic-link flow and redirects the browser onward.\n\n#### Signature\n\n```http\nPOST /user/magic-link/redirect (body) -> The redirect result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /magic-link`","requestBody":{"description":"The token and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"mlk_9k2m4h1p7q","redirectUrl":"https://app.example.com/"}}}}}},"/profile/user/magic-link":{"get":{"operationId":"UsersController_magicLinkUserLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"query","schema":{"type":"string"}},{"name":"type","required":true,"in":"query","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"schema":{"type":"string"},"example":"mlk_9k2m4h1p7q"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Sign in with a magic link (user)","description":"The user-scoped magic-link sign-in, distinct from the customer flow.\n\n#### Signature\n\n```http\nGET /profile/user/magic-link (token?: string) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/magic-link/redirect`"}},"/user/user/magic-link":{"get":{"operationId":"UsersController_magicLinkUserLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"query","schema":{"type":"string"}},{"name":"type","required":true,"in":"query","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"schema":{"type":"string"},"example":"mlk_9k2m4h1p7q"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Sign in with a magic link (user)","description":"The user-scoped magic-link sign-in, distinct from the customer flow.\n\n#### Signature\n\n```http\nGET /user/user/magic-link (token?: string) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /user/magic-link/redirect`"}},"/profile/user/magic-link/redirect":{"post":{"operationId":"UsersController_magicLinkUserRedirect","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The redirect result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Redirect after a user magic link","description":"Completes the user magic-link flow and redirects onward.\n\n#### Signature\n\n```http\nPOST /profile/user/magic-link/redirect (body) -> The redirect result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /user/magic-link`","requestBody":{"description":"The token and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"mlk_9k2m4h1p7q"}}}}}},"/user/user/magic-link/redirect":{"post":{"operationId":"UsersController_magicLinkUserRedirect","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The redirect result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Redirect after a user magic link","description":"Completes the user magic-link flow and redirects onward.\n\n#### Signature\n\n```http\nPOST /user/user/magic-link/redirect (body) -> The redirect result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /user/magic-link`","requestBody":{"description":"The token and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"mlk_9k2m4h1p7q"}}}}}},"/profile/facebook/url":{"get":{"operationId":"UsersController_facebookAuthUrl","summary":"Get the Facebook auth URL","description":"Returns the URL to send a browser to for Facebook sign-in, for clients that redirect themselves.\n\n#### Signature\n\n```http\nGET /profile/facebook/url () -> The auth URL\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /facebook`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The auth URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/facebook/url":{"get":{"operationId":"UsersController_facebookAuthUrl","summary":"Get the Facebook auth URL","description":"Returns the URL to send a browser to for Facebook sign-in, for clients that redirect themselves.\n\n#### Signature\n\n```http\nGET /user/facebook/url () -> The auth URL\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /facebook`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The auth URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/facebook":{"get":{"operationId":"UsersController_facebookLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Redirect to Facebook","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Start Facebook sign-in","description":"Begins the Facebook OAuth flow.\n\n#### Signature\n\n```http\nGET /profile/facebook () -> Redirect to Facebook\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /facebook/redirect`"}},"/user/facebook":{"get":{"operationId":"UsersController_facebookLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Redirect to Facebook","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Start Facebook sign-in","description":"Begins the Facebook OAuth flow.\n\n#### Signature\n\n```http\nGET /user/facebook () -> Redirect to Facebook\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /facebook/redirect`"}},"/profile/facebook/redirect":{"get":{"operationId":"UsersController_facebookLoginCallback","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Facebook sign-in callback","description":"Handles Facebook's OAuth callback and issues tokens.\n\n#### Signature\n\n```http\nGET /profile/facebook/redirect () -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /facebook/token`"}},"/user/facebook/redirect":{"get":{"operationId":"UsersController_facebookLoginCallback","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Facebook sign-in callback","description":"Handles Facebook's OAuth callback and issues tokens.\n\n#### Signature\n\n```http\nGET /user/facebook/redirect () -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /facebook/token`"}},"/profile/facebook/token":{"post":{"operationId":"UsersController_facebookTokenExchange","summary":"Exchange a Facebook token","description":"Exchanges a Facebook access token for platform tokens — the native-app flow, where the SDK obtains the token rather than a browser redirect.\n\n#### Signature\n\n```http\nPOST /profile/facebook/token (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Verify the token with the provider — a client-supplied token is not evidence on its own.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /facebook/redirect`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The provider token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"accessToken":"EAAG…"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/facebook/token":{"post":{"operationId":"UsersController_facebookTokenExchange","summary":"Exchange a Facebook token","description":"Exchanges a Facebook access token for platform tokens — the native-app flow, where the SDK obtains the token rather than a browser redirect.\n\n#### Signature\n\n```http\nPOST /user/facebook/token (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Verify the token with the provider — a client-supplied token is not evidence on its own.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /facebook/redirect`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The provider token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"accessToken":"EAAG…"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/google":{"get":{"operationId":"UsersController_googleLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Redirect to Google","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Start Google sign-in","description":"Begins the Google OAuth flow.\n\n#### Signature\n\n```http\nGET /profile/google () -> Redirect to Google\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /google/redirect`"}},"/user/google":{"get":{"operationId":"UsersController_googleLogin","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Redirect to Google","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Start Google sign-in","description":"Begins the Google OAuth flow.\n\n#### Signature\n\n```http\nGET /user/google () -> Redirect to Google\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /google/redirect`"}},"/profile/google/redirect":{"get":{"operationId":"UsersController_googleLoginCallback","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Google sign-in callback","description":"Handles Google's OAuth callback and issues tokens.\n\n#### Signature\n\n```http\nGET /profile/google/redirect () -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/google/token`"}},"/user/google/redirect":{"get":{"operationId":"UsersController_googleLoginCallback","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Google sign-in callback","description":"Handles Google's OAuth callback and issues tokens.\n\n#### Signature\n\n```http\nGET /user/google/redirect () -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/google/token`"}},"/profile/customer/google/token":{"post":{"operationId":"UsersController_customerGoogleTokenExchange","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Tokens and the customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Exchange a Google token for a customer","description":"Exchanges a Google token for customer tokens — the native-app sign-in path.\n\n#### Signature\n\n```http\nPOST /profile/customer/google/token (body) -> Tokens and the customer\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Verify the token with Google rather than trusting the client.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/social-login`","requestBody":{"description":"The provider token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"idToken":"eyJhbGciOi…"}}}}}},"/user/customer/google/token":{"post":{"operationId":"UsersController_customerGoogleTokenExchange","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Tokens and the customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Customers"],"summary":"Exchange a Google token for a customer","description":"Exchanges a Google token for customer tokens — the native-app sign-in path.\n\n#### Signature\n\n```http\nPOST /user/customer/google/token (body) -> Tokens and the customer\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Verify the token with Google rather than trusting the client.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /customer/social-login`","requestBody":{"description":"The provider token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"idToken":"eyJhbGciOi…"}}}}}},"/profile/github/url":{"get":{"operationId":"UsersController_githubAuthUrl","summary":"Get the GitHub auth URL","description":"Returns the URL to send a browser to for GitHub sign-in.\n\n#### Signature\n\n```http\nGET /profile/github/url () -> The auth URL\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /github`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"origin","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The auth URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/github/url":{"get":{"operationId":"UsersController_githubAuthUrl","summary":"Get the GitHub auth URL","description":"Returns the URL to send a browser to for GitHub sign-in.\n\n#### Signature\n\n```http\nGET /user/github/url () -> The auth URL\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /github`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"origin","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The auth URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/github":{"get":{"operationId":"UsersController_githubLogin","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Redirect to GitHub","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Start GitHub sign-in","description":"Begins the GitHub OAuth flow.\n\n#### Signature\n\n```http\nGET /profile/github () -> Redirect to GitHub\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /github/redirect`"}},"/user/github":{"get":{"operationId":"UsersController_githubLogin","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Redirect to GitHub","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Start GitHub sign-in","description":"Begins the GitHub OAuth flow.\n\n#### Signature\n\n```http\nGET /user/github () -> Redirect to GitHub\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /github/redirect`"}},"/profile/github/redirect":{"get":{"operationId":"UsersController_githubLoginCallback","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"GitHub sign-in callback","description":"Handles GitHub's OAuth callback and issues tokens.\n\n#### Signature\n\n```http\nGET /profile/github/redirect () -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /github/redirect`"},"post":{"operationId":"UsersController_githubLoginCallbackPost","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"GitHub sign-in callback (POST)","description":"The POST form of the GitHub callback, for clients that post the authorisation code rather than being redirected.\n\n#### Signature\n\n```http\nPOST /profile/github/redirect (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /github/redirect`","requestBody":{"description":"The authorisation code.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"code":"abc123"}}}}}},"/user/github/redirect":{"get":{"operationId":"UsersController_githubLoginCallback","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"GitHub sign-in callback","description":"Handles GitHub's OAuth callback and issues tokens.\n\n#### Signature\n\n```http\nGET /user/github/redirect () -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /github/redirect`"},"post":{"operationId":"UsersController_githubLoginCallbackPost","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"GitHub sign-in callback (POST)","description":"The POST form of the GitHub callback, for clients that post the authorisation code rather than being redirected.\n\n#### Signature\n\n```http\nPOST /user/github/redirect (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /github/redirect`","requestBody":{"description":"The authorisation code.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"code":"abc123"}}}}}},"/profile/github/token":{"post":{"operationId":"UsersController_githubTokenExchange","summary":"Exchange a GitHub token","description":"Exchanges a GitHub access token for platform tokens.\n\n#### Signature\n\n```http\nPOST /profile/github/token (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /facebook/token`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The provider token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"accessToken":"gho_…"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/user/github/token":{"post":{"operationId":"UsersController_githubTokenExchange","summary":"Exchange a GitHub token","description":"Exchanges a GitHub access token for platform tokens.\n\n#### Signature\n\n```http\nPOST /user/github/token (body) -> Tokens and the signed-in user\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /facebook/token`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The provider token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"accessToken":"gho_…"}}}},"responses":{"201":{"description":"Tokens and the signed-in user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Bearer token for the `Authorization` header (a JWT; its lifetime is set by the server). Treat as a credential."},"refreshToken":{"type":"string","description":"Used to obtain a new token. Longer-lived, so more sensitive."},"user":{"type":"object","description":"A user or customer record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"username":{"type":"string","example":"ada"},"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"roles":{"type":"array","items":{"type":"string"},"example":["User"]},"groups":{"type":"array","items":{"type":"string"},"example":["engineering"]},"status":{"type":"string","example":"active"}}}}},"orgId":{"type":"string","description":"The org the session is for.","example":"acme"},"rootOrg":{"type":"string","description":"The platform root org id."},"sharedOrg":{"type":"string","description":"The platform shared org id."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"]}},"/profile/auth/success":{"get":{"operationId":"UsersController_authSuccess","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Authentication result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Authentication success callback","description":"The landing endpoint after a successful external authentication flow.\n\n#### Signature\n\n```http\nGET /profile/auth/success () -> Authentication result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /google/redirect`"}},"/user/auth/success":{"get":{"operationId":"UsersController_authSuccess","parameters":[{"name":"token","required":true,"in":"query","schema":{"type":"string"}},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Authentication result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · Authentication"],"summary":"Authentication success callback","description":"The landing endpoint after a successful external authentication flow.\n\n#### Signature\n\n```http\nGET /user/auth/success () -> Authentication result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /google/redirect`"}},"/api-key/create":{"post":{"operationId":"ApikeyController_createApiKey","summary":"Create an API key","description":"Creates an API key for machine-to-machine access.\n\nThe key value is returned **once, at creation**. It cannot be retrieved afterwards — if it is lost, regenerate rather than hunting for it. Scope the key to what the integration actually needs.\n\n#### Signature\n\n```http\nPOST /api-key/create (body) -> The created key — the secret is shown only here\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Set an expiry. A key with no expiry outlives whoever created it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /api-key/regenerate/{keyId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The key to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Warehouse sync"},"scopes":{"type":"array","items":{"type":"string"},"example":["storefront:read"]},"expiresAt":{"type":"string","format":"date-time"}}},"example":{"name":"Warehouse sync","scopes":["storefront:read"],"expiresAt":"2027-01-01T00:00:00.000Z"}}}},"responses":{"201":{"description":"The created key — the secret is shown only here","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]}},"/api-key/list":{"get":{"operationId":"ApikeyController_getUserApiKeys","summary":"List my API keys","description":"The caller's API keys — names, scopes and last use, but never the secrets.\n\n#### Signature\n\n```http\nGET /api-key/list () -> API keys\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /api-key/usage/{keyId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"API keys","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]}},"/api-key/{keyId}":{"get":{"operationId":"ApikeyController_getApiKey","summary":"Get an API key","description":"Fetches one key's metadata. The secret is not returned.\n\n#### Signature\n\n```http\nGET /api-key/{keyId} (keyId: string) -> The key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /api-key/{keyId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"keyId","required":true,"in":"path","description":"API key id.","schema":{"type":"string"},"example":"AKY-4821"}],"responses":{"200":{"description":"The key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]},"put":{"operationId":"ApikeyController_updateApiKey","summary":"Update an API key","description":"Updates a key's name, scopes or expiry. Narrowing scopes takes effect immediately, so check what the integration relies on first.\n\n#### Signature\n\n```http\nPUT /api-key/{keyId} (keyId: string, body) -> The updated key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /api-key/{keyId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"keyId","required":true,"in":"path","description":"API key id.","schema":{"type":"string"},"example":"AKY-4821"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Warehouse sync (read-only)","scopes":["storefront:read"]}}}},"responses":{"200":{"description":"The updated key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]},"delete":{"operationId":"ApikeyController_deleteApiKey","summary":"Delete an API key","description":"Deletes a key permanently. Anything using it stops working immediately — check the usage report before deleting a key you did not create.\n\n#### Signature\n\n```http\nDELETE /api-key/{keyId} (keyId: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Immediate and irreversible. Check `usage/{keyId}` first.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /api-key/usage/{keyId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"keyId","required":true,"in":"path","description":"API key id.","schema":{"type":"string"},"example":"AKY-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]}},"/api-key/regenerate/{keyId}":{"post":{"operationId":"ApikeyController_regenerateApiKey","summary":"Regenerate an API key","description":"Issues a new secret for an existing key and invalidates the old one, keeping the key's name and scopes.\n\n**The old secret stops working the moment this returns.** Have the new value ready to deploy before calling it, or the integration breaks in the gap.\n\n#### Signature\n\n```http\nPOST /api-key/regenerate/{keyId} (keyId: string) -> The key with its new secret — shown once\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- No overlap period. Plan the cutover before regenerating.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /api-key/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"keyId","required":true,"in":"path","description":"API key id.","schema":{"type":"string"},"example":"AKY-4821"}],"responses":{"201":{"description":"The key with its new secret — shown once","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]}},"/api-key/usage/{keyId}":{"get":{"operationId":"ApikeyController_getApiKeyUsage","summary":"Get API key usage","description":"How a key has been used — request volume and last activity. Read this before revoking a key to see what depends on it, and to spot a key still live long after its integration was retired.\n\n#### Signature\n\n```http\nGET /api-key/usage/{keyId} (keyId: string) -> Key usage\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /api-key/{keyId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"keyId","required":true,"in":"path","description":"API key id.","schema":{"type":"string"},"example":"AKY-4821"}],"responses":{"200":{"description":"Key usage","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]}},"/api-key/admin/list":{"get":{"operationId":"ApikeyController_getAllApiKeys","summary":"List all API keys (admin)","description":"Every API key in the organization, not just the caller's — the audit view for finding forgotten or over-scoped keys.\n\n#### Signature\n\n```http\nGET /api-key/admin/list () -> All API keys\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Admin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /api-key/admin/revoke/{keyId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"All API keys","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"]}},"/api-key/admin/revoke/{keyId}":{"post":{"operationId":"ApikeyController_revokeApiKey","summary":"Revoke an API key (admin)","description":"Revokes any key in the organization, regardless of who created it — the response to a leaked credential when its owner is unavailable.\n\n#### Signature\n\n```http\nPOST /api-key/admin/revoke/{keyId} (keyId: string, body) -> The revoked key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Admin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /blacklist/apikey/add`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"keyId","required":true,"in":"path","description":"API key id.","schema":{"type":"string"},"example":"AKY-4821"}],"responses":{"201":{"description":"The revoked key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"],"requestBody":{"description":"Optional reason.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reason":"Leaked in a public repository"}}}}}},"/api-key/auth":{"post":{"operationId":"ApikeyController_authenticateApiKey","summary":"Authenticate with an API key","description":"Exchanges an API key for an access token. The public entry point for machine-to-machine callers — the key is the credential, so it belongs in a header or body, never a URL.\n\n#### Signature\n\n```http\nPOST /api-key/auth (body) -> An access token\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | INVALID_KEY | Invalid or revoked API key | The key is unknown, expired, revoked or blacklisted. | Check the key is still active with the usage endpoint. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /validate-app-key`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-api-key","required":true,"in":"header","description":"API Key","schema":{"type":"string"}}],"responses":{"201":{"description":"An access token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or revoked API key — The key is unknown, expired, revoked or blacklisted.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Invalid or revoked API key","path":"/api-key/auth","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"],"requestBody":{"description":"The API key.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","example":"ak_9k2m4h1p7q"}}},"example":{"key":"ak_9k2m4h1p7q"}}}}}},"/api-key/org/{orgid}":{"get":{"operationId":"ApikeyController_getOrgUsers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"Organization id.","example":"acme-retail"}],"responses":{"200":{"description":"API keys","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"],"summary":"List an organization's API keys","description":"API keys for a named organization. Cross-org, so restrict to operators who legitimately administer more than one tenant.\n\n#### Signature\n\n```http\nGET /api-key/org/{orgid} (orgid: string) -> API keys\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /api-key/org/{orgid}/create`"}},"/api-key/org/{orgid}/create":{"post":{"operationId":"ApikeyController_createOrgUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"Organization id.","example":"acme-retail"}],"responses":{"201":{"description":"The created key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"],"summary":"Create an API key for an organization","description":"Creates a key against a named organization rather than the caller's own. The secret is returned once.\n\n#### Signature\n\n```http\nPOST /api-key/org/{orgid}/create (orgid: string, body) -> The created key\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /api-key/org/{orgid}/delete`","requestBody":{"description":"The key to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Partner integration","scopes":["storefront:read"]}}}}}},"/api-key/org/{orgid}/delete":{"post":{"operationId":"ApikeyController_deleteOrgUsers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"Organization id.","example":"acme-retail"}],"responses":{"201":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Users · API keys"],"summary":"Delete an organization API key","description":"Deletes a key belonging to a named organization. Note this is a `POST`, not a `DELETE`, unlike the self-service equivalent.\n\n#### Signature\n\n```http\nPOST /api-key/org/{orgid}/delete (orgid: string, body) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /api-key/{keyId}`","requestBody":{"description":"Which key to delete.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"keyId":"AKY-4821"}}}}}},"/profile/customer/sign-in-options":{"get":{"operationId":"CustomerSignInController_signInOptions","summary":"What a site's sign-in page offers","description":"The site is the one the request comes from (x-client-host, and the site name in x-client-info). Password, email link and sign-in code are the site's switches; google/github are the public client id the button starts with, present only when the site switched it on and the business has its sign-in app set up.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Customer sign-in"]}},"/profile/customer/oauth/{provider}":{"post":{"operationId":"CustomerSignInController_signInWithProvider","summary":"Finish a Google or GitHub sign-in","description":"A site's /auth/<provider>/callback posts the code the provider gave the customer and the redirect URI it was given on. The code is exchanged with the business's own sign-in app; the answer is the customer's session.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}},{"name":"provider","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Customer sign-in"]}},"/upstream/integration-types/{type}":{"get":{"operationId":"UpstreamController_getIntegrationTypes","summary":"Get integration types","description":"The integration types the platform supports and what each provides. `type` narrows to one; omit it for the full catalogue.\n\n#### Signature\n\n```http\nGET /upstream/integration-types/{type} (type: string) -> Integration types\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /upstream/integration-use-cases/{useCase}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"type","required":true,"in":"path","description":"Integration type. Optional.","schema":{"type":"string"},"example":"payment"}],"responses":{"200":{"description":"Integration types","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/integration-use-cases/{useCase}":{"get":{"operationId":"UpstreamController_getIntegrationUseCases","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"useCase","required":true,"in":"path","schema":{"type":"string"},"description":"Use case name.","example":"sms"}],"responses":{"200":{"description":"Integrations for the use case","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"],"summary":"Get integrations for a use case","description":"Which integrations serve a given use case — the lookup for \"what can send SMS\" rather than \"what does Twilio do\".\n\n#### Signature\n\n```http\nGET /upstream/integration-use-cases/{useCase} (useCase: string) -> Integrations for the use case\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /upstream/integration-types/{type}`"}},"/upstream/get-config/{type}/{configId}":{"get":{"operationId":"UpstreamController_getIntegrationConfig","summary":"Get an integration configuration","description":"Reads an integration's configuration. Both path segments are optional — narrow by type, or fetch one configuration by id.\n\n`create=true` **creates the configuration if it does not exist**, which makes this a write in disguise. Leave it off for a plain read.\n\nConfiguration carries credentials for the external service; treat the response as sensitive.\n\n#### Signature\n\n```http\nGET /upstream/get-config/{type}/{configId} (type: string, configId: string, create?: boolean) -> The configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `create=true` writes.\n- Response may contain credentials.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /upstream/save-integration`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"type","required":true,"in":"path","description":"Integration type. Optional.","schema":{"type":"string"},"example":"payment"},{"name":"configId","required":true,"in":"path","description":"Configuration id. Optional.","schema":{"type":"string"},"example":"CFG-12"},{"name":"create","required":false,"in":"query","description":"Create the configuration if missing. Default false.","schema":{"type":"boolean"},"example":false}],"responses":{"200":{"description":"The configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/active/{type}":{"get":{"operationId":"UpstreamController_listActiveIntegrationByType","summary":"List active integrations","description":"Integrations currently connected for the org, optionally narrowed to one type. The list to read before offering an integration-backed feature.\n\n#### Signature\n\n```http\nGET /upstream/active/{type} (type: string) -> Active integrations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /upstream/active/detail/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"type","required":true,"in":"path","description":"Integration type. Optional.","schema":{"type":"string"},"example":"payment"}],"responses":{"200":{"description":"Active integrations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/active/detail/{id}":{"get":{"operationId":"UpstreamController_activeIntegrations","summary":"Get an active integration","description":"Details of one active integration.\n\n#### Signature\n\n```http\nGET /upstream/active/detail/{id} (id: string) -> The integration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /upstream/active/{type}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Integration id. Optional.","schema":{"type":"string"},"example":"INT-12"}],"responses":{"200":{"description":"The integration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/get-integration":{"post":{"operationId":"UpstreamController_getIntegration","summary":"Get an integration by id","description":"Fetches an integration by identifier. A POST because the selector goes in the body; it is a read.\n\n#### Signature\n\n```http\nPOST /upstream/get-integration (body) -> The integration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Read-only despite being a POST.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /upstream/active/detail/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which integration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"INT-12"}}}},"responses":{"201":{"description":"The integration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/shutdown/{id}":{"post":{"operationId":"UpstreamController_shutdown","summary":"Shut down an integration","description":"Disconnects an integration. Everything depending on it stops working immediately — payments, messaging, sync — so check what uses it first.\n\n#### Signature\n\n```http\nPOST /upstream/shutdown/{id} (id: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Breaks every feature that depends on it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /upstream/active/{type}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Integration id.","schema":{"type":"string"},"example":"INT-12"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/call/{integration}/{operation}":{"post":{"operationId":"UpstreamController_callPost","summary":"Call an integration operation","description":"Forwards a call to an external service. The body is passed through as the operation's parameters, and the response is whatever the service returns — this API does not interpret either.\n\nBecause it is a generic proxy, the operation can have any effect the external service supports, including charging money or sending messages. Know what the operation does before calling it.\n\n### User account provisioning\n\nThe `MicrosoftProvider`, `GoogleWorkspaceProvider` and `SlackProvider` integrations create, suspend and remove staff accounts with one shape, so onboarding and offboarding call any of them the same way. Operation parameters go in `data`.\n\n**Common operations** (all three): `createUser`, `getUser`, `updateUser`, `suspendUser`, `resumeUser`, `deleteUser`, `addUserToGroup`, `removeUserFromGroup`, `listGroups`, `provisioningCapabilities`.\n**Microsoft only:** `assignLicense` (`skuId` or skuPartNumber; `removeSkuId`), `listLicenses`, `revokeSignInSessions` (alias `signOutUser`).\n**Google only:** `listOrgUnits`, `signOutUser`.\n**Slack only:** `deactivateUser` / `reactivateUser` (what `suspendUser` / `resumeUser` do), `inviteUser` (Enterprise Grid).\n\n**Input** to `createUser`: `{ email, firstName, lastName, displayName?, password?, groups?, license?, orgUnit?, attributes? }`. `groups` are ids, emails or names. `license` is Microsoft only, `orgUnit` Google only; `attributes` are provider-native fields merged into the request. Other operations identify the account with `{ externalId }` or `{ email }`; group operations add `groupId`.\n\n**Output:** `{ provider, externalId, email, status: \"active\" | \"suspended\" | \"deleted\", alreadyExisted?, temporaryPassword?, warnings?, raw? }`.\n\n**Behaviour**\n- `createUser` is idempotent by email: an existing account is returned untouched with `alreadyExisted: true`.\n- Without `password`, Microsoft and Google get a generated temporary password that must be changed at first sign-in; it is returned once as `temporaryPassword` and never stored or logged. Slack sets no password.\n- A failed licence or group step does not undo the account; it is reported in `warnings`.\n- `deleteUser` requires `confirm: true`. Microsoft keeps deleted users restorable for 30 days, Google for 20; Slack cannot delete, so the account is deactivated.\n- `suspendUser` with `signOut: true` also ends sessions (Microsoft revokeSignInSessions, Google signOut).\n- `provisioningCapabilities` reports, per operation, what the connected credentials and plan allow, and what is missing.\n\n**Setup and permissions**\n- Microsoft (Graph v1.0): `tenantId`, `clientId`, `clientSecret` of an Entra app with admin-consented *Application* permissions User.ReadWrite.All, GroupMember.ReadWrite.All (or Group.ReadWrite.All), Group.Read.All, LicenseAssignment.ReadWrite.All, Organization.Read.All, User.RevokeSessions.All. Directory.ReadWrite.All does not allow deleting users. Optional `defaultUsageLocation` (needed before a licence); `directoryAuth: \"delegated\"` uses the connected admin token instead.\n- Google (Admin SDK Directory API): `workspaceServiceAccountJson` and `workspaceAdminEmail` (a super admin to impersonate); optional `workspaceCustomerId`, `workspaceDomain`, `workspaceDefaultOrgUnit`. Authorise the service account client id for domain-wide delegation with admin.directory.user, admin.directory.group, admin.directory.orgunit and admin.directory.user.security. Alternatively an admin reconnects Google through `getAuthUrl` with `{ workspaceDirectory: true }`.\n- Slack (SCIM v2): Business+ or Enterprise Grid plan; `scimToken` is a user token (xoxp-) with the `admin` scope from a Workspace Owner/Admin (Org Owner on Grid). `inviteUser` (admin.users.invite) is Enterprise Grid only: `adminToken` with admin.users:write, `inviteTeamId`, `defaultInviteChannelIds`. A plan or token that does not allow SCIM fails with a message saying so.\n\n### E-Verify (`EverifyProvider`)\n\nSave a config with `provider: \"EverifyProvider\"` through `POST /upstream/save-integration`. Fields: `environment` (`stage` = E-Verify test account, `production` = live), `companyId` (the employer's E-Verify company ID), and the Web Services credentials E-Verify issued — `username` + `password`, or `clientId` + `clientSecret`. Optional: `baseUrl` (override the standard URL for the environment), `caseCreatorName` / `caseCreatorEmail` / `caseCreatorPhone` (used when no user is signed in), `autoCloseAuthorized` (default true). A config in the shared org with `employerAgent: true` lends its credentials to an org whose own config has only `companyId`.\n\nSaving the config sends every E-Verify case that was waiting for it. Cases are worked through `/business-made/everify/*`, not through `call/*`; the operations (`authenticate`, `createCase`, `submitCase`, `getCase`, `closeCase`, `confirmEmployeeNotified`, `referCase`, `confirmPhotoMatch`, `test`) are available on the proxy for diagnosis — `test` only signs in.\n\n#### Signature\n\n```http\nPOST /upstream/call/{integration}/{operation} (integration: string, operation: string, body) -> The operation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Passthrough — effects are defined by the external service.\n- Provisioning operations create, suspend and delete real accounts at the provider.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | — | Microsoft 365: deleteUser requires \"confirm\": true — this removes the account. | `deleteUser` without `confirm: true`. | Send `confirm: true` once the removal is intended. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /upstream/test/{integration}/{operation}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"integration","required":true,"in":"path","description":"Integration name.","schema":{"type":"string"},"example":"stripe"},{"name":"operation","required":true,"in":"path","description":"Operation name.","schema":{"type":"string"},"example":"listCharges"}],"requestBody":{"description":"Operation parameters, passed through unchanged. Provisioning operations take them under `data`.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"generic":{"summary":"Any operation","value":{"limit":10}},"microsoftCreate":{"summary":"Microsoft 365 — create a user with a licence (POST /upstream/call/MicrosoftProvider/createUser)","value":{"data":{"email":"ana.ng@contoso.com","firstName":"Ana","lastName":"Ng","license":"O365_BUSINESS_PREMIUM","groups":["Kitchen Staff"]}}},"googleCreate":{"summary":"Google Workspace — create a user in an org unit (POST /upstream/call/GoogleWorkspaceProvider/createUser)","value":{"data":{"email":"ana.ng@acme.com","firstName":"Ana","lastName":"Ng","orgUnit":"/Staff/Kitchen","groups":["kitchen@acme.com"]}}},"suspend":{"summary":"Any provider — suspend and sign out at the end time (…/suspendUser)","value":{"data":{"email":"ana.ng@acme.com","signOut":true}}},"delete":{"summary":"Any provider — delete, which must be confirmed (…/deleteUser)","value":{"data":{"externalId":"0d5b7e2a-1f4c-4b8e-9a61-2f3c4d5e6f70","confirm":true}}},"slackInvite":{"summary":"Slack Enterprise Grid — invite (POST /upstream/call/SlackProvider/inviteUser)","value":{"data":{"email":"ana.ng@acme.com","firstName":"Ana","lastName":"Ng","channelIds":"C0123ABCD"}}},"capabilities":{"summary":"Any provider — what the connected account can do (…/provisioningCapabilities)","value":{"data":{}}}}}}},"responses":{"201":{"description":"The operation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"provisioned":{"summary":"createUser result","value":{"provider":"google","externalId":"104512345678901234567","email":"ana.ng@acme.com","status":"active","alreadyExisted":false,"temporaryPassword":"<returned once>"}}}}}},"400":{"description":"Microsoft 365: deleteUser requires \"confirm\": true — this removes the account. — `deleteUser` without `confirm: true`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Microsoft 365: deleteUser requires \"confirm\": true — this removes the account.","path":"/upstream/call/{integration}/{operation}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]},"get":{"operationId":"UpstreamController_callGet","summary":"Call an integration operation (GET)","description":"The GET form of the proxy, for operations whose parameters fit in a query string. Same passthrough semantics — and note that being a GET does not make the operation safe; that depends on the external service.\n\n#### Signature\n\n```http\nGET /upstream/call/{integration}/{operation} (integration: string, operation: string) -> The operation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A GET here can still have side effects upstream.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /upstream/call/{integration}/{operation}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"integration","required":true,"in":"path","description":"Integration name.","schema":{"type":"string"},"example":"stripe"},{"name":"operation","required":true,"in":"path","description":"Operation name.","schema":{"type":"string"},"example":"listCharges"}],"responses":{"200":{"description":"The operation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/service/{serviceName}/{operation}":{"get":{"operationId":"UpstreamController_serviceGet","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serviceName","required":true,"in":"path","schema":{"type":"string"},"description":"Service name.","example":"sms"},{"name":"operation","required":true,"in":"path","schema":{"type":"string"},"description":"Operation name.","example":"listMessages"}],"responses":{"200":{"description":"The operation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"],"summary":"Call a service operation (GET)","description":"Calls an operation by **service name** rather than integration id — the platform resolves which configured integration provides that service. Use it when the caller cares about the capability, not the vendor.\n\n#### Signature\n\n```http\nGET /upstream/service/{serviceName}/{operation} (serviceName: string, operation: string) -> The operation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /upstream/service/{serviceName}/{operation}`"},"post":{"operationId":"UpstreamController_servicePost","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"integration","required":true,"in":"path","schema":{"type":"string"}},{"name":"operation","required":true,"in":"path","schema":{"type":"string"},"description":"Operation name.","example":"send"},{"name":"serviceName","in":"path","required":true,"description":"Service name — the first path segment.","schema":{"type":"string"},"example":"sms"}],"responses":{"201":{"description":"The operation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"],"summary":"Call a service operation","description":"The POST form of the service-name call. Same resolution: the platform picks the integration providing the named service.\n\n**Note:** the handler declares its path parameters as `integration` and `operation` while the route declares `serviceName` and `operation` — the first segment binds to whichever name the route uses, so pass the service name in the first position.\n\n#### Signature\n\n```http\nPOST /upstream/service/{serviceName}/{operation} (serviceName: string, operation: string, body) -> The operation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Passthrough — effects are defined by the external service.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /upstream/service/{serviceName}/{operation}`","requestBody":{"description":"Operation parameters.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"to":"+15551234567","body":"Hello"}}}}}},"/upstream/test/{integration}/{operation}":{"post":{"operationId":"UpstreamController_test","summary":"Test an integration operation","description":"Runs an operation as a connectivity and credential check. The call still reaches the external service — \"test\" means it is run for diagnosis, not that it is simulated, so pick a read-only operation.\n\n#### Signature\n\n```http\nPOST /upstream/test/{integration}/{operation} (integration: string, operation: string, body) -> The test result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Really calls the external service.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /upstream/call/{integration}/{operation}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"integration","required":true,"in":"path","description":"Integration name.","schema":{"type":"string"},"example":"stripe"},{"name":"operation","required":true,"in":"path","description":"Operation name.","schema":{"type":"string"},"example":"listCharges"}],"requestBody":{"description":"Operation parameters.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}},"responses":{"201":{"description":"The test result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/upstream/integration-default/{provider}":{"post":{"operationId":"UpstreamController_makeDefaultConnection","summary":"Make a connection the default","description":"Gives this connection the top priority among its provider’s connections, so it is used first (staff).","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"provider","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Upstream"]}},"/upstream/integration-connections":{"get":{"operationId":"UpstreamController_integrationConnections","summary":"Integration connections","description":"Every connection this org has, any provider: name, state, mode, last test (staff). Never returns secrets.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Upstream"]}},"/upstream/integration-status":{"get":{"operationId":"UpstreamController_integrationStatuses","summary":"Integration states","description":"Every provider this org has a connection for, by state (staff).","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Upstream"]}},"/upstream/integration-status/{provider}":{"get":{"operationId":"UpstreamController_integrationStatus","summary":"Integration state","description":"One provider for this org: connected, mode, setup steps done, last test, webhook address (staff). Never returns secrets.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"provider","required":true,"in":"path","schema":{"type":"string"}},{"name":"configId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Upstream"]}},"/upstream/integration-test/{provider}":{"post":{"operationId":"UpstreamController_testIntegration","summary":"Test an integration","description":"Runs the provider's own connection test and keeps the result on the connection (staff).","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"provider","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Upstream"]}},"/upstream/save-integration":{"post":{"operationId":"UpstreamController_saveIntegration","summary":"Save an integration","description":"Creates or updates an integration configuration, including its credentials. **Never log this request body.** Saving a bad credential does not fail here — it fails on the next call through the integration, so test afterwards.\n\n#### Signature\n\n```http\nPOST /upstream/save-integration (body) -> The saved integration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Carries credentials.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /upstream/test/{integration}/{operation}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The integration configuration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"type":"payment","name":"stripe","config":{"apiKey":"<secret>"}}}}},"responses":{"201":{"description":"The saved integration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Upstream"]}},"/connect/webhook/{vendor}/{serviceId}":{"post":{"operationId":"ConnectController_connectPartnerPost","summary":"Partner webhook (POST)","description":"Receives a webhook from a partner service. **Unauthenticated** — it has to be, since the partner has no session — so the tenant is taken from the `orgid` **query parameter** and the payload's authenticity is whatever the vendor's own signing provides.\n\nTreat the body as untrusted input. `serviceId` is optional and identifies which configured connection the callback belongs to.\n\n#### Signature\n\n```http\nPOST /connect/webhook/{vendor}/{serviceId} (vendor: string, serviceId: string, orgid?: string, body) -> The vendor-appropriate acknowledgement\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated; tenant comes from the query string.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /connect/webhook/{vendor}/{serviceId}`","parameters":[{"name":"orgid","required":true,"in":"query","description":"The tenant — this route does not use the `orgid` header.","schema":{"type":"string"},"example":"org_4821"},{"name":"vendor","required":true,"in":"path","description":"Partner name.","schema":{"type":"string"},"example":"stripe"},{"name":"serviceId","required":true,"in":"path","description":"Which configured connection. Optional.","schema":{"type":"string"},"example":"SVC-12"},{"name":"orgid","in":"header","description":"Organization ID","required":false,"schema":{"type":"string"}}],"requestBody":{"description":"The vendor's payload, passed through as sent.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"The vendor-appropriate acknowledgement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Connect"]},"get":{"operationId":"ConnectController_connectPartnerGet","summary":"Partner webhook (GET)","description":"The GET form, for vendors that verify a webhook endpoint with a challenge request before sending real events. Same unauthenticated, query-scoped shape as the POST form.\n\n#### Signature\n\n```http\nGET /connect/webhook/{vendor}/{serviceId} (vendor: string, serviceId: string, orgid?: string) -> The challenge response\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /connect/webhook/{vendor}/{serviceId}`","parameters":[{"name":"orgid","required":true,"in":"query","schema":{"type":"string"},"example":"org_4821"},{"name":"vendor","required":true,"in":"path","description":"Partner name.","schema":{"type":"string"},"example":"facebook"},{"name":"serviceId","required":true,"in":"path","description":"Optional.","schema":{"type":"string"},"example":"SVC-12"},{"name":"orgid","in":"header","description":"Organization ID","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The challenge response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Connect"]}},"/connect/oauth2callback/{vendor}":{"get":{"operationId":"ConnectController_oAuthCallback","summary":"OAuth callback","description":"The redirect target for an OAuth authorization flow. The browser arrives here with `code` and `state`; the server exchanges the code for tokens and stores them against the integration.\n\n`state` is what ties the callback back to the flow that started it — a callback with a mismatched state is not the one that was initiated.\n\n#### Signature\n\n```http\nGET /connect/oauth2callback/{vendor} (vendor: string, code?: string, state?: string) -> A redirect back into the application\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Browser-facing redirect target.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /upstream/save-integration`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"vendor","required":true,"in":"path","description":"Partner name.","schema":{"type":"string"},"example":"google"},{"name":"serviceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","description":"Opaque state tying the callback to the initiating flow.","schema":{"type":"string"},"example":"st_7Kq2M9"},{"name":"code","required":true,"in":"query","description":"Authorization code from the provider.","schema":{"type":"string"},"example":"4/0AbC…"}],"responses":{"200":{"description":"A redirect back into the application","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"302":{"description":"Redirect to another URL"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Connect"]}},"/connect/automation/{id}/{stepId}/{entity}/{activity}":{"post":{"operationId":"ConnectController_handleUnifiedAutomationWebhook","summary":"Automation webhook (POST)","description":"The unified inbound hook that lets an external event advance an automation — `id` and `stepId` name where in the automation to resume, `entity` and `activity` say what happened.\n\n**Unauthenticated**, with the tenant in the `orgId` query parameter. Anyone who knows the URL can trigger the step, so treat these URLs as capability tokens and do not publish them. `redirect` sends the caller onward afterwards, which is how this is used from an email link.\n\n#### Signature\n\n```http\nPOST /connect/automation/{id}/{stepId}/{entity}/{activity} (id: string, stepId: string, entity: string, activity: string, orgId?: string, automationId?: string, redirect?: string, body) -> A result, or a redirect\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the URL is the credential.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /connect/automation/{id}/{stepId}/{entity}/{activity}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"orgId","required":true,"in":"query","description":"The tenant.","schema":{"type":"string"},"example":"org_4821"},{"name":"entity","required":true,"in":"path","description":"What the event concerns.","schema":{"type":"string"},"example":"customer"},{"name":"activity","required":true,"in":"path","description":"What happened.","schema":{"type":"string"},"example":"clicked"},{"name":"stepId","required":false,"in":"query","description":"Step ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Automation id.","schema":{"type":"string"},"example":"AUT-4821"},{"name":"automationId","required":false,"in":"query","schema":{"type":"string"},"example":"AUT-4821"},{"name":"redirect","required":false,"in":"query","description":"Where to send the caller afterwards.","schema":{"type":"string"},"example":"https://example.com/thanks"},{"name":"stepId","in":"path","required":true,"description":"Step to resume at.","schema":{"type":"string"},"example":"step-3"}],"requestBody":{"description":"Event payload.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"A result, or a redirect","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Connect"]},"get":{"operationId":"ConnectController_handleUnifiedAutomationWebhookGet","summary":"Automation webhook (GET)","description":"The GET form, for use as a link in an email — a recipient clicking it advances the automation and is then sent to `redirect`. Same unauthenticated, URL-as-credential caveat as the POST form.\n\n#### Signature\n\n```http\nGET /connect/automation/{id}/{stepId}/{entity}/{activity} (id: string, stepId: string, entity: string, activity: string, orgId?: string, automationId?: string, redirect?: string) -> A result, or a redirect\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the URL is the credential.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /connect/automation/{id}/{stepId}/{entity}/{activity}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"orgId","required":true,"in":"query","schema":{"type":"string"},"example":"org_4821"},{"name":"entity","required":true,"in":"path","description":"What the event concerns.","schema":{"type":"string"},"example":"customer"},{"name":"activity","required":true,"in":"path","description":"What happened.","schema":{"type":"string"},"example":"confirmed"},{"name":"id","required":true,"in":"path","description":"Automation id.","schema":{"type":"string"},"example":"AUT-4821"},{"name":"stepId","required":false,"in":"query","description":"Step ID","schema":{"type":"string"}},{"name":"automationId","required":false,"in":"query","schema":{"type":"string"},"example":"AUT-4821"},{"name":"redirect","required":false,"in":"query","schema":{"type":"string"},"example":"https://example.com/thanks"},{"name":"stepId","in":"path","required":true,"description":"Step to resume at.","schema":{"type":"string"},"example":"step-3"}],"responses":{"200":{"description":"A result, or a redirect","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Connect"]}},"/phone/numbers":{"get":{"operationId":"PhoneController_getPhoneNumbers","summary":"List phone numbers","description":"Every phone number configured for the organization, with its capabilities and purpose.\n\n#### Signature\n\n```http\nGET /phone/numbers () -> Phone numbers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/available`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Phone numbers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"post":{"operationId":"PhoneController_purchasePhoneNumber","summary":"Purchase a phone number","description":"Buys a number from the provider and adds it to the organization.\n\n**This incurs a real, recurring charge.** Numbers bill monthly until released, so provision deliberately rather than as a side effect of a setup flow.\n\n#### Signature\n\n```http\nPOST /phone/numbers (body) -> The purchased number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Recurring cost from the moment of purchase. Release numbers you stop using.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /phone/numbers/{phoneId}`\n- `POST /phone/numbers/add`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which number to buy.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"phoneNumber":"+14155552600","friendlyName":"Support line","purpose":"support"}}}},"responses":{"201":{"description":"The purchased number","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/numbers/{phoneId}":{"get":{"operationId":"PhoneController_getPhoneNumberById","summary":"Get a phone number","description":"Fetches one number with its routing, capabilities and SMS registration state.\n\n#### Signature\n\n```http\nGET /phone/numbers/{phoneId} (phoneId: string) -> The phone number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PHONE_NOT_FOUND | Phone number not found | No phone number in the org has that id. | List them with `GET /phone/numbers`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/numbers/{phoneId}/sms-requirements`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":true,"in":"path","description":"Phone number id.","schema":{"type":"string"},"example":"PHN-4821"}],"responses":{"200":{"description":"The phone number","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Phone number not found — No phone number in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Phone number not found","path":"/phone/numbers/{phoneId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"put":{"operationId":"PhoneController_updatePhoneConfiguration","summary":"Update a phone number","description":"Updates a number's friendly name or purpose. Routing has its own endpoint.\n\n#### Signature\n\n```http\nPUT /phone/numbers/{phoneId} (phoneId: string, body) -> The updated number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PHONE_NOT_FOUND | Phone number not found | No phone number in the org has that id. | List them with `GET /phone/numbers`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/numbers/{phoneId}/routing`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":true,"in":"path","description":"Phone number id.","schema":{"type":"string"},"example":"PHN-4821"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"friendlyName":"Sales line"}}}},"responses":{"200":{"description":"The updated number","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Phone number not found — No phone number in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Phone number not found","path":"/phone/numbers/{phoneId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"delete":{"operationId":"PhoneController_releasePhoneNumber","summary":"Release a phone number","description":"Releases a number back to the provider, ending the recurring charge.\n\n**Releasing is not reversible.** The number returns to the provider's pool and may be reassigned to someone else — anyone who calls or texts it afterwards reaches a stranger. Check nothing published still lists it.\n\n#### Signature\n\n```http\nDELETE /phone/numbers/{phoneId} (phoneId: string) -> Release result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- You cannot get the number back. Verify it is not in print, on a website, or in a customer record first.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PHONE_NOT_FOUND | Phone number not found | No phone number in the org has that id. | List them with `GET /phone/numbers`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/numbers`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":true,"in":"path","description":"Phone number id.","schema":{"type":"string"},"example":"PHN-4821"}],"responses":{"200":{"description":"Release result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Phone number not found — No phone number in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Phone number not found","path":"/phone/numbers/{phoneId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/available":{"get":{"operationId":"PhoneController_getAvailableNumbers","summary":"Search available numbers","description":"Searches the provider for numbers available to buy. Listing is free and reserves nothing — a number shown here can be taken by someone else before you purchase it.\n\n#### Signature\n\n```http\nGET /phone/available (areaCode?: string, region?: string, contains?: string, smsEnabled?: boolean, voiceEnabled?: boolean, limit?: integer) -> Available numbers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Search results are not held. Purchase promptly or re-search.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/numbers`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"limit","required":false,"in":"query","description":"How many results.","schema":{"type":"integer"},"example":20},{"name":"voiceEnabled","required":false,"in":"query","description":"Only voice-capable numbers.","schema":{"type":"boolean"},"example":true},{"name":"smsEnabled","required":false,"in":"query","description":"Only SMS-capable numbers.","schema":{"type":"boolean"},"example":true},{"name":"contains","required":false,"in":"query","description":"Digits the number should contain.","schema":{"type":"string"},"example":"2600"},{"name":"region","required":false,"in":"query","description":"Region or state.","schema":{"type":"string"},"example":"CA"},{"name":"areaCode","required":false,"in":"query","description":"Area code to search within.","schema":{"type":"string"},"example":"415"},{"name":"countryCode","required":false,"in":"query","description":"Country code (default: US)","schema":{}}],"responses":{"200":{"description":"Available numbers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/numbers/add":{"post":{"operationId":"PhoneController_addExistingPhoneNumber","summary":"Add an existing number","description":"Registers a number you already own with the platform, rather than buying a new one. Use this when porting in or when the number was bought directly with the provider — it adds no cost of its own.\n\n#### Signature\n\n```http\nPOST /phone/numbers/add (body) -> The added number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- E.164 format is required — `+` and country code, no spaces or punctuation.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/numbers`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The number to add.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumber"],"properties":{"phoneNumber":{"type":"string","description":"E.164 format.","example":"+14155552600"},"friendlyName":{"type":"string","example":"Support line"},"purpose":{"type":"string","example":"support"}}},"example":{"phoneNumber":"+14155552600","friendlyName":"Support line","purpose":"support"}}}},"responses":{"201":{"description":"The added number","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/numbers/{phoneId}/routing":{"post":{"operationId":"PhoneController_configurePhoneRouting","summary":"Configure number routing","description":"Sets where calls and messages to a number go — an IVR, a queue, a forwarding destination. Misrouting silently sends customers nowhere, so verify with a test call after changing it.\n\n#### Signature\n\n```http\nPOST /phone/numbers/{phoneId}/routing (phoneId: string, body) -> The updated routing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PHONE_NOT_FOUND | Phone number not found | No phone number in the org has that id. | List them with `GET /phone/numbers`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/numbers/{phoneId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":true,"in":"path","description":"Phone number id.","schema":{"type":"string"},"example":"PHN-4821"}],"requestBody":{"description":"The routing configuration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"voice":{"type":"queue","target":"support"},"sms":{"type":"inbox"}}}}},"responses":{"201":{"description":"The updated routing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Phone number not found — No phone number in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Phone number not found","path":"/phone/numbers/{phoneId}/routing","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/numbers/sms-status/{phoneId}":{"get":{"operationId":"PhoneController_checkSmsRegistrationStatus","summary":"Get SMS registration status","description":"Where a number stands in A2P registration. Registration takes days and can be rejected, so check status rather than assuming a submitted registration is a working one.\n\n#### Signature\n\n```http\nGET /phone/numbers/sms-status/{phoneId} (phoneId: string) -> Registration status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PHONE_NOT_FOUND | Phone number not found | No phone number in the org has that id. | List them with `GET /phone/numbers`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/a2p/brand`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":true,"in":"path","description":"Phone number id.","schema":{"type":"string"},"example":"PHN-4821"}],"responses":{"200":{"description":"Registration status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Phone number not found — No phone number in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Phone number not found","path":"/phone/numbers/sms-status/{phoneId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/numbers/register-sms/{phoneId}":{"post":{"operationId":"PhoneController_registerForSms","summary":"Register a number for SMS","description":"Submits a number for A2P messaging registration. Asynchronous and subject to carrier approval — poll the status endpoint rather than treating a `200` as registration.\n\n#### Signature\n\n```http\nPOST /phone/numbers/register-sms/{phoneId} (phoneId: string, body) -> The submission result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Submission is not approval. Carriers can reject a campaign days later.\n- Nobody has to come back: the `a2p-watch` scheduled job (every 15 minutes, for each org with a registration waiting) checks the brand and each campaign, submits a waiting campaign once — and only once — the brand is approved, and marks the number ready to text when the campaign is. See GET /jobs/scheduled.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PHONE_NOT_FOUND | Phone number not found | No phone number in the org has that id. | List them with `GET /phone/numbers`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/numbers/sms-status/{phoneId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":true,"in":"path","description":"Phone number id.","schema":{"type":"string"},"example":"PHN-4821"}],"requestBody":{"description":"Registration details.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"campaignUseCase":"customer_care"}}}},"responses":{"201":{"description":"The submission result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Phone number not found — No phone number in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Phone number not found","path":"/phone/numbers/register-sms/{phoneId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/a2p/site-pages":{"post":{"operationId":"PhoneController_publishA2PSitePages","summary":"Publish SMS terms and a privacy policy","description":"Publishes the SMS Terms and Privacy Policy pages carriers look for on the org's site, filled with its details. Pages the site already has are kept. Returns the page links and a suggested opt-in description.\n\n#### Signature\n\n```http\nPOST /phone/a2p/site-pages (body) -> { site, siteUrl, pages, suggestedMessageFlow }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"{ site, siteUrl, pages, suggestedMessageFlow }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"],"requestBody":{"description":"Optional business details to use.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/phone/calls/ai":{"post":{"operationId":"PhoneController_placeAICall","summary":"Make an AI phone call (call someone)","description":"Dials a person from the organization's number and connects its AI voice assistant, which talks to them — you do not speak on the call. Give `to` (the number to call; 10-digit US numbers are fine), `reason` (what the call is for — the voice assistant works from it) and optionally `greeting` (its opening line), `assistantId` (which voice assistant; default: the one that answers the calling number) and `from` (which of the organization's numbers to call from — by default your own assigned number, else the default number, else a free one, else the system phone). Use it to call a customer back, confirm an appointment, or follow up.\n\n#### Signature\n\n```http\nPOST /phone/calls/ai (body) -> { sid, status, to, from, assistantId } — the call is placed; the voice assistant takes over when they answer.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Premium-rate and international numbers are refused.\n- The call is billed to the organization like any call.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/calls`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"{ sid, status, to, from, assistantId } — the call is placed; the voice assistant takes over when they answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"],"requestBody":{"description":"Who to call and why.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"to":"+16823470647","reason":"Call back about their website setup question and offer to book a walkthrough.","greeting":"Hi, this is Appmint calling about your website question."}}}}}},"/phone/a2p/draft":{"get":{"operationId":"PhoneController_a2pDraft","summary":"The SMS registration, pre-filled","description":"The registration form filled from what the platform knows: the registered brand, business profile, org settings (address, email, phone), the signed-in user as representative, the website and its SMS pages, and this number's previous submission. Includes `platform.ready` — false until the platform's own Twilio profile is approved.\n\n#### Signature\n\n```http\nGET /phone/a2p/draft (phoneId?: string) -> The pre-filled submission\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/a2p/check`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":false,"in":"query","schema":{"type":"string"},"description":"The number being registered.","example":"6a8267a95850d7f4f4b92ae5"}],"responses":{"200":{"description":"The pre-filled submission","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/a2p/check":{"post":{"operationId":"PhoneController_checkA2P","summary":"Check an SMS registration before submitting","description":"Runs the checks that catch the usual rejection reasons. Returns { ok, problems: [{ field, severity: block|warn, message }] } — registration refuses a submission with block problems.\n\n#### Signature\n\n```http\nPOST /phone/a2p/check (body) -> { ok, problems, brandExists }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/numbers/register-sms/{phoneId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"{ ok, problems, brandExists }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"],"requestBody":{"description":"The submission.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/phone/a2p/brand":{"get":{"operationId":"PhoneController_getA2PBrand","summary":"Get the A2P brand","description":"The organization's A2P brand registration — the business identity carriers approve campaigns against. Numbers cannot be registered until the brand is.\n\n#### Signature\n\n```http\nGET /phone/a2p/brand () -> The A2P brand\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/numbers/register-sms/{phoneId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The A2P brand","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/numbers/{phoneId}/sms-requirements":{"get":{"operationId":"PhoneController_getSmsRegistrationRequirements","summary":"Get SMS requirements for a number","description":"What still has to be done before this number can send SMS reliably — brand registration, campaign approval, and the rest of A2P 10DLC.\n\nRead this before relying on a number for messaging. An unregistered number does not fail loudly; carriers simply filter its traffic.\n\n#### Signature\n\n```http\nGET /phone/numbers/{phoneId}/sms-requirements (phoneId: string) -> Outstanding requirements\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PHONE_NOT_FOUND | Phone number not found | No phone number in the org has that id. | List them with `GET /phone/numbers`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/numbers/register-sms/{phoneId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":true,"in":"path","description":"Phone number id.","schema":{"type":"string"},"example":"PHN-4821"}],"responses":{"200":{"description":"Outstanding requirements","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Phone number not found — No phone number in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Phone number not found","path":"/phone/numbers/{phoneId}/sms-requirements","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/setup":{"post":{"operationId":"PhoneController_setupPhone","summary":"Set up phone","description":"Configures phone service for the organization — provider credentials and defaults. Run `GET /phone/verify` afterwards to confirm it works before depending on it.\n\n#### Signature\n\n```http\nPOST /phone/setup (body) -> The setup result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The body carries provider credentials — do not log it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/verify`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Setup details.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"provider":"twilio","accountSid":"AC…","authToken":"…"}}}},"responses":{"201":{"description":"The setup result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/verify":{"get":{"operationId":"PhoneController_verifySetup","summary":"Verify phone setup","description":"Checks the phone configuration is complete and the provider reachable. The first thing to run when calls or messages stop arriving.\n\n#### Signature\n\n```http\nGET /phone/verify () -> Verification result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/setup`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"phoneId","required":false,"in":"query","description":"Specific phone to verify (optional)","schema":{"type":"string"}}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/token":{"post":{"operationId":"PhoneController_generateVoiceToken","summary":"Get a phone access token","description":"Issues a short-lived token for a softphone or browser client to connect to the voice service, always for the signed-in caller (`user:<orgId>:<email>`). Staff only. Tokens expire — fetch one per session rather than caching.\n\n#### Signature\n\n```http\nPOST /phone/token (body) -> The access token\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The token permits placing calls. Treat it as a credential.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/voice/register-device`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Token request. `identity` is ignored.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"platform":"web"}}}},"responses":{"200":{"description":"Voice access token","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"identity":{"type":"string"},"expiresIn":{"type":"number"}}}}}},"201":{"description":"The access token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/whatsapp/enable/{phoneId}":{"post":{"operationId":"PhoneController_enableWhatsApp","summary":"Turn on WhatsApp for a number","description":"Registers the number as a WhatsApp sender with Twilio (one-time Meta approval) on the account the number belongs to. Returns the phone's `whatsapp` block: status pending|on|failed, senderSid, displayName, reason, updatedAt. A failure is saved with a reason that says what to fix — e.g. no WhatsApp Business Account linked yet.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"phoneId","required":true,"in":"path","description":"Phone record sk","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Phone Management"]}},"/phone/whatsapp/status/{phoneId}":{"get":{"operationId":"PhoneController_whatsAppStatus","summary":"WhatsApp status of a number","description":"Asks Twilio where the WhatsApp sender is, saves and returns the phone's `whatsapp` block.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"phoneId","required":true,"in":"path","description":"Phone record sk","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Phone Management"]}},"/phone/whatsapp/numbers":{"get":{"operationId":"PhoneController_whatsAppNumbers","summary":"Numbers I can send WhatsApp from","description":"The signed-in user's numbers (same list and shape as GET phone/user-phones) that have WhatsApp on.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Phone Management"]}},"/phone/user-phones":{"get":{"operationId":"PhoneController_getUserPhones","summary":"Get user phone assignments","description":"Which numbers are assigned to which users — who receives calls to what.\n\n#### Signature\n\n```http\nGET /phone/user-phones () -> User phone assignments\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/numbers`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"User phone assignments","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/voice/app":{"get":{"operationId":"PhoneController_getVoiceApp","summary":"Get the voice application","description":"The voice application configuration — how inbound calls are handled before any per-number routing applies.\n\n#### Signature\n\n```http\nGET /phone/voice/app () -> The voice application\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/voice/app`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","description":"Frontend-generated stable device id, persisted in localStorage (web) / Keychain (iOS) / EncryptedSharedPreferences (Android). Reuse the same value across page reloads / app relaunches. Required for correct multi-device behavior — multiple tabs/apps can register under the same user identity and all ring in parallel."},"platform":{"type":"string","enum":["web","ios","android"],"default":"web"},"label":{"type":"string","description":"Human-readable device label for admin UI (e.g., \"Chrome on MacBook\")"},"capabilities":{"type":"array","items":{"type":"string","enum":["voice","sms"]},"default":["voice"],"description":"What this device wants to receive. \"voice\" = incoming calls (Twilio Client). \"sms\" = inbound SMS for this user's assigned numbers (pushed via websocket). Pass [\"voice\", \"sms\"] for a full softphone."}}}}}},"responses":{"200":{"description":"The voice application","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"post":{"operationId":"PhoneController_createVoiceApp","summary":"Update the voice application","description":"Updates the voice application configuration. This affects call handling org-wide, so a mistake here takes out every number at once — test with a call afterwards.\n\n#### Signature\n\n```http\nPOST /phone/voice/app (body) -> The updated application\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Org-wide effect. Verify with a real call.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/voice/app`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The configuration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"greeting":"Thanks for calling Acme","fallbackNumber":"+14155552601"}}}},"responses":{"201":{"description":"The updated application","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/voice/voices":{"get":{"operationId":"PhoneController_getAiVoices","summary":"List available AI voices","description":"Every AI voice the org can put on a call, from every engine, as `[{ name, info, platform, previewUrl? }]`. `previewUrl` is a short sample to play before choosing: ElevenLabs' own hosted sample, or for OpenAI a sample rendered once and stored. A voice whose sample does not exist yet is returned without it (the render starts in the background) — the list never waits or fails on previews.\n\n#### Signature\n\n```http\nGET /phone/voice/voices () -> Available voices\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/voice/preview`\n- `POST /phone/voice/app`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Available voices","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/voice/preview":{"post":{"operationId":"PhoneController_previewVoice","summary":"Preview a line in an AI voice","description":"Renders a specific line — usually the assistant's greeting — in the chosen voice and returns a URL to the mp3. ElevenLabs voices render on ElevenLabs, OpenAI voices on OpenAI TTS; the caller does not care which.\n\nRendered once per (platform, voice, text) and stored, so previewing the same greeting again is instant and free. New lines are capped per org per hour.\n\n#### Signature\n\n```http\nPOST /phone/voice/preview (body) -> `{ url }` — a public mp3 URL\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- 400 with a plain message for an unknown platform, a voice that is not on that platform, or empty / over-300-character text.\n- 429 when the org has rendered too many new lines this hour; cached lines are never counted.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/voice/voices`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"`{ url }` — a public mp3 URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"],"requestBody":{"description":"The voice and the line.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["voice","platform","text"],"properties":{"voice":{"type":"string","description":"The voice `name` from GET /phone/voice/voices — an OpenAI voice name or an ElevenLabs voice_id.","example":"marin"},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"The voice's `platform` from the same list."},"text":{"type":"string","maxLength":300,"description":"The line to speak.","example":"Thanks for calling Acme, how can I help?"}}},"example":{"voice":"marin","platform":"openai-realtime","text":"Thanks for calling Acme, how can I help?"}}}}}},"/phone/voice/register-device":{"post":{"operationId":"PhoneController_registerVoiceDevice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The registered device","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"],"summary":"Register a voice device","description":"Registers a device to receive calls — a softphone, a mobile app. Until registered, calls routed to that user will not ring anywhere.\n\n#### Signature\n\n```http\nPOST /phone/voice/register-device (body) -> The registered device\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/voice/heartbeat`","requestBody":{"description":"The device to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"identity":"ada@example.com","deviceToken":"apns_…","platform":"ios"}}}}}},"/phone/voice/heartbeat":{"post":{"operationId":"PhoneController_heartbeatVoiceDevice","summary":"Send a device heartbeat","description":"Keeps a registered device marked as available. A device that stops sending heartbeats is treated as offline and calls route past it — which is what stops a dead app silently swallowing calls.\n\n#### Signature\n\n```http\nPOST /phone/voice/heartbeat (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/voice/devices`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The device.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"identity":"ada@example.com","deviceId":"DEV-4821"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/voice/unregister-device":{"post":{"operationId":"PhoneController_unregisterVoiceDevice","summary":"Unregister a voice device","description":"Removes a device so it stops receiving calls. Do this when someone changes phone, or their old handset keeps ringing for calls they should not get.\n\n#### Signature\n\n```http\nPOST /phone/voice/unregister-device (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/voice/register-device`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The device to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"identity":"ada@example.com","deviceId":"DEV-4821"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/voice/devices":{"get":{"operationId":"PhoneController_listVoiceDevices","summary":"List registered voice devices","description":"Devices currently registered to receive calls, and whether each is live. Where a \"why did nobody answer\" investigation starts.\n\n#### Signature\n\n```http\nGET /phone/voice/devices () -> Registered devices\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/voice/heartbeat`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Registered devices","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/system":{"get":{"operationId":"PhoneController_getSystemPhone","summary":"Get the system phone configuration","description":"The platform-level phone configuration, as opposed to the org's own numbers.\n\n#### Signature\n\n```http\nGET /phone/system () -> System phone configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/system`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"System phone configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"post":{"operationId":"PhoneController_setSystemPhone","summary":"Update the system phone configuration","description":"Updates the platform-level phone configuration.\n\n#### Signature\n\n```http\nPOST /phone/system (body) -> The updated configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /phone/system`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The configuration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"phoneNumber":"+14155552600"}}}},"responses":{"201":{"description":"The updated configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"delete":{"operationId":"PhoneController_clearSystemPhone","summary":"Remove the system phone configuration","description":"Clears the platform-level phone configuration. Anything relying on a system number stops working.\n\n#### Signature\n\n```http\nDELETE /phone/system () -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/system`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/sms-number":{"get":{"operationId":"PhoneController_getSmsPhone","summary":"Get the default SMS number","description":"The number outbound SMS is sent from by default.\n\n#### Signature\n\n```http\nGET /phone/sms-number () -> The default SMS number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/sms-number`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The default SMS number","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"post":{"operationId":"PhoneController_setSmsPhone","summary":"Set the default SMS number","description":"Sets the number outbound SMS is sent from.\n\nThe number is **checked for sendability first**: it must exist in the org and be capable of sending, and the refusal names the specific reason — usually incomplete A2P registration. That check is what stops the org silently defaulting to a number whose messages carriers drop.\n\n#### Signature\n\n```http\nPOST /phone/sms-number (body) -> The updated default\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PHONE_NUMBER_REQUIRED | phoneNumber is required | `phoneNumber` is missing. | Supply the number in E.164 format. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/numbers/{phoneId}/sms-requirements`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The number to use.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["phoneNumber"],"properties":{"phoneNumber":{"type":"string","description":"E.164 format.","example":"+14155552600"}}},"example":{"phoneNumber":"+14155552600"}}}},"responses":{"201":{"description":"The updated default","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"phoneNumber is required — `phoneNumber` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"phoneNumber is required","path":"/phone/sms-number","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]},"delete":{"operationId":"PhoneController_clearSmsPhone","summary":"Clear the default SMS number","description":"Removes the default SMS number. Outbound SMS with no explicit sender then has nowhere to send from.\n\n#### Signature\n\n```http\nDELETE /phone/sms-number () -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/sms-number`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/migration/status":{"get":{"operationId":"PhoneController_checkMigrationStatus","summary":"Get phone migration status","description":"Progress of a phone configuration migration.\n\n#### Signature\n\n```http\nGET /phone/migration/status () -> Migration status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /phone/migration/run`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Migration status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"]}},"/phone/migration/run":{"post":{"operationId":"PhoneController_runMigration","summary":"Run the phone migration","description":"Runs the phone configuration migration. An administrative operation that rewrites phone configuration — run it once, deliberately, and check the status afterwards.\n\n#### Signature\n\n```http\nPOST /phone/migration/run (body) -> The migration result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Rewrites configuration across the org's numbers.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /phone/migration/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The migration result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Phone"],"requestBody":{"description":"Optional options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/ai/voice/session":{"post":{"operationId":"VoiceTalkController_start","summary":"Start talking to the in-app assistant","description":"A short-lived token for the browser voice session, and the voice to speak in (the main assistant's voice, talking speed and greeting). Everything said goes to the same in-app agent as the chat.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Voice"]}},"/ai/voice/session/end":{"post":{"operationId":"VoiceTalkController_end","summary":"The voice session ended: body { sessionId, conversationId? }. Charges the minutes talked.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Voice"]}},"/ai/agent/setup":{"get":{"operationId":"AIAgentSetupController_status","summary":"The AI Agent's setup","description":"Whether its voice is on, its own record (open it in the assistant editor to change its voice and instructions), the agreement, and the price.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["AI Agent"]}},"/ai/agent/setup/enable":{"post":{"operationId":"AIAgentSetupController_enable","summary":"Turn on voice for the AI Agent","description":"Accepts the AI Agent agreement (recorded against the signed-in user) and gives the AI Agent its own record in AI Assistants. Deleting that record turns voice off and withdraws the agreement.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["AI Agent"]}},"/jobs/scheduled":{"get":{"operationId":"ScheduledJobsController_list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"jobs","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ jobs: [JobRow], options: { intervals } }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"jobs":[{"job":"readiness-daily","group":"readiness","label":"Readiness daily run","kind":"daily","enabled":true,"available":true,"inUse":true,"time":"04:00","timezone":"America/Los_Angeles","timezoneSetting":"","schedule":"Daily at 04:00 (America/Los_Angeles)","cron":"0 4 * * *","scheduleId":"68f0c2a1e4b0a1b2c3d4e5f6","queued":true,"nextRun":"2026-10-04T11:00:00.000Z","lastRun":{"at":"2026-10-03T11:00:00.120Z","trigger":"schedule","ok":true,"ms":5310,"summary":{"assigned":3},"jobId":"68f0c2a1e4b0a1b2c3d4e5f7"}}],"options":{"intervals":[{"value":10,"label":"Every 10 minutes"}]}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List scheduled jobs","description":"Every recurring job this server runs, for this org: its settings (enabled, time or interval, time zone), the schedule it is on, whether it is queued, the next run and the last run. Runs are spread per business: an interval job runs on a minute offset fixed for this org (every 5 minutes may be `3-59/5`), and a daily job left on its default time runs at a fixed minute up to half an hour after it (`time` shows the real time; a time the business sets is kept exactly). `lastRun` is the last time the job ran or checked: a scheduled run that found nothing (`summary.processed` 0, no errors) writes no `job` record, so `lastRun.jobId` is absent for it. `inUse` says whether the org uses the job (it is scheduled only then). Each run is also a `job` record: GET /jobs?kind=scheduled:<job>. `exact` jobs run once per piece of work at its own time; their row gives `pending` and the next one due.\n\n#### Signature\n\n```http\nGET /jobs/scheduled () -> { jobs: [JobRow], options: { intervals } }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /jobs/scheduled/{job}`\n- `POST /jobs/scheduled/{job}/run`\n- `GET /jobs`","tags":["Scheduled jobs"]}},"/jobs/scheduled/{job}":{"put":{"operationId":"ScheduledJobsController_save","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"job","required":true,"in":"path","schema":{"type":"string"},"description":"The job id, e.g. readiness-daily, journeys-sweep, leave-nightly, a2p-watch, voice-agent-sweep, ai-employee-ping, everify-refresh, broadcast-send, notification-send, external-mail-pull, service-billing, data-purge, social-sync-messages.","example":"readiness-daily"}],"responses":{"200":{"description":"The job's row, as in GET /jobs/scheduled","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job":"readiness-daily","group":"readiness","label":"Readiness daily run","kind":"daily","enabled":true,"available":true,"inUse":true,"time":"05:30","timezone":"America/Chicago","timezoneSetting":"","schedule":"Daily at 04:00 (America/Los_Angeles)","cron":"30 5 * * *","scheduleId":"68f0c2a1e4b0a1b2c3d4e5f6","queued":true,"nextRun":"2026-10-04T11:00:00.000Z","lastRun":{"at":"2026-10-03T11:00:00.120Z","trigger":"schedule","ok":true,"ms":5310,"summary":{"assigned":3},"jobId":"68f0c2a1e4b0a1b2c3d4e5f7"}}}}},"400":{"description":"Use HH:mm, 24-hour — A field is wrong; `problems` lists each `{ field, message }`","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Use HH:mm, 24-hour","path":"/jobs/scheduled/{job}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"There is no scheduled job \"<job>\" — The job id is not registered on this server","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"There is no scheduled job \"<job>\"","path":"/jobs/scheduled/{job}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Change a scheduled job","description":"Turn the job on or off, move its time (daily jobs, `HH:mm` 24-hour) or interval (interval jobs, minutes: 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 720), or give it its own time zone (IANA name; empty = the business time zone). Only the fields sent change. The org's schedule record is updated in place — the cron moves, a turned-off job is stopped — never duplicated. 400 with `problems` when a field is wrong.\n\n#### Signature\n\n```http\nPUT /jobs/scheduled/{job} (job: string, body) -> The job's row, as in GET /jobs/scheduled\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SETTINGS_INVALID | Use HH:mm, 24-hour | A field is wrong; `problems` lists each `{ field, message }` | Fix the named fields and send again. |\n| `404` | JOB_NOT_FOUND | There is no scheduled job \"<job>\" | The job id is not registered on this server | Use a job id from GET /jobs/scheduled. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Scheduled jobs"],"requestBody":{"description":"The fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"enabled":true,"time":"05:30","timezone":"America/Chicago"}}}}}},"/jobs/scheduled/{job}/run":{"post":{"operationId":"ScheduledJobsController_runNow","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"job","required":true,"in":"path","schema":{"type":"string"},"description":"The job id, e.g. readiness-daily, journeys-sweep, leave-nightly, a2p-watch, voice-agent-sweep, ai-employee-ping, everify-refresh, broadcast-send, notification-send, external-mail-pull, service-billing, data-purge, social-sync-messages.","example":"readiness-daily"}],"responses":{"201":{"description":"{ result: { at, trigger, ok, ms, summary?, error?, by, jobId }, job: JobRow }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"There is no scheduled job \"<job>\" — The job id is not registered on this server","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"There is no scheduled job \"<job>\"","path":"/jobs/scheduled/{job}/run","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"<label> is already running — A run of this job for this org holds its lock","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"<label> is already running","path":"/jobs/scheduled/{job}/run","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Run a scheduled job now","description":"Runs the job for this org now and waits for it, even when it is turned off. It holds the same lock as the scheduled run, so it never overlaps one: 409 while it is already running. The run is a `job` record (`result.jobId`) and becomes the job's last run. `args` is passed to the job (an exact job takes the piece of work it should run).\n\n#### Signature\n\n```http\nPOST /jobs/scheduled/{job}/run (job: string, body) -> { result: { at, trigger, ok, ms, summary?, error?, by, jobId }, job: JobRow }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | JOB_NOT_FOUND | There is no scheduled job \"<job>\" | The job id is not registered on this server | Use a job id from GET /jobs/scheduled. |\n| `409` | JOB_RUNNING | <label> is already running | A run of this job for this org holds its lock | Wait for it to finish; its result shows as the last run. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Scheduled jobs"],"requestBody":{"description":"Optional.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"args":{}}}}}}},"/jobs":{"get":{"operationId":"JobsController_list","summary":"List jobs","description":"Newest first. Filter with ?status=queued,running and ?kind=import.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Jobs"]},"post":{"operationId":"JobsController_start","summary":"Start a job","description":"Body: { kind, title?, args?, notify?: { email?, emails?, notice?, on? } }. Returns the job; it runs in the background.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Jobs"]}},"/jobs/{id}":{"get":{"operationId":"JobsController_get","summary":"One job","description":"Status, progress, cursor, result, errors and what was sent when it ended.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Jobs"]}},"/jobs/{id}/cancel":{"post":{"operationId":"JobsController_cancel","summary":"Cancel a running scheduled run","description":"For a run of a recurring job (kind `scheduled:<job>`, status `running`): sets `cancelRequested`. The job checks it between items (`ctx.cancelled()`), stops after the item in hand and the run ends `cancelled`, its result counting what was done (`cancelled: true`). What was done stays done; what was left is picked up by the next run. A run whose server stopped (its lock is gone) is closed as `cancelled` at once. A run that is already over is returned as it is. Jobs that check: a2p-watch, voice-agent-sweep, ai-employee-ping, everify-refresh, broadcast-send, notification-send, service-billing, data-purge, social-sync-* (others finish their run).\n\n#### Signature\n\n```http\nPOST /jobs/{id}/cancel (id: string) -> The run's `job` record (`cancelRequested: true`; `cancelled` once it has stopped).\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /jobs/{id}/retry`\n- `GET /jobs`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The `job` record id (a run), from GET /jobs.","example":"68f0c2a1e4b0a1b2c3d4e5f7"}],"responses":{"201":{"description":"The run's `job` record (`cancelRequested: true`; `cancelled` once it has stopped).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Scheduled jobs"]}},"/jobs/{id}/retry":{"post":{"operationId":"JobsController_retry","summary":"Run a failed scheduled run again","description":"For a run of a recurring job (a `job` record of kind `scheduled:<job>`, status `failed` or `cancelled`): runs that job again now, for this org, with the same `args` — exactly like POST /jobs/scheduled/{job}/run. It is a NEW run with its own `job` record (`retryOf` = this id; this record gets `retriedAs`), which is returned as soon as it has started; it carries on in the background and is polled like any job. The job finds its own work, so the new run picks up whatever is still due — what the failed run already did is not done twice. Other jobs (imports, exports) carry on from their saved cursor instead.\n\n#### Signature\n\n```http\nPOST /jobs/{id}/retry (id: string) -> The new run's `job` record (status `running`).\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | JOB_NOT_RETRYABLE | Only a failed or cancelled run can be run again. | The run is still going, or finished well | Use POST /jobs/scheduled/{job}/run to run it again anyway. |\n| `404` | JOB_NOT_FOUND | This server no longer runs \"<job>\", so it cannot be run again. | The job is not registered on this server any more | Nothing to retry; GET /jobs/scheduled lists the jobs there are. |\n| `409` | JOB_RUNNING | <label> is already running | Another run of the job for this org holds its lock | Wait for it to finish; it does the same work. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /jobs/scheduled/{job}/run`\n- `POST /jobs/{id}/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The `job` record id (a run), from GET /jobs.","example":"68f0c2a1e4b0a1b2c3d4e5f7"}],"responses":{"201":{"description":"The new run's `job` record (status `running`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sk":"68f0c2a1e4b0a1b2c3d4e5f8","data":{"kind":"scheduled:a2p-watch","title":"Text messaging registration check","status":"running","trigger":"manual","retryOf":"68f0c2a1e4b0a1b2c3d4e5f7","requestedBy":"owner@example.com"}}}}},"400":{"description":"Only a failed or cancelled run can be run again. — The run is still going, or finished well","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Only a failed or cancelled run can be run again.","path":"/jobs/{id}/retry","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"This server no longer runs \"<job>\", so it cannot be run again. — The job is not registered on this server any more","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"This server no longer runs \"<job>\", so it cannot be run again.","path":"/jobs/{id}/retry","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"<label> is already running — Another run of the job for this org holds its lock","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"<label> is already running","path":"/jobs/{id}/retry","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Scheduled jobs"]}},"/automation/start/{automationId}":{"post":{"operationId":"AutomationController_startAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Start an automation","description":"Arms the automation's trigger. From this point it runs **unattended** whenever the trigger fires — sending email, writing records, calling external services and, depending on its actions, moving money.\n\nValidate the definition and check the trigger's selectivity first: a trigger that matches more records than intended runs its actions on all of them.\n\n#### Signature\n\n```http\nPOST /automation/start/{automationId} (automationId: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Arms unattended, repeating execution.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/ai/validate`\n- `POST /automation/stop/{automationId}`","tags":["Automation"],"requestBody":{"description":"Optional start options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/automation/stop/{automationId}":{"post":{"operationId":"AutomationController_stopAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Stop an automation","description":"Disarms the trigger so the automation stops firing. Executions already in flight run to completion — stopping is not a kill switch for work already started.\n\n#### Signature\n\n```http\nPOST /automation/stop/{automationId} (automationId: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- In-flight executions still finish.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/start/{automationId}`","tags":["Automation"],"requestBody":{"description":"Optional stop options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/automation/status/{automationId}":{"get":{"operationId":"AutomationController_getAutomationStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"200":{"description":"The status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an automation's status","description":"Whether an automation is running, when it last fired, and its recent outcome.\n\n#### Signature\n\n```http\nGET /automation/status/{automationId} (automationId: string) -> The status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /automation/execution/history`","tags":["Automation"]}},"/automation/health":{"get":{"operationId":"AutomationController_getHealth","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Health","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get automation health","description":"Whether the automation engine is processing — the check to run when nothing seems to be firing.\n\n#### Signature\n\n```http\nGET /automation/health () -> Health\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /automation/dashboard/stats`","tags":["Automation"]}},"/automation/capabilities":{"get":{"operationId":"AutomationController_getCapabilities","parameters":[],"responses":{"200":{"description":""}}}},"/automation/dashboard/stats":{"get":{"operationId":"AutomationController_getDashboardStats","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get automation statistics","description":"Run counts, success and failure rates across the org's automations.\n\n#### Signature\n\n```http\nGET /automation/dashboard/stats () -> Statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /automation/execution/history`","tags":["Automation"]}},"/automation/execution/history":{"get":{"operationId":"AutomationController_getExecutionHistory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":false,"in":"query","schema":{"type":"string"},"example":"AUT-4821"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"example":50},{"name":"offset","required":false,"in":"query","schema":{"type":"integer"},"example":0}],"responses":{"200":{"description":"Executions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get execution history","description":"Past automation runs and their outcomes — the record for working out why something did or did not happen.\n\n#### Signature\n\n```http\nGET /automation/execution/history (automationId?: string, limit?: integer, offset?: integer) -> Executions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /automation/dashboard/stats`","tags":["Automation"]}},"/automation":{"get":{"operationId":"AutomationController_getAutomations","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Automations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List automations","description":"The org's automations and whether each is running.\n\n#### Signature\n\n```http\nGET /automation () -> Automations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /automation/{automationId}`","tags":["Automation"]},"post":{"operationId":"AutomationController_createAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The automation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create an automation","description":"Defines an automation — its trigger, conditions and actions. **Created stopped**: it does nothing until started, which is the safe default for a definition that has not been reviewed.\n\n#### Signature\n\n```http\nPOST /automation (body) -> The automation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Created inactive.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/start/{automationId}`","tags":["Automation"],"requestBody":{"description":"The automation.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Welcome email","trigger":{"type":"record.created","datatype":"customer"},"conditions":[],"actions":[{"type":"send-email","template":"welcome"}]}}}}}},"/automation/executions/{executionId}":{"get":{"operationId":"AutomationController_getRun","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"executionId","required":true,"in":"path","schema":{"type":"string"},"description":"Run id (`exec_…`).","example":"exec_1759000000000_ab12cd"}],"responses":{"200":{"description":"The run","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Run not found — No run with that executionId.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Run not found","path":"/automation/executions/{executionId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a run","description":"One run: its summary, step results, errors, completed steps and the variables it carried.\n\n#### Signature\n\n```http\nGET /automation/executions/{executionId} (executionId: string) -> The run\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RUN_NOT_FOUND | Run not found | No run with that executionId. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Automation"]}},"/automation/executions/{executionId}/cancel":{"post":{"operationId":"AutomationController_cancelRun","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"executionId","required":true,"in":"path","schema":{"type":"string"},"description":"Run id (`exec_…`).","example":"exec_1759000000000_ab12cd"}],"responses":{"201":{"description":"{ cancelled: true, executionId }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"This run has already finished — there is nothing to stop. — The run finished or failed (\"already failed\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This run has already finished — there is nothing to stop.","path":"/automation/executions/{executionId}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Run not found — No run with that executionId.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Run not found","path":"/automation/executions/{executionId}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Stop a run","description":"Cancels a run that is still going.\n\n#### Signature\n\n```http\nPOST /automation/executions/{executionId}/cancel (executionId: string) -> { cancelled: true, executionId }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RUN_NOT_FOUND | Run not found | No run with that executionId. | — |\n| `400` | ALREADY_DONE | This run has already finished — there is nothing to stop. | The run finished or failed (\"already failed\"). | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Automation"]}},"/automation/executions/{executionId}/retry":{"post":{"operationId":"AutomationController_retryRun","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"executionId","required":true,"in":"path","schema":{"type":"string"},"description":"Run id (`exec_…`).","example":"exec_1759000000000_ab12cd"}],"responses":{"201":{"description":"{ success, executionId, retryOf, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Run not found — No run with that executionId.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Run not found","path":"/automation/executions/{executionId}/retry","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Run it again","description":"Runs the automation again now with the same variables, as a new run linked to this one (`retryOf`). Real effects, like any run.\n\n#### Signature\n\n```http\nPOST /automation/executions/{executionId}/retry (executionId: string) -> { success, executionId, retryOf, message }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RUN_NOT_FOUND | Run not found | No run with that executionId. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Automation"]}},"/automation/{automationId}/runs":{"get":{"operationId":"AutomationController_runsLog","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"stepId","in":"query","required":false,"schema":{"type":"string"}},{"name":"outcome","in":"query","required":false,"schema":{"type":"string","enum":["succeeded","failed"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","required":false,"description":"Max 200.","schema":{"type":"integer","default":25}}],"responses":{"200":{"description":"{ total, page, pageSize, pages, data }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Run log","description":"Runs of this automation, newest first, paged. `status` takes a comma-separated list; `stepId` with `outcome` (succeeded | failed) keeps runs where that step had that outcome; `q` searches the runs; `from`/`to` bound the start time.\n\n#### Signature\n\n```http\nGET /automation/{automationId}/runs (automationId: string, status?: string, stepId?: string, outcome?: string, q?: string, from?: string, to?: string, page?: integer, pageSize?: integer) -> { total, page, pageSize, pages, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Automation"]}},"/automation/{automationId}/steps/{stepId}/outcomes":{"get":{"operationId":"AutomationController_stepOutcomes","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"},{"name":"stepId","required":true,"in":"path","schema":{"type":"string"},"description":"Step id in the workflow."},{"name":"outcome","in":"query","required":false,"schema":{"type":"string","enum":["succeeded","failed"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"{ step, totals: { reached, succeeded, failed }, total, page, pageSize, pages, data }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Automation not found — No automation with that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Automation not found","path":"/automation/{automationId}/steps/{stepId}/outcomes","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"One step across runs","description":"For every run that reached this step, newest first: its outcome, duration, what it produced or the error, and where the flow went next. `outcome` narrows to succeeded or failed.\n\n#### Signature\n\n```http\nGET /automation/{automationId}/steps/{stepId}/outcomes (automationId: string, stepId: string, outcome?: string, q?: string, page?: integer, pageSize?: integer) -> { step, totals: { reached, succeeded, failed }, total, page, pageSize, pages, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AUTOMATION_NOT_FOUND | Automation not found | No automation with that id. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Automation"]}},"/automation/{automationId}/monitor":{"get":{"operationId":"AutomationController_monitor","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"},{"name":"days","required":false,"in":"query","schema":{"type":"integer","default":14}}],"responses":{"200":{"description":"{ automation, … }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Automation not found — No automation with that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Automation not found","path":"/automation/{automationId}/monitor","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Monitor an automation","description":"The monitoring page in one call for the last `days` (default 14): the automation and whether its trigger is registered (re-registered first if it had dropped), run counts and rates, runs in flight, per-step figures (ran, failed, average ms, last error) and errors grouped by message.\n\n#### Signature\n\n```http\nGET /automation/{automationId}/monitor (automationId: string, days?: integer) -> { automation, … }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AUTOMATION_NOT_FOUND | Automation not found | No automation with that id. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Automation"]}},"/automation/{automationId}/check":{"get":{"operationId":"AutomationController_checkAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"200":{"description":"{ ready, problems }","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"boolean"},"problems":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Automation not found — No automation with that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Automation not found","path":"/automation/{automationId}/check","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Check an automation before running it","description":"What stands between this workflow and running, step by step, so problems show before anyone presses Start. Nothing is run.\n\n#### Signature\n\n```http\nGET /automation/{automationId}/check (automationId: string) -> { ready, problems }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AUTOMATION_NOT_FOUND | Automation not found | No automation with that id. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["Automation"]}},"/automation/{automationId}":{"get":{"operationId":"AutomationController_getAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"200":{"description":"The automation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an automation","description":"One automation with its trigger, conditions and actions.\n\n#### Signature\n\n```http\nGET /automation/{automationId} (automationId: string) -> The automation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /automation/{automationId}`","tags":["Automation"]},"put":{"operationId":"AutomationController_updateAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"200":{"description":"The updated automation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update an automation","description":"Changes an automation's definition. Editing a **running** automation changes what fires from the next trigger onward — stop it first if the edit is not one you want taking effect mid-way.\n\n#### Signature\n\n```http\nPUT /automation/{automationId} (automationId: string, body) -> The updated automation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Takes effect immediately on a running automation.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/stop/{automationId}`","tags":["Automation"],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"actions":[{"type":"send-email","template":"welcome-v2"}]}}}}},"delete":{"operationId":"AutomationController_deleteAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete an automation","description":"Removes an automation and its execution history. Stop it rather than delete it if the history matters — the record of what it did goes with it.\n\n#### Signature\n\n```http\nDELETE /automation/{automationId} (automationId: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Discards execution history.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/stop/{automationId}`","tags":["Automation"],"requestBody":{"description":"Optional options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/automation/{automationId}/execute":{"post":{"operationId":"AutomationController_executeAutomation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"automationId","required":true,"in":"path","schema":{"type":"string"},"description":"Automation id.","example":"AUT-4821"}],"responses":{"201":{"description":"The execution result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Execute an automation now","description":"Runs an automation immediately, outside its trigger. **Not a dry run** — the actions happen for real, including anything that sends or charges.\n\nUse it to test with a deliberately harmless payload, or to re-run a case that should have fired and did not.\n\n#### Signature\n\n```http\nPOST /automation/{automationId}/execute (automationId: string, body) -> The execution result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Real side effects — not a simulation.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/ai/validate`","tags":["Automation"],"requestBody":{"description":"The payload to run against.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"record":{"id":"CUST-4821","email":"ada@example.com"}}}}}}},"/automation/ai/generate":{"post":{"operationId":"AutomationAiController_generateAutomation","summary":"Generate an automation from a description","description":"Drafts an automation definition from plain language. The output is a **draft**: it is created stopped and should be read before being armed, because a plausible-looking trigger can match far more than intended.\n\nConsumes AI credit.\n\n#### Signature\n\n```http\nPOST /automation/ai/generate (body) -> The drafted automation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Review before starting. Consumes AI credit.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/ai/validate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What the automation should do.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"prompt":"When a new customer signs up, wait a day, then email them a getting-started guide."}}}},"responses":{"200":{"description":"Returns the generated automation workflow JSON","content":{"application/json":{"schema":{"type":"object","properties":{"workflow":{"type":"object","description":"Generated automation workflow"},"explanation":{"type":"string","description":"Human-readable explanation of the generated automation"},"confidence":{"type":"number","description":"AI confidence score (0-1)"}}}}}},"201":{"description":"The drafted automation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Automation"]}},"/automation/ai/improve":{"post":{"operationId":"AutomationAiController_improveAutomation","summary":"Suggest automation improvements","description":"Reviews an existing automation and suggests changes. Suggestions only — nothing is applied.\n\n#### Signature\n\n```http\nPOST /automation/ai/improve (body) -> Suggestions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Read-only. Consumes AI credit.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /automation/{automationId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The automation to review.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"automationId":"AUT-4821"}}}},"responses":{"201":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Automation"]}},"/automation/ai/validate":{"post":{"operationId":"AutomationAiController_validateAutomation","summary":"Validate an automation","description":"Checks an automation definition for problems before it is armed — missing fields, unreachable conditions, actions that will fail. The cheap check to run between drafting and starting.\n\n#### Signature\n\n```http\nPOST /automation/ai/validate (body) -> The validation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/start/{automationId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The definition to check.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"trigger":{"type":"record.created","datatype":"customer"},"actions":[{"type":"send-email","template":"welcome"}]}}}},"responses":{"201":{"description":"The validation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Automation"]}},"/automation/ai/templates":{"post":{"operationId":"AutomationAiController_getAutomationTemplates","summary":"Get automation templates","description":"Suggested starting points for a described goal — templates to adapt rather than write from scratch.\n\n#### Signature\n\n```http\nPOST /automation/ai/templates (body) -> Templates\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /automation/ai/generate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Templates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Automation"],"requestBody":{"description":"What you are trying to automate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"goal":"follow up on abandoned carts"}}}}}},"/enrichment/search/persons":{"post":{"operationId":"DataEnrichmentController_searchPersons","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Matching people","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search for people","description":"Searches provider data for people matching criteria. Each search calls an external provider and typically consumes credit with them.\n\n#### Signature\n\n```http\nPOST /enrichment/search/persons (body) -> Matching people\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Calls a paid third-party provider.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /enrichment/person`","tags":["Data enrichment"],"requestBody":{"description":"Search criteria.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Ada Lovelace","company":"Acme"}}}}}},"/enrichment/search/companies":{"post":{"operationId":"DataEnrichmentController_searchCompanies","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Matching companies","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search for companies","description":"Searches provider data for companies matching criteria.\n\n#### Signature\n\n```http\nPOST /enrichment/search/companies (body) -> Matching companies\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Calls a paid third-party provider.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /enrichment/company`","tags":["Data enrichment"],"requestBody":{"description":"Search criteria.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Acme","domain":"acme.example"}}}}}},"/enrichment/person":{"post":{"operationId":"DataEnrichmentController_enrichPerson","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The enriched profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Enrich a person","description":"Looks up additional data for one person from an identifier — usually an email address. The data comes from a third party and can be stale or wrong; treat it as a hint, not a fact about a real individual.\n\n#### Signature\n\n```http\nPOST /enrichment/person (body) -> The enriched profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Third-party data — accuracy is not guaranteed.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /enrichment/bulk`","tags":["Data enrichment"],"requestBody":{"description":"Who to enrich.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}}}},"/enrichment/company":{"post":{"operationId":"DataEnrichmentController_enrichCompany","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The enriched company","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Enrich a company","description":"Looks up additional data for a company, usually from its domain.\n\n#### Signature\n\n```http\nPOST /enrichment/company (body) -> The enriched company\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Third-party data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /enrichment/person`","tags":["Data enrichment"],"requestBody":{"description":"Which company.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"acme.example"}}}}}},"/enrichment/validate-email":{"post":{"operationId":"DataEnrichmentController_validateEmail","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Validate an email address","description":"Checks an address for deliverability through the provider. Worth running before adding an address to a send list — invalid addresses cause bounces, which damage sender reputation.\n\n#### Signature\n\n```http\nPOST /enrichment/validate-email (body) -> Validation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /broadcast/validate/email/{email}`","tags":["Data enrichment"],"requestBody":{"description":"The address.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}}}},"/enrichment/bulk":{"post":{"operationId":"DataEnrichmentController_bulkEnrich","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Per-record results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Bulk enrich","description":"Enriches many records in one call. Each record is a provider lookup, so cost and duration scale with the list — check the provider's credit before submitting a large batch.\n\n#### Signature\n\n```http\nPOST /enrichment/bulk (body) -> Per-record results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Cost scales with the batch size.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /enrichment/person`","tags":["Data enrichment"],"requestBody":{"description":"The records to enrich.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"type":"person","items":[{"email":"ada@example.com"},{"email":"grace@example.com"}]}}}}}},"/enrichment/providers":{"get":{"operationId":"DataEnrichmentController_getProviders","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Providers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List enrichment providers","description":"The third-party data providers available for enrichment.\n\n#### Signature\n\n```http\nGET /enrichment/providers () -> Providers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /enrichment/providers/{name}/status`","tags":["Data enrichment"]}},"/enrichment/providers/{name}/status":{"get":{"operationId":"DataEnrichmentController_getProviderStatus","parameters":[{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Provider name.","example":"clearbit"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Provider status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a provider's status","description":"Whether a provider is reachable and configured — the check when enrichment starts returning nothing.\n\n#### Signature\n\n```http\nGET /enrichment/providers/{name}/status (name: string) -> Provider status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /enrichment/providers`","tags":["Data enrichment"]}},"/enrichment/cache/clear":{"post":{"operationId":"DataEnrichmentController_clearCache","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Clear the enrichment cache","description":"Drops cached provider responses. The next lookups go back to the provider and are charged again — clear it when data is known stale, not as routine housekeeping.\n\n#### Signature\n\n```http\nPOST /enrichment/cache/clear () -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Subsequent lookups are re-charged.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /enrichment/person`","tags":["Data enrichment"]}},"/storefront/data/{siteId}":{"get":{"operationId":"StorefrontController_data","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"siteId","required":true,"in":"path","schema":{"type":"string"},"description":"Site `sk` or `name`. Identifies which site configuration (filters, currencies) to bundle.","example":"main-store"},{"name":"brand","in":"query","required":false,"description":"Brand name, matched case-insensitively. Repeat for several brands.","schema":{"type":"string"},"example":"fizzco"},{"name":"collection","in":"query","required":false,"description":"Restrict the `collectionDTO` bundle to this collection name.","schema":{"type":"string"}},{"name":"categories","in":"query","required":false,"description":"Comma-separated category names. Matched case-insensitively against `post.categories`.","schema":{"type":"string"},"example":"cold-drinks,featured"},{"name":"category","in":"query","required":false,"description":"Single category name. Alias for a one-value `categories`.","schema":{"type":"string"},"example":"cold-drinks"},{"name":"tags","in":"query","required":false,"description":"Comma-separated tags, matched case-insensitively against `post.tags`.","schema":{"type":"string"},"example":"summer,sale"},{"name":"tag","in":"query","required":false,"description":"Single tag. Alias for a one-value `tags`.","schema":{"type":"string"}},{"name":"keyword","in":"query","required":false,"description":"Search words. Every word must appear, case-insensitively and as any part of a word, in the product's values (name, description, sku, variant skus, brand, attribute options) or its categories, tags or post title.","schema":{"type":"string"},"example":"cola"},{"name":"minPrice","in":"query","required":false,"description":"Lower price bound, inclusive.","schema":{"type":"number"},"example":5},{"name":"maxPrice","in":"query","required":false,"description":"Upper price bound, inclusive.","schema":{"type":"number"},"example":50},{"name":"<attribute>","in":"query","required":false,"description":"Any query parameter that is not a reserved name is treated as a product attribute facet, comma-separated for multiple values — e.g. `?size=330ml,500ml&color=red`. Matched against `data.attributes[].options[].value`.","schema":{"type":"string"},"example":"330ml,500ml"},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"l","in":"query","required":false,"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth.","schema":{"type":"string"}},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"}],"responses":{"200":{"description":"The full landing-page bundle","content":{"application/json":{"schema":{"type":"object","properties":{"brandDTO":{"type":"object","description":"Brands, paged.","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}},"collectionDTO":{"type":"object","description":"Collections, paged.","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}},"filters":{"type":"object","additionalProperties":true,"description":"Facet configuration from the site record (`data.storefront.filters`)."},"productDTO":{"type":"object","description":"The product page matching the supplied filters.","properties":{"data":{"type":"array","items":{"type":"object","description":"A storefront product (`sf_product`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"cola-330ml"},"title":{"type":"string","example":"Cola 330ml"},"price":{"type":"number","example":12},"brand":{"type":"string","example":"fizzco"},"hide":{"type":"boolean","description":"When true the product is excluded from every storefront listing.","example":false},"attributes":{"type":"array","description":"Faceted attributes, each with selectable options.","items":{"type":"object","properties":{"name":{"type":"string","example":"size"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","example":"330ml"}}}}}}},"calculatedPrice":{"type":"object","description":"Price resolved for the calling customer at read time — tier discounts, promotions and rules already applied. Never cache this across customers.","properties":{"originalPrice":{"type":"number","description":"List price before any discount.","example":12},"finalPrice":{"type":"number","description":"Price the customer actually pays.","example":9.6},"discount":{"type":"number","description":"Absolute amount discounted.","example":2.4},"discountPercent":{"type":"number","description":"Discount as a percentage of `originalPrice`.","example":20},"appliedRule":{"type":"object","additionalProperties":true,"description":"The pricing rule that won, if any."},"appliedDiscounts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Every discount that contributed."},"freeShipping":{"type":"boolean","description":"Whether the winning rule grants free shipping.","example":false}}}}}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}},"currencies":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Currencies enabled on the site."},"minMaxPrice":{"type":"object","nullable":true,"description":"Catalog price bounds, for a price-range slider. `null` when the catalog is empty.","properties":{"minPrice":{"type":"number","example":1.5},"maxPrice":{"type":"number","example":499}}},"categories":{"type":"array","items":{"type":"object","description":"A node in the storefront category tree.","properties":{"name":{"type":"string","description":"Slug, unique across the entire tree. This is the value products carry in `post.categories`.","example":"cold-drinks"},"title":{"type":"string","description":"Display title.","example":"Cold Drinks"},"description":{"type":"string","description":"Category description.","example":"Chilled sodas, juices and water"},"image":{"type":"object","description":"Platform file reference.","properties":{"url":{"type":"string","description":"Publicly resolvable URL.","example":"https://cdn.appmint.io/acme/cold-drinks.png"},"path":{"type":"string","description":"Storage path within the org bucket."},"contentType":{"type":"string","example":"image/png"},"size":{"type":"integer","description":"Bytes."},"meta":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata carried with the file."}}},"children":{"type":"array","description":"Nested child categories. Empty for a leaf.","items":{"type":"object","description":"Recursive category node."}}}},"description":"The storefront category tree."},"featuredProductDTO":{"type":"object","description":"Up to 10 products in the `featured` category.","properties":{"data":{"type":"array","items":{"type":"object","description":"A storefront product (`sf_product`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"cola-330ml"},"title":{"type":"string","example":"Cola 330ml"},"price":{"type":"number","example":12},"brand":{"type":"string","example":"fizzco"},"hide":{"type":"boolean","description":"When true the product is excluded from every storefront listing.","example":false},"attributes":{"type":"array","description":"Faceted attributes, each with selectable options.","items":{"type":"object","properties":{"name":{"type":"string","example":"size"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","example":"330ml"}}}}}}},"calculatedPrice":{"type":"object","description":"Price resolved for the calling customer at read time — tier discounts, promotions and rules already applied. Never cache this across customers.","properties":{"originalPrice":{"type":"number","description":"List price before any discount.","example":12},"finalPrice":{"type":"number","description":"Price the customer actually pays.","example":9.6},"discount":{"type":"number","description":"Absolute amount discounted.","example":2.4},"discountPercent":{"type":"number","description":"Discount as a percentage of `originalPrice`.","example":20},"appliedRule":{"type":"object","additionalProperties":true,"description":"The pricing rule that won, if any."},"appliedDiscounts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Every discount that contributed."},"freeShipping":{"type":"boolean","description":"Whether the winning rule grants free shipping.","example":false}}}}}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}}}}}}},"404":{"description":"Site 'main-store' not found — `siteId` matches no site record in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Site 'main-store' not found","path":"/storefront/data/{siteId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"],"summary":"Get everything a storefront landing page needs","description":"One round trip that returns the full payload for a storefront home page: site configuration, brands, collections, a product page, the catalog price bounds, the category tree and a featured-products bundle.\n\nUse this instead of calling `/brands`, `/collections`, `/products` and `/categories` separately — it is a single query pass on the server and avoids four round trips from the browser.\n\nEvery list-shaped query parameter (`brand`, `collection`, paging, sorting) and every product filter is forwarded to the underlying list calls, so the same filtering vocabulary as `GET /storefront/products` applies.\n\n#### Signature\n\n```http\nGET /storefront/data/{siteId} (siteId: string, brand?: string, collection?: string, categories?: string, category?: string, tags?: string, tag?: string, brand?: string, keyword?: string, minPrice?: number, maxPrice?: number, <attribute>?: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string) -> The full landing-page bundle\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- `featuredProductDTO` is always the first 10 products in the `featured` category and ignores your filters.\n- Products with `data.hide: true` are excluded from every bundle in this response.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SITE_NOT_FOUND | Site 'main-store' not found | `siteId` matches no site record in the org. | Check the site `name` or `sk`. Sites are listed under the site management API. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/products`\n- `GET /storefront/categories`"}},"/storefront/currencies":{"get":{"operationId":"StorefrontController_currencies","summary":"Currencies a shopper can buy in","description":"The currencies the request's site sells in (site.currencies, kept to the org's base and approved currencies with a rate; empty = the base only): code and name on each row (with `selected` and `base` flags), `selected` = the one this request buys in (the `currency` in x-client-info when the site offers it, else the site default, else the base), and `base`. Every price the storefront returns is in `selected`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront"]}},"/storefront/store-locations":{"get":{"operationId":"StorefrontController_storeLocations","summary":"Stores a shopper can choose","description":"The business locations the request's site serves (site.storefront.businessLocations), in the site's order: name (the id the storefront sends back as `x-store-location`, or `storeLocation` in x-client-info), title, address, phone, timezone, opening hours. `selected` is the store the request named when the site serves it. A site serving no locations returns an empty list.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront"]}},"/storefront/brands/{brand}":{"get":{"operationId":"StorefrontController_brands","summary":"List brands","description":"Returns the brands (`sf_brand`) defined for the org, paged. Supply the `brand` path segment to fetch one brand by its exact `name`; omit it to list all of them.\n\n#### Signature\n\n```http\nGET /storefront/brands/{brand} (brand: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string) -> A page of brand records\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Matching on `brand` is exact, not a prefix or substring search.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/products`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"l","required":false,"in":"query","description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth.","schema":{"type":"string"}},{"name":"st","required":false,"in":"query","description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"},{"name":"s","required":false,"in":"query","description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"ps","required":false,"in":"query","description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"p","required":false,"in":"query","description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"brand","required":true,"in":"path","description":"Exact brand `name`. Omit the segment entirely to list every brand.","schema":{"type":"string"},"example":"fizzco"}],"responses":{"200":{"description":"A page of brand records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A brand (`sf_brand`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}},"example":{"data":[{"id":"66f1a2b3c4d5e6f708192a3b","datatype":"sf_brand","name":"fizzco","title":"FizzCo","data":{"name":"fizzco","title":"FizzCo","logo":null}}],"total":1,"page":1,"pageSize":50}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"]}},"/storefront/attributes/{attribute}":{"get":{"operationId":"StorefrontController_attributes","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"attribute","in":"path","required":true,"description":"Exact attribute `name`.","schema":{"type":"string"},"example":"size"}],"responses":{"200":{"description":"A page of attribute records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A filter attribute (`sf_attribute`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"],"summary":"List storefront filter attributes","description":"Returns the faceted filter attributes (`sf_attribute`) used to build storefront filter UI, sorted by `filterPosition` ascending. Supply `attribute` to fetch one by exact `name`.\n\n#### Signature\n\n```http\nGET /storefront/attributes/{attribute} (attribute: string) -> A page of attribute records\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- **Legacy behaviour, verified in `StorefrontCatalogService.getAttributes`:** when the `attribute` segment is omitted this endpoint returns **brands** (`sf_brand`), not attributes. To list all attributes you must currently read them through the repository API. Treat the no-argument form as unreliable and do not build against it.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/brands/{brand}`"}},"/storefront/collections/{collection}":{"get":{"operationId":"StorefrontController_collections","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"l","required":false,"in":"query","schema":{"type":"string"},"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth."},{"name":"collection","in":"path","required":true,"description":"Exact collection `name`.","schema":{"type":"string"},"example":"summer-2026"},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans. Defaults to 100 here.","schema":{"type":"integer","default":100},"example":50},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"}],"responses":{"200":{"description":"A page of collection records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A collection (`sf_collection`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"],"summary":"List collections","description":"Returns merchandising collections (`sf_collection`), paged. Supply `collection` to fetch one by exact `name`.\n\n#### Signature\n\n```http\nGET /storefront/collections/{collection} (collection: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string) -> A page of collection records\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`."}},"/storefront/products":{"get":{"operationId":"StorefrontController_products","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"categories","in":"query","required":false,"description":"Comma-separated category names. Matched case-insensitively against `post.categories`.","schema":{"type":"string"},"example":"cold-drinks,featured"},{"name":"category","in":"query","required":false,"description":"Single category name. Alias for a one-value `categories`.","schema":{"type":"string"},"example":"cold-drinks"},{"name":"tags","in":"query","required":false,"description":"Comma-separated tags, matched case-insensitively against `post.tags`.","schema":{"type":"string"},"example":"summer,sale"},{"name":"tag","in":"query","required":false,"description":"Single tag. Alias for a one-value `tags`.","schema":{"type":"string"}},{"name":"brand","in":"query","required":false,"description":"Brand name, matched case-insensitively. Repeat for several brands.","schema":{"type":"string"},"example":"fizzco"},{"name":"keyword","in":"query","required":false,"description":"Search words. Every word must appear, case-insensitively and as any part of a word, in the product's values (name, description, sku, variant skus, brand, attribute options) or its categories, tags or post title.","schema":{"type":"string"},"example":"cola"},{"name":"minPrice","in":"query","required":false,"description":"Lower price bound, inclusive.","schema":{"type":"number"},"example":5},{"name":"maxPrice","in":"query","required":false,"description":"Upper price bound, inclusive.","schema":{"type":"number"},"example":50},{"name":"<attribute>","in":"query","required":false,"description":"Any query parameter that is not a reserved name is treated as a product attribute facet, comma-separated for multiple values — e.g. `?size=330ml,500ml&color=red`. Matched against `data.attributes[].options[].value`.","schema":{"type":"string"},"example":"330ml,500ml"},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"l","in":"query","required":false,"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth.","schema":{"type":"string"}},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"modifydate"},"example":"modifydate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"},{"name":"random","in":"query","required":false,"description":"Return results in random order instead of by `s`/`st`. `true` samples afresh each call (a small featured strip); any other value is a seed (see `seed`), so the order repeats. Empty, `false`, `0` or `no`: not random.","schema":{"type":"string"}},{"name":"seed","in":"query","required":false,"description":"With `random`: a value (up to 64 characters) that fixes the shuffled order, so every page and every larger `pageSize` of the same seed continues the same order with no product twice. Give each visitor their own seed for a shuffled listing that pages or loads more.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of products, each with calculated pricing, plus catalog price bounds","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A storefront product (`sf_product`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"cola-330ml"},"title":{"type":"string","example":"Cola 330ml"},"price":{"type":"number","example":12},"brand":{"type":"string","example":"fizzco"},"hide":{"type":"boolean","description":"When true the product is excluded from every storefront listing.","example":false},"attributes":{"type":"array","description":"Faceted attributes, each with selectable options.","items":{"type":"object","properties":{"name":{"type":"string","example":"size"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","example":"330ml"}}}}}}},"calculatedPrice":{"type":"object","description":"Price resolved for the calling customer at read time — tier discounts, promotions and rules already applied. Never cache this across customers.","properties":{"originalPrice":{"type":"number","description":"List price before any discount.","example":12},"finalPrice":{"type":"number","description":"Price the customer actually pays.","example":9.6},"discount":{"type":"number","description":"Absolute amount discounted.","example":2.4},"discountPercent":{"type":"number","description":"Discount as a percentage of `originalPrice`.","example":20},"appliedRule":{"type":"object","additionalProperties":true,"description":"The pricing rule that won, if any."},"appliedDiscounts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Every discount that contributed."},"freeShipping":{"type":"boolean","description":"Whether the winning rule grants free shipping.","example":false}}}}}}},"description":"The page of records."},"total":{"type":"integer","description":"Total matching records, ignoring pagination."},"page":{"type":"integer","description":"Page number echoed back."},"pageSize":{"type":"integer","description":"Page size echoed back."}}},{"type":"object","properties":{"minMaxPrice":{"type":"object","nullable":true,"description":"Catalog price bounds, for a price-range slider. `null` when the catalog is empty.","properties":{"minPrice":{"type":"number","example":1.5},"maxPrice":{"type":"number","example":499}}}}}]},"example":{"data":[{"id":"66f1a2b3c4d5e6f708192a3b","datatype":"sf_product","name":"cola-330ml","title":"Cola 330ml","data":{"sku":"DRK-COLA-330","title":"Cola 330ml","price":12,"brand":"fizzco","hide":false,"calculatedPrice":{"originalPrice":12,"finalPrice":9.6,"discount":2.4,"discountPercent":20,"appliedRule":{"name":"summer-sale"},"appliedDiscounts":[{"name":"summer-sale","amount":2.4}],"freeShipping":false}}}],"total":1,"page":1,"pageSize":50,"minMaxPrice":{"minPrice":1.5,"maxPrice":499}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"],"summary":"List and search products","description":"The main catalog query. Filters on categories, tags, brand, price range and arbitrary product attributes, then enriches every result with `data.calculatedPrice` resolved for the calling customer.\n\n**Attribute filtering is open-ended.** Any query parameter that is not one of the reserved names (`keyword`, `categories`, `category`, `tags`, `tag`, `brand`, `price`, `minPrice`, `maxPrice`, `sort`, `sortType`, `random`, `page`, `pageSize`, `lastItem`, `sort_by`, and the short forms `p`, `ps`, `s`, `st`, `l`) is treated as a product attribute facet. So `?size=330ml,500ml&color=red` filters on the `size` and `color` attributes with no server configuration.\n\nText matching on categories, tags and brands is **case-insensitive and exact per value** — `cold-drinks` matches `Cold-Drinks` but not `cold-drinks-large`.\n\n#### Signature\n\n```http\nGET /storefront/products (categories?: string, category?: string, tags?: string, tag?: string, brand?: string, keyword?: string, minPrice?: number, maxPrice?: number, <attribute>?: string, p?: integer, ps?: integer, l?: string, s?: string, st?: string, random?: string, seed?: string) -> A page of products, each with calculated pricing, plus catalog price bounds\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Products with `data.hide: true` are never returned. Products without the field are returned.\n- `calculatedPrice` depends on who is calling — an anonymous request and a signed-in customer can see different `finalPrice` values for the same product. Do not cache the response across customers.\n- If pricing fails for an individual product, that product is returned without `calculatedPrice` rather than failing the whole request. Clients should fall back to `data.price`.\n- Prefer the `l` cursor over large `p` values: deep offset paging degrades on big catalogs.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/product/{id}`\n- `GET /storefront/data/{siteId}`"}},"/storefront/product/{id}":{"get":{"operationId":"StorefrontController_productBySlug","summary":"Get a product","description":"Fetches one product and enriches it with `data.calculatedPrice` for the calling customer at quantity 1.\n\nThe `id` segment is flexible: the record `sk`, the product `name` (its URL slug) or the `sku` all resolve, so a storefront can route `/p/cola-330ml` straight through without a lookup table.\n\n#### Signature\n\n```http\nGET /storefront/product/{id} (id: string) -> The product with calculated pricing, or `null` when `id` is empty\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A product that does not exist resolves to `null` with a `200`, not a `404`. Check for a null body.\n- Pricing is computed at quantity 1. Quantity-tiered prices are resolved at cart time, not here.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/products`\n- `GET /storefront/product/{id}/related`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Product `sk`, `name` (slug) or `sku`.","schema":{"type":"string"},"example":"cola-330ml"}],"responses":{"200":{"description":"The product with calculated pricing, or `null` when `id` is empty","content":{"application/json":{"schema":{"type":"object","description":"A storefront product (`sf_product`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"cola-330ml"},"title":{"type":"string","example":"Cola 330ml"},"price":{"type":"number","example":12},"brand":{"type":"string","example":"fizzco"},"hide":{"type":"boolean","description":"When true the product is excluded from every storefront listing.","example":false},"attributes":{"type":"array","description":"Faceted attributes, each with selectable options.","items":{"type":"object","properties":{"name":{"type":"string","example":"size"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","example":"330ml"}}}}}}},"calculatedPrice":{"type":"object","description":"Price resolved for the calling customer at read time — tier discounts, promotions and rules already applied. Never cache this across customers.","properties":{"originalPrice":{"type":"number","description":"List price before any discount.","example":12},"finalPrice":{"type":"number","description":"Price the customer actually pays.","example":9.6},"discount":{"type":"number","description":"Absolute amount discounted.","example":2.4},"discountPercent":{"type":"number","description":"Discount as a percentage of `originalPrice`.","example":20},"appliedRule":{"type":"object","additionalProperties":true,"description":"The pricing rule that won, if any."},"appliedDiscounts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Every discount that contributed."},"freeShipping":{"type":"boolean","description":"Whether the winning rule grants free shipping.","example":false}}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"]}},"/storefront/product/{id}/stock":{"get":{"operationId":"StorefrontController_productStock","summary":"What can be bought of a product now","description":"Per SKU (the product and its variations), the available quantity: at the site region when the site serves one, else summed over stock locations. Counted as region stock and the in-stock filter count. tracked: false when the product keeps no stock count.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Product sk, slug or sku","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront"]}},"/storefront/product/{id}/related":{"get":{"operationId":"StorefrontController_productRelated","summary":"Get related products","description":"Products related to the given one, as the storefront lists them: hidden products and products not sold in the request's region are left out, and each carries `data.calculatedPrice` for the calling customer. Products sharing one of its `post.categories` come first, then products sharing one of its `post.tags`; the product itself never appears.\n\n#### Signature\n\n```http\nGET /storefront/product/{id}/related (id: string, limit?: number)\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Empty `data` when the product has no categories or tags, or its `post.showRelated` is false.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Product <id> not found | No product has that sk, slug or sku. | Pass the id of an existing product. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/product/{id}`\n- `GET /storefront/products`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"limit","required":false,"in":"query","description":"How many to return. Default 8, at most 24.","schema":{"type":"number"},"example":4},{"name":"id","required":true,"in":"path","description":"Product `sk`, `name` (slug) or `sku`.","schema":{"type":"string"},"example":"DRK-COLA-330"}],"responses":{"200":{"description":""},"404":{"description":"Product <id> not found — No product has that sk, slug or sku.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Product <id> not found","path":"/storefront/product/{id}/related","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"]}},"/storefront/categories":{"get":{"operationId":"StorefrontController_categories","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The root category's children, or `[]` when the tree is empty","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A node in the storefront category tree.","properties":{"name":{"type":"string","description":"Slug, unique across the entire tree. This is the value products carry in `post.categories`.","example":"cold-drinks"},"title":{"type":"string","description":"Display title.","example":"Cold Drinks"},"description":{"type":"string","description":"Category description.","example":"Chilled sodas, juices and water"},"image":{"type":"object","description":"Platform file reference.","properties":{"url":{"type":"string","description":"Publicly resolvable URL.","example":"https://cdn.appmint.io/acme/cold-drinks.png"},"path":{"type":"string","description":"Storage path within the org bucket."},"contentType":{"type":"string","example":"image/png"},"size":{"type":"integer","description":"Bytes."},"meta":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata carried with the file."}}},"children":{"type":"array","description":"Nested child categories. Empty for a leaf.","items":{"type":"object","description":"Recursive category node."}}}}},"example":[{"name":"drinks","title":"Drinks","description":"Everything to drink","children":[{"name":"cold-drinks","title":"Cold Drinks","description":"Chilled sodas, juices and water","children":[]}]}]}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"],"summary":"Get the storefront category tree","description":"Returns the storefront category tree as a nested array.\n\nThe tree is not one record per category — it lives entirely in the `children` array of a single `category` record named `storefront`. The `category` collection is shared across domains (CRM, content, storefront), each with its own root, which is why every storefront category call resolves that root first.\n\nThe root is created on demand, so a brand-new org gets `[]` rather than an error.\n\n#### Signature\n\n```http\nGET /storefront/categories () -> The root category's children, or `[]` when the tree is empty\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- The root `storefront` node itself is never returned — only its children.\n- Calling this on a fresh org has a side effect: it creates the root `category` record.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/categories`"},"post":{"operationId":"StorefrontController_addCategory","summary":"Add a storefront category","description":"Adds a category to the storefront tree. It always lands under the root `storefront` category, which is created automatically if the org does not have one yet. Pass `parent` (an existing category name) to nest it one level deeper instead of at the top level.\n\n**Idempotent.** Posting a name that already exists *anywhere* in the tree returns that node unchanged, with a `201`, and writes nothing. Retrying a request whose response you lost is therefore safe.\n\n**Names are slugified and globally unique.** `name` (or `title` when `name` is absent) is lowercased, non-alphanumeric runs collapse to `-`, leading and trailing dashes are trimmed and the result is cut to 50 characters — so `\"Cold Drinks\"` is stored as `cold-drinks`. Uniqueness is enforced across the whole tree, not just among siblings, because `name` is the only thing a product carries in `post.categories`; two nodes sharing a name would each list the other's products.\n\n`parent` is matched by name anywhere in the tree, so you can nest under a category without knowing its path.\n\n#### Signature\n\n```http\nPOST /storefront/categories (body) -> The added (or already-existing) node, plus the full tree\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- The write is a partial update on `data.children` only, so the root record's other fields — and every other root sharing the `category` collection — are untouched.\n- There is no update or delete endpoint for storefront categories; edit the `category` record named `storefront` through the repository API.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CATEGORY_NAME_REQUIRED | Category name is required | Neither `name` nor `title` is supplied, or the value slugifies to an empty string (e.g. `\"!!!\"`). | Send a `name` containing at least one alphanumeric character. |\n| `404` | PARENT_NOT_FOUND | Parent category 'drinks' not found | `parent` is set but no category with that name exists anywhere in the tree. | Create the parent first, or call `GET /storefront/categories` to see the available names. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/categories`\n- `GET /storefront/products`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The category to add. Same shape as the `category` model, plus an optional `parent`.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":50,"description":"Slugified before storing (`^[a-zA-Z_\\-0-9]*$`). This is the value products carry in `post.categories`, and it must be unique across the whole storefront tree.","example":"Cold Drinks"},"title":{"type":"string","description":"Display title. Defaults to `name` as given.","example":"Cold Drinks"},"description":{"type":"string","description":"Category description.","example":"Chilled sodas, juices and water"},"image":{"type":"object","description":"Platform file reference.","properties":{"url":{"type":"string","description":"Publicly resolvable URL.","example":"https://cdn.appmint.io/acme/cold-drinks.png"},"path":{"type":"string","description":"Storage path within the org bucket."},"contentType":{"type":"string","example":"image/png"},"size":{"type":"integer","description":"Bytes."},"meta":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata carried with the file."}}},"parent":{"type":"string","description":"Name of an existing category to nest under, matched anywhere in the tree. Omit for a top-level category.","example":"drinks"}}},"examples":{"topLevel":{"summary":"Top-level category","description":"Lands directly under the storefront root.","value":{"name":"Drinks","description":"Everything to drink"}},"nested":{"summary":"Nested under an existing category","description":"`parent` is matched by name anywhere in the tree.","value":{"name":"Cold Drinks","title":"Cold Drinks","description":"Chilled sodas, juices and water","parent":"drinks"}},"withImage":{"summary":"With a category image","description":"`image` takes the platform FileInfo shape and is stored verbatim.","value":{"name":"Cold Drinks","parent":"drinks","image":{"url":"https://cdn.appmint.io/acme/cold-drinks.png","path":"acme/cold-drinks.png","contentType":"image/png"}}}}}}},"responses":{"201":{"description":"The added (or already-existing) node, plus the full tree","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"object","description":"The node as stored. On a repeat call, the pre-existing node.","properties":{"name":{"type":"string","description":"Slug, unique across the entire tree. This is the value products carry in `post.categories`.","example":"cold-drinks"},"title":{"type":"string","description":"Display title.","example":"Cold Drinks"},"description":{"type":"string","description":"Category description.","example":"Chilled sodas, juices and water"},"image":{"type":"object","description":"Platform file reference.","properties":{"url":{"type":"string","description":"Publicly resolvable URL.","example":"https://cdn.appmint.io/acme/cold-drinks.png"},"path":{"type":"string","description":"Storage path within the org bucket."},"contentType":{"type":"string","example":"image/png"},"size":{"type":"integer","description":"Bytes."},"meta":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata carried with the file."}}},"children":{"type":"array","description":"Nested child categories. Empty for a leaf.","items":{"type":"object","description":"Recursive category node."}}}},"categories":{"type":"array","items":{"type":"object","description":"A node in the storefront category tree.","properties":{"name":{"type":"string","description":"Slug, unique across the entire tree. This is the value products carry in `post.categories`.","example":"cold-drinks"},"title":{"type":"string","description":"Display title.","example":"Cold Drinks"},"description":{"type":"string","description":"Category description.","example":"Chilled sodas, juices and water"},"image":{"type":"object","description":"Platform file reference.","properties":{"url":{"type":"string","description":"Publicly resolvable URL.","example":"https://cdn.appmint.io/acme/cold-drinks.png"},"path":{"type":"string","description":"Storage path within the org bucket."},"contentType":{"type":"string","example":"image/png"},"size":{"type":"integer","description":"Bytes."},"meta":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata carried with the file."}}},"children":{"type":"array","description":"Nested child categories. Empty for a leaf.","items":{"type":"object","description":"Recursive category node."}}}},"description":"The complete storefront tree after the write."}}},"example":{"category":{"name":"cold-drinks","title":"Cold Drinks","description":"Chilled sodas, juices and water","children":[]},"categories":[{"name":"drinks","title":"Drinks","description":"","children":[{"name":"cold-drinks","title":"Cold Drinks","description":"Chilled sodas, juices and water","children":[]}]}]}}}},"400":{"description":"Category name is required — Neither `name` nor `title` is supplied, or the value slugifies to an empty string (e.g. `\"!!!\"`).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Category name is required","path":"/storefront/categories","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Parent category 'drinks' not found — `parent` is set but no category with that name exists anywhere in the tree.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Parent category 'drinks' not found","path":"/storefront/categories","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"],"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://api.appmint.io/storefront/categories \\\n  -H 'orgid: acme-retail' \\\n  -H 'Authorization: Bearer <jwt>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{ \"name\": \"Cold Drinks\", \"parent\": \"drinks\" }'"},{"lang":"javascript","label":"fetch","source":"const res = await fetch('https://api.appmint.io/storefront/categories', {\n  method: 'POST',\n  headers: {\n    orgid: 'acme-retail',\n    Authorization: `Bearer ${token}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ name: 'Cold Drinks', parent: 'drinks' }),\n});\n\nconst { category, categories } = await res.json();"}]}},"/storefront/products/{id}/categories":{"post":{"operationId":"StorefrontController_setProductCategories","summary":"Put a product in categories","description":"Puts a product in storefront categories by name or title. A category missing from the storefront tree is added under the root (as `POST /storefront/categories` would); the product's record-level `post.categories` then carries the tree names (slugs, e.g. `cold-drinks`), which is what the storefront filters by. Adds to the categories the product already has unless `replace` is true.\n\n#### Signature\n\n```http\nPOST /storefront/products/{id}/categories (id: string, body) -> { product, categories } — the updated product and the category names it now carries.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/categories`\n- `GET /storefront/categories`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The product: sk, name or sku.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"{ product, categories } — the updated product and the category names it now carries."},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"],"requestBody":{"description":"The categories.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["names"],"properties":{"names":{"type":"array","items":{"type":"string"},"description":"Category names or titles.","example":["Cold Drinks"]},"replace":{"type":"boolean","description":"true to set exactly these categories instead of adding to the existing ones."}}},"example":{"names":["Cold Drinks"]}}}}}},"/storefront/pos-categories":{"get":{"operationId":"StorefrontController_posCategories","summary":"Get POS quick-pick categories","description":"The top-of-screen quick category buckets used by the in-store POS (Apps / Mains / Drinks / …).\n\nThese are deliberately *not* the storefront category tree: they are sourced from the `posCategory` entry in the `sf_attribute` collection so operators can edit the POS layout in one place without touching the catalog taxonomy.\n\n#### Signature\n\n```http\nGET /storefront/pos-categories () -> The option list, or `[]` when `posCategory` has not been seeded\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- An empty array means the `posCategory` attribute has not been configured yet, not that there was an error.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/categories`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The option list, or `[]` when `posCategory` has not been seeded","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Button caption.","example":"Drinks"},"value":{"type":"string","description":"Category value the POS filters products by.","example":"drinks"},"param":{"type":"string","description":"Optional extra parameter carried with the selection."}}}},"example":[{"label":"Apps","value":"appetisers"},{"label":"Mains","value":"mains"},{"label":"Drinks","value":"drinks"}]}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront"]}},"/storefront/pos/tab":{"post":{"operationId":"StorefrontController_openPosTab","summary":"Open a POS tab","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Tab details. All fields optional.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"businessLocationId":{"type":"string","description":"Location the tab belongs to. Also scopes auto-alias numbering.","example":"loc_downtown"},"alias":{"type":"string","description":"Operator-facing label. Auto-generated as `Walk-up #N` when omitted.","example":"Table 7"},"tabLabel":{"type":"string","description":"Deprecated alias for `alias`, accepted for older clients. Prefer `alias`.","deprecated":true},"servicePointId":{"type":"string","description":"Table or counter to seat the tab at immediately.","example":"sp_t7"},"customer":{"type":"object","description":"Contact to attach. Also populates the order-level `email`, `phone` and `name`, which receipts fall back to.","properties":{"sk":{"type":"string","description":"Existing customer record."},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"override":{"type":"object","description":"Readiness override (manager/HR): lets this action go ahead despite a block. Recorded per blocking requirement.","properties":{"reasonCode":{"type":"string","enum":["renewal_booked","awaiting_document","training_scheduled","business_need","not_applicable","system_error","other"]},"reason":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}},"examples":{"walkUp":{"summary":"Walk-up tab","description":"Empty body — the server names it `Walk-up #N`.","value":{}},"table":{"summary":"Named table at a location","value":{"businessLocationId":"loc_downtown","alias":"Table 7","servicePointId":"sp_t7"}},"withCustomer":{"summary":"Tab with a contact","description":"Attaching contact details up front lets `send-receipt` work without a recipient.","value":{"businessLocationId":"loc_downtown","alias":"Smith party","customer":{"name":"Ada Lovelace","email":"ada@example.com"}}}}}}},"responses":{"201":{"description":"The created tab","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"400":{"description":"An override needs reasonCode, reason, expiresAt. — `override` is missing a field, has an unknown reason code, or an expiry in the past.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"An override needs reasonCode, reason, expiresAt.","path":"/storefront/pos/tab","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"Sign in as a location manager or HR to override. — The caller may not approve an override (no caller, the person themselves, or only their own supervisor).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Sign in as a location manager or HR to override.","path":"/storefront/pos/tab","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"423":{"description":"<name> can't use the register: <requirement titles>. — A requirement rule whose `enforcement.pos` effect is block (or override-with-reason) is unmet for this person, and no override is active.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"reason":"readiness_block","code":"READINESS_BLOCK","gate":"pos","message":"Luis Ramirez can't clock in: Food handler card.","employeeId":"E012","employeeName":"Luis Ramirez","effect":"block","blocking":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","expiresAt":"2026-09-20T00:00:00.000Z"}],"warnings":[],"reasons":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","severity":"block"}],"canOverride":true,"override":{"how":"Send the same request again with override: { reasonCode, reason, expiresAt }.","fields":["reasonCode","reason","expiresAt"],"reasonCodes":["renewal_booked","awaiting_document","training_scheduled","business_need","not_applicable","system_error","other"],"approver":"A location manager or HR. The person’s own supervisor alone cannot approve."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"description":"Opens a new tab and returns it with `status: \"new\"`. Every field is optional — an empty body is a valid walk-up tab.\n\nWhen `alias` is omitted the server auto-numbers one from the tabs currently open at that location, giving `Walk-up #1`, `Walk-up #2` and so on. Because the count is taken at open time, aliases are not reserved: two tabs opened simultaneously at one location can receive the same auto-alias. Pass an explicit `alias` where that matters.\n\nA tab is an `sf_order` and lives in the same collection as web orders with the same shape — a unique `number`, `productItems[]`, and the monetary fields — so reporting and integrations see one consistent model regardless of channel.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab (body) -> The created tab\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Auto-generated aliases are not unique under concurrency. Send an explicit `alias` when you need a guaranteed one.\n- The tab opens empty; add lines with `POST /storefront/order/{id}/items`.\n- POS gate (whole register) for the signed-in operator: 423 `readiness_block`; a manager resends with `override`, stamped on the tab as `readinessOverride`. Customers and non-staff callers are never gated.\n- Workforce Readiness: with no requirement rules this endpoint behaves exactly as before. `warn` never stops anything — it comes back as `readiness.warnings` in the response.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `423` | READINESS_BLOCK | <name> can't use the register: <requirement titles>. | A requirement rule whose `enforcement.pos` effect is block (or override-with-reason) is unmet for this person, and no override is active. | Show `message` and `reasons`. A location manager or HR can resend the same request with `override: { reasonCode, reason, expiresAt }` — it is written to the readiness ledger with the approver and expiry. The person’s own override is refused. |\n| `400` | OVERRIDE_INVALID | An override needs reasonCode, reason, expiresAt. | `override` is missing a field, has an unknown reason code, or an expiry in the past. | — |\n| `403` | OVERRIDE_FORBIDDEN | Sign in as a location manager or HR to override. | The caller may not approve an override (no caller, the person themselves, or only their own supervisor). | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pos/tabs`\n- `POST /storefront/order/{id}/items`\n- `POST /storefront/pos/tab/{id}/settle`"}},"/storefront/pos/readiness":{"get":{"operationId":"StorefrontController_posOperatorReadiness","summary":"May the signed-in operator use the POS?","description":"The Workforce Readiness `pos` gate, asked when the POS screen opens. Never throws for a block — it describes it, so the screen can explain and offer the override. Pass `permissionScope` (e.g. `alcohol`) to ask about one gated permission. The same gate is enforced server-side on POST /storefront/pos/tab and POST /storefront/order/{id}/items.\n\n#### Signature\n\n```http\nGET /storefront/pos/readiness (businessLocationId?: string, permissionScope?: string) -> `{ allowed, staff, permissionScope, effect, employeeId, employeeName, blocking[], warnings[], reasons[], overrideActive }`; when not allowed, also the standard block fields (`reason: \"readiness_block\"`, `message`, `canOverride`, `override`). A caller who isn’t staff gets `{ allowed: true, staff: false }`.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Workforce Readiness: with no requirement rules this endpoint behaves exactly as before. `warn` never stops anything — it comes back as `readiness.warnings` in the response.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab`\n- `POST /storefront/order/{id}/items`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"businessLocationId","required":false,"in":"query","schema":{"type":"string"},"description":"The register’s location.","example":"harbor-grill"},{"name":"permissionScope","required":false,"in":"query","schema":{"type":"string"},"description":"One POS permission to check, e.g. alcohol. Empty = the whole register.","example":"alcohol"}],"responses":{"200":{"description":"`{ allowed, staff, permissionScope, effect, employeeId, employeeName, blocking[], warnings[], reasons[], overrideActive }`; when not allowed, also the standard block fields (`reason: \"readiness_block\"`, `message`, `canOverride`, `override`). A caller who isn’t staff gets `{ allowed: true, staff: false }`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"allowed":false,"staff":true,"permissionScope":"alcohol","reason":"readiness_block","code":"READINESS_BLOCK","gate":"pos","message":"Luis Ramirez can't sell alcohol items: Alcohol server cert.","employeeId":"E012","employeeName":"Luis Ramirez","effect":"block","blocking":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","expiresAt":"2026-09-20T00:00:00.000Z"}],"warnings":[],"reasons":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","severity":"block"}],"canOverride":true,"override":{"how":"Send the same request again with override: { reasonCode, reason, expiresAt }.","fields":["reasonCode","reason","expiresAt"],"reasonCodes":["renewal_booked","awaiting_document","training_scheduled","business_need","not_applicable","system_error","other"],"approver":"A location manager or HR. The person’s own supervisor alone cannot approve."}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tabs":{"get":{"operationId":"StorefrontController_listPosTabs","summary":"List open POS tabs","description":"Returns the tabs an operator might still act on, newest first, with line items task-enriched.\n\n\"Open\" is defined by exclusion: any tab whose status is **not** one of `completed`, `cancelled`, `returned`, `refunded`, `failed` is returned. That deliberately includes **fully-paid tabs** — a paid tab stays on the floor until the operator closes it out — and it makes the list resilient to unexpected status values rather than hiding them.\n\n#### Signature\n\n```http\nGET /storefront/pos/tabs (businessLocationId?: string) -> Open tabs, newest first\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Capped at 200 tabs. There is no pagination — a location with more than 200 open tabs is truncated.\n- Paid-but-not-closed tabs appear here, not in the closed list. Check `amountPaid` against `amount` to tell them apart.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pos/tabs/closed`\n- `POST /storefront/pos/tab`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"businessLocationId","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one location. Omit to list every location in the org.","example":"loc_downtown"},{"name":"unpaid","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Open tabs, newest first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tabs/closed":{"get":{"operationId":"StorefrontController_listClosedPosTabs","summary":"List closed POS tabs","description":"The exact complement of the open list: tabs whose status **is** one of `completed`, `cancelled`, `returned`, `refunded`, `failed`, newest first, with line items task-enriched. Intended for audit and reporting views (\"show me yesterday's tabs\").\n\n#### Signature\n\n```http\nGET /storefront/pos/tabs/closed (businessLocationId?: string) -> Closed tabs, newest first\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Capped at 200 tabs with no pagination or date filter, so this is not a full historical export. Query `sf_order` through the repository API for reporting over long ranges.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pos/tabs`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"businessLocationId","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one location.","example":"loc_downtown"}],"responses":{"200":{"description":"Closed tabs, newest first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/order/{id}":{"get":{"operationId":"StorefrontController_getOrderById","summary":"Get an order with tasks enriched","description":"Returns one order or tab by `sk`, with `productItems[].task` populated for every line that has been fired. This is the read to use when rendering a tab, because it resolves workflow state in the same round trip.\n\n#### Signature\n\n```http\nGET /storefront/order/{id} (id: string) -> The order with fired lines task-enriched\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/order/{id}/payments`\n- `POST /storefront/order/{id}/fire`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Order `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The order with fired lines task-enriched","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/order/{id}/product-pages":{"get":{"operationId":"StorefrontController_getOrderProductPages","summary":"The storefront page of each product on an order","description":"Each product line matched to its product by SKU, with its page on the storefront ({site}/{storePage}/{slug}) or why it has none (not-found, hidden, no-page).","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Order sk","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront"]}},"/storefront/order/{id}/payments":{"get":{"operationId":"StorefrontController_getOrderPayments","summary":"List payments and balance for an order","description":"The authoritative payment view for an order. Matches `sf_transaction.invoiceNumber` case-insensitively against the order `sk`, display number and name, then returns every linked transaction together with computed `totalPaid`, `balance` and `paymentStatus`.\n\nUse this rather than reconstructing payment state on the client — the matching rules and the refund arithmetic live on the server, and client-side heuristics have historically disagreed with the ledger.\n\n#### Signature\n\n```http\nGET /storefront/order/{id}/payments (id: string) -> Linked transactions plus computed totals\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/settle`\n- `POST /storefront/pos/tab/{id}/refund`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Order `sk`, display number, or name.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"Linked transactions plus computed totals","content":{"application/json":{"schema":{"type":"object","properties":{"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Matching `sf_transaction` records, refunds included as negative amounts."},"totalPaid":{"type":"number","description":"Net of refunds.","example":25.92},"balance":{"type":"number","description":"Order total minus `totalPaid`. Zero or negative means settled.","example":0},"paymentStatus":{"type":"string","description":"Derived status, e.g. `paid`, `paid-partial`, `unpaid`.","example":"paid"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/order/{id}/books":{"get":{"operationId":"StorefrontController_getOrderBooks","summary":"Is the money taken on this order in Books","description":"Each payment taken on the order checked against its own journal entry: { mode, payments[{ key, amount, inBooks }], unbooked }. RT4-S2-01.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Order sk, display number, or name","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront"]},"put":{"operationId":"StorefrontController_postOrderBooks","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront"]}},"/storefront/pos/tab/{id}/payment-preflight":{"post":{"operationId":"StorefrontController_preflightPosPayment","summary":"Post to Books: book the payments taken on this order that Books does not have yet","description":"Catch-up for payments taken before order payments were booked (RT4-S2-01). Keyed per payment like the live path, so nothing posts twice; the entries are tagged \"posted to Books by catch-up\" and are ordinary journal entries (reversible in Books › Journal). Staff only.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Order sk, display number, or name","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/stripe/pos/intent":{"post":{"operationId":"StorefrontController_stripePosPaymentIntent","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/stripe/terminal/payment-status":{"post":{"operationId":"StorefrontController_stripeTerminalPaymentStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/pos/tab/{id}/settle":{"post":{"operationId":"StorefrontController_settlePosTab","summary":"Settle a POS tab","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Open POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"The tender to record.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"Tender amount in the order currency. Must be greater than zero.","example":25.92},"method":{"type":"string","description":"How it was paid — `card`, `cash`, `giftcard`, …. Recorded for reporting.","example":"card"},"gateway":{"type":"string","default":"manual","description":"Processor. `stripe` verifies with the gateway before recording; anything else records offline.","example":"stripe"},"ref":{"type":"string","description":"Gateway or operator reference, stored on the payment line.","example":"ch_3PabcXYZ"},"tip":{"type":"number","description":"Tip included in `amount`.","example":3},"currency":{"type":"string","description":"Defaults to the order currency, then `USD`.","example":"USD"},"tendered":{"type":"number","description":"Cash only: the note handed over for this tender; change = tendered − (amount + tip).","example":50}}},"examples":{"cash":{"summary":"Cash, paid in full","value":{"amount":25.92,"method":"cash"}},"cashWithChange":{"summary":"Cash share with change","value":{"amount":18.5,"tip":2,"method":"cash","tendered":50}},"cardWithTip":{"summary":"Card via Stripe with a tip","description":"`tip` is part of `amount`, not additional to it.","value":{"amount":28.92,"tip":3,"method":"card","gateway":"stripe","ref":"ch_3PabcXYZ"}},"partial":{"summary":"Partial payment","description":"Leaves the tab `paid-partial`; call again for the balance.","value":{"amount":10,"method":"cash"}}}}}},"responses":{"201":{"description":"The updated tab and the recorded transaction","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"transaction":{"type":"object","additionalProperties":true,"description":"The `sf_transaction` written for this tender."},"accounting":{"type":"object","nullable":true,"additionalProperties":true,"description":"Ledger posting result once fully paid: status complete | needs_attention, issues[]."},"stock":{"type":"object","nullable":true,"additionalProperties":true,"description":"Stock deduction result once fully paid: status complete | needs_attention, issues[]."}}}}}},"400":{"description":"Order is already paid in full — `amountPaid` already covers the order total.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Order is already paid in full","path":"/storefront/pos/tab/{id}/settle","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/settle","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This sale has a recorded cash refund. Use a new tab for another sale; retry refund records separately. — The tab already has a POS refund recorded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This sale has a recorded cash refund. Use a new tab for another sale; retry refund records separately.","path":"/storefront/pos/tab/{id}/settle","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"description":"Records a tender against the tab, increments `amountPaid`, appends to `payments[]` and recomputes the status to `paid` or `paid-partial`.\n\nAn `sf_transaction` is **always** written, including for cash, so accounting and reporting see every tender. When `gateway` is `stripe` the transaction is verified with Stripe before it is recorded; every other gateway is recorded as paid offline on trust.\n\nPartial settlement is supported — call it repeatedly until the balance reaches zero. Each call is a new tender, so this endpoint is **not idempotent**: a retried request records a second payment.\n\n**Overpayment**: only a cash tender may exceed what is due — the payment is recorded as the amount due and `tendered`/change are kept on the payment line. Any other tender for more than is due is refused. For a cash share of a split, send `tendered` (the note handed over) and the change is worked out against `amount + tip`.\n\n**Cards** are never recorded by hand: a card is taken on the location's connected card terminal (`POST /storefront/pos/tab/{id}/terminal-charge`), or online with `gateway: \"stripe\"`. `method: \"card\"` with any other gateway, and `gateway: \"terminal\"` in a request, are refused (400 `CARD_ON_TERMINAL`). Offline tenders recorded here: cash, check (number in `ref`), other/draft, house account.\n\n**Gift cards** are paid by redeeming them first (`POST /storefront/giftcards/redeem`) and settling with `gateway: \"giftcard\"` and the GCT reference; a gift-card tender recorded any other way is refused.\n\nWhen the tab becomes fully paid the sale is posted to the ledger and stock is deducted. Those results come back as `accounting` and `stock`; if either could not complete it is saved as `needs_attention` for `retry-accounting` / `retry-stock` — never a reason to charge again.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/settle (id: string, body) -> The updated tab and the recorded transaction\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Not idempotent — a retry records an additional tender. Confirm with the payments endpoint before retrying a request whose response you lost.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | ALREADY_PAID | Order is already paid in full | `amountPaid` already covers the order total. | Read `GET /storefront/order/{id}/payments` to confirm the balance before settling. |\n| `409` | REFUNDED_SALE | This sale has a recorded cash refund. Use a new tab for another sale; retry refund records separately. | The tab already has a POS refund recorded. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/order/{id}/payments`\n- `POST /storefront/pos/tab/{id}/refund`\n- `POST /storefront/pos/tab/{id}/terminal-charge`"}},"/storefront/pos/tab/{id}/terminal-charge":{"post":{"operationId":"StorefrontController_chargePosTabOnTerminal","summary":"Take a card on the connected card terminal","description":"Card payments at the till go through the card terminal connected at the tab's location (Operations › Devices, a `card-terminal` device on a Device Hub). This sends `amount + tip` to the terminal as a hub `charge` command and waits — up to 2 minutes — while the customer taps, inserts or swipes.\n\n**Approved**: the payment is recorded exactly like a settle (method `card`, gateway `terminal`, `ref` = the terminal's transaction id, the card brand / last 4 / entry mode / approval code on the payment line under `card`) and the same `{ order, transaction, accounting, stock }` comes back, plus `terminal`.\n\n**Declined**: 402, nothing recorded. The amount is checked against what is due before the card is touched, so a card is never charged for a payment the tab would refuse.\n\nSend the tender row's id as `chargeKey`: a resent request (dropped reply, double tap) returns the payment it already took instead of charging the card again. Runs under the tab's settle lock.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/terminal-charge (id: string, body) -> The updated tab, the recorded transaction and what the terminal reported\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `409` | NO_CARD_TERMINAL | No card terminal is connected at this location. Connect one in Operations › Devices to take card payments. | No active card terminal at the tab's location, its hub is offline (`state: hub-offline`), or the hub reports the terminal not answering (`state: terminal-offline`). | Connect or fix the terminal in Operations › Devices. There is no manual card path. |\n| `402` | CARD_DECLINED | Card declined: <reason>. Nothing was charged. Try another card or tender. | The terminal declined the card. | — |\n| `504` | TERMINAL_NO_ANSWER | The card terminal \"<name>\" did not answer in time. Nothing was recorded… | No answer from the terminal within 2 minutes. | Check the terminal; if it shows the payment approved, void it there before charging again. |\n| `400` | OVERPAYMENT | Card payment of <amount> is more than the <due> due. Charge the balance due. | `amount` is above what is due. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pos/card-terminal`\n- `POST /storefront/pos/tab/{id}/settle`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Open POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"The card tender.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"This tender's share of the bill, tip excluded. No more than what is due.","example":32.48},"tip":{"type":"number","description":"Tip on this tender. The terminal is asked for amount + tip.","example":0},"currency":{"type":"string","description":"Defaults to the order currency, then `USD`.","example":"USD"},"chargeKey":{"type":"string","description":"Stable id of this tender (retry-safe).","example":"7d4c1f0e-…"}}},"examples":{"secondHalf":{"summary":"Second half of a split, on the card","value":{"amount":32.48,"tip":0,"chargeKey":"7d4c1f0e-2b8a-4a51-9a0e-5b1f3c2d9e11"}}}}}},"responses":{"201":{"description":"The updated tab, the recorded transaction and what the terminal reported","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"transaction":{"type":"object","additionalProperties":true},"terminal":{"type":"object","additionalProperties":true,"description":"{ name, approved, ref, amount, approvalCode?, brand?, last4?, entryMode? }"}}}}}},"400":{"description":"Card payment of <amount> is more than the <due> due. Charge the balance due. — `amount` is above what is due.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Card payment of <amount> is more than the <due> due. Charge the balance due.","path":"/storefront/pos/tab/{id}/terminal-charge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"Card declined: <reason>. Nothing was charged. Try another card or tender. — The terminal declined the card.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"Card declined: <reason>. Nothing was charged. Try another card or tender.","path":"/storefront/pos/tab/{id}/terminal-charge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/terminal-charge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"No card terminal is connected at this location. Connect one in Operations › Devices to take card payments. — No active card terminal at the tab's location, its hub is offline (`state: hub-offline`), or the hub reports the terminal not answering (`state: terminal-offline`).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"No card terminal is connected at this location. Connect one in Operations › Devices to take card payments.","path":"/storefront/pos/tab/{id}/terminal-charge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"504":{"description":"The card terminal \"<name>\" did not answer in time. Nothing was recorded… — No answer from the terminal within 2 minutes.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":504,"error":"The card terminal \"<name>\" did not answer in time. Nothing was recorded…","path":"/storefront/pos/tab/{id}/terminal-charge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · POS"]}},"/storefront/pos/card-terminal":{"get":{"operationId":"StorefrontController_posCardTerminal","summary":"The card terminal at a location","description":"Whether a card can be taken at a location right now. `state`: `ready` (a terminal on an online hub), `none` (no terminal connected), `hub-offline`, `terminal-offline`. `message` is the sentence the till shows when it is not ready.\n\n#### Signature\n\n```http\nGET /storefront/pos/card-terminal (location?: string) -> The location's terminal state\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/terminal-charge`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"location","required":false,"in":"query","schema":{"type":"string"},"description":"Business location id (the tab's `businessLocationId`).","example":"main-dining"}],"responses":{"200":{"description":"The location's terminal state","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string"},"message":{"type":"string"},"terminal":{"type":"object","additionalProperties":true}}},"example":{"state":"ready","terminal":{"name":"till-hub-counter-terminal","displayName":"Counter card terminal","hubName":"till-hub","endpointName":"counter-terminal"}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/breakdown":{"get":{"operationId":"StorefrontController_posTabBreakdown","summary":"Get the money breakdown of a POS tab","description":"Read-only, server-priced figures for the settle screen: the recorded subtotal, discount, tax and total; what is paid and the tips collected; `balanceDue`; tip options (15/18/20/25% of subtotal) and the chosen tip; per-person split amounts; and, for the tenders the cashier is laying out, their total, what is still `outstanding`, the \"pay rest\" fill for each, the charge each will make (the tip rides the first) and cash `change`. The client renders these numbers and never derives money itself.\n\n`selected` (line ids) splits the lines into `selectedTotal` / `unselectedTotal` for pay-by-item.\n\n#### Signature\n\n```http\nGET /storefront/pos/tab/{id}/breakdown (id: string, tip?: number, tipPercent?: number, split?: integer, pending?: string, tendered?: string, selected?: string) -> { order, breakdown }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Anonymous: StorefrontController is `@PublicRoute()` at class level and this handler does not override it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/settle`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"tip","required":false,"in":"query","schema":{"type":"number"},"description":"Tip amount. Ignored when `tipPercent` is given.","example":5},{"name":"tipPercent","required":false,"in":"query","schema":{"type":"number"},"description":"Tip as a percent of the subtotal.","example":18},{"name":"split","required":false,"in":"query","schema":{"type":"integer"},"description":"Split the balance evenly this many ways (2 or more).","example":3},{"name":"pending","required":false,"in":"query","schema":{"type":"string"},"description":"Comma list of tender amounts being laid out.","example":"20,15.5"},{"name":"tendered","required":false,"in":"query","schema":{"type":"string"},"description":"Comma list, parallel to `pending`: cash handed over for each, for change.","example":"20,20"},{"name":"selected","required":false,"in":"query","schema":{"type":"string"},"description":"Comma list of line ids for pay-by-item."}],"responses":{"200":{"description":"{ order, breakdown }","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"breakdown":{"type":"object","properties":{"subtotal":{"type":"number"},"discount":{"type":"number"},"tax":{"type":"number"},"taxRate":{"type":"number"},"taxName":{"type":"string"},"total":{"type":"number"},"paid":{"type":"number"},"tipsCollected":{"type":"number"},"collected":{"type":"number"},"balanceDue":{"type":"number"},"paidInFull":{"type":"boolean"},"tipOptions":{"type":"array","items":{"type":"object","properties":{"percent":{"type":"number"},"amount":{"type":"number"}}}},"tip":{"type":"number"},"dueNow":{"type":"number","description":"balanceDue + tip."},"splitAmounts":{"type":"array","nullable":true,"items":{"type":"number"},"description":"Even split of the balance; the last share absorbs rounding. Null unless `split` ≥ 2."},"splitOptions":{"type":"array","items":{"type":"object","properties":{"parts":{"type":"integer"},"each":{"type":"number"}}}},"pendingTotal":{"type":"number"},"outstanding":{"type":"number"},"tenders":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"charge":{"type":"number"},"tipIncluded":{"type":"number"},"payRest":{"type":"number"},"change":{"type":"number"}}}},"selectedTotal":{"type":"number"},"unselectedTotal":{"type":"number"},"payments":{"type":"array","items":{"type":"object","properties":{"transactionId":{"type":"string"},"amount":{"type":"number"},"tip":{"type":"number"},"refundedAmount":{"type":"number"},"refunded":{"type":"boolean"},"refundable":{"type":"number"},"tendered":{"type":"number"},"change":{"type":"number"},"isRefund":{"type":"boolean"}}}}}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/breakdown","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/redeem-points":{"post":{"operationId":"StorefrontController_redeemPointsForTab","summary":"Pay a tab whose lines are all bought with reward points: takes the tab customer's points once and marks it paid","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Order sk","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/pos/tab/{id}/close":{"post":{"operationId":"StorefrontController_closePosTab","summary":"Close a paid POS tab","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The completed order and the freed service point","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"servicePoint":{"type":"object","nullable":true,"additionalProperties":true}}}}}},"400":{"description":"Tab is already <status> — The tab is completed, cancelled, refunded or returned.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Tab is already <status>","path":"/storefront/pos/tab/{id}/close","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/close","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"<n> sent items are still open at the station (<names>). Close the tab once the ticket is done. — A sent item's station task is not done.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"<n> sent items are still open at the station (<names>). Close the tab once the ticket is done.","path":"/storefront/pos/tab/{id}/close","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"description":"Completes a fully paid tab (the order is completed in person) and frees its service point: the table goes to `dirty` — or `available` with `markDirty: false` — and its current tab, party size, server and seated time are cleared.\n\nRefused while anything is still owed, or while a sent item is still open at a station.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/close (id: string, body) -> The completed order and the freed service point\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Anonymous: StorefrontController is `@PublicRoute()` at class level and this handler does not override it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | TAB_CLOSED | Tab is already <status> | The tab is completed, cancelled, refunded or returned. | — |\n| `409` | ITEMS_OPEN | <n> sent items are still open at the station (<names>). Close the tab once the ticket is done. | A sent item's station task is not done. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/settle`\n- `POST /storefront/pos/tab/{id}/release-service-point`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"markDirty":{"type":"boolean","default":true,"description":"false leaves the table available instead of dirty."}}}}}}}},"/storefront/pos/tab/{id}/void":{"post":{"operationId":"StorefrontController_voidPosTab","summary":"Void a POS tab — cancels it; a partly paid tab also hands back what was collected and reverses its sale in the books","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Order sk","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/pos/tab/{id}/lines/{lineId}/void":{"post":{"operationId":"StorefrontController_voidPosLine","summary":"Void one already-sent line on an open POS tab (manager or owner). Body: { reason? }. B-HUM-05.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Order sk","schema":{"type":"string"}},{"name":"lineId","required":true,"in":"path","description":"Line id on the tab","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/pos/tab/{id}/lines/{lineId}/sell-anyway":{"post":{"operationId":"StorefrontController_sellPosLineAnyway","summary":"Sell a tab line anyway when the tab's customer does not meet its product's purchase requirements. Any staff member. Body: { reason? }.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Order sk","schema":{"type":"string"}},{"name":"lineId","required":true,"in":"path","description":"Line id on the tab","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/pos/tab/{id}/retry-accounting":{"post":{"operationId":"StorefrontController_retryPosAccounting","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"POS tab `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The order and its accounting status","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"accounting":{"type":"object","additionalProperties":true,"description":"status complete | needs_attention, issues[], checkedAt."}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/retry-accounting","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This historical tab has no saved accounting snapshot; no payment or journal was changed — A tab settled before accounting snapshots existed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This historical tab has no saved accounting snapshot; no payment or journal was changed","path":"/storefront/pos/tab/{id}/retry-accounting","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"summary":"Retry the journal for a settled POS tab","description":"When settling a tab could not post its sale and payment journals (the tab's `posAccounting.status` is `needs_attention`), this replays the saved accounting snapshot. Idempotent: journals already posted are not posted again. No payment is changed.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/retry-accounting (id: string) -> The order and its accounting status\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A failure while posting is recorded in `accounting.issues` with `status: needs_attention`, not raised.\n- Anonymous: StorefrontController is `@PublicRoute()` at class level and this handler does not override it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `409` | NO_SNAPSHOT | This historical tab has no saved accounting snapshot; no payment or journal was changed | A tab settled before accounting snapshots existed. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/retry-stock`"}},"/storefront/pos/tab/{id}/retry-stock":{"post":{"operationId":"StorefrontController_retryPosStock","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"POS tab `sk`.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The order and its stock status","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"stock":{"type":"object","additionalProperties":true,"description":"status complete | needs_attention, issues[]."}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/retry-stock","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This order has no saved POS stock intent; historical sales are not deducted automatically — The tab has no saved stock intent.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This order has no saved POS stock intent; historical sales are not deducted automatically","path":"/storefront/pos/tab/{id}/retry-stock","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"summary":"Retry the stock deduction for a settled POS tab","description":"When settling a fully paid tab could not deduct stock (the saved stock intent is `needs_attention`), this replays it and posts the cost of goods. Already complete intents are returned unchanged. Refused if the sold items or location changed after payment, or the sale was refunded.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/retry-stock (id: string) -> The order and its stock status\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Problems resolving items, the location or posting COGS are recorded in `stock.issues` rather than raised.\n- Anonymous: StorefrontController is `@PublicRoute()` at class level and this handler does not override it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `409` | NO_STOCK_INTENT | This order has no saved POS stock intent; historical sales are not deducted automatically | The tab has no saved stock intent. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/retry-accounting`"}},"/storefront/pos/tab/{id}/print-check":{"post":{"operationId":"StorefrontController_printPosCheck","summary":"Print a pre-payment check","description":"Builds an ESC/POS check from the tab and dispatches it to the location's configured printer via the hub-agent — the restaurant flow where a customer asks for the check before paying.\n\nThe printer is read from `location.data.pos.checkPrinter`, falling back to `receiptPrinter`. Use `GET /storefront/pos/tab/{id}/check-payload` instead when the client drives its own printer.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/print-check (id: string) -> Dispatch result from the hub-agent\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Requires a configured printer and a reachable hub-agent at the location; neither is validated before dispatch.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pos/tab/{id}/check-payload`\n- `POST /storefront/pos/tab/{id}/print-receipt`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Open POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"Dispatch result from the hub-agent","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/print-check","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/print-receipt":{"post":{"operationId":"StorefrontController_printPosReceipt","summary":"Print or reprint a receipt","description":"Prints the receipt for a tab through the location's printer. Works in any payment state — the tender section is taken from the most recent entry in `payments[]` — so it serves both the moment of sale and a later reprint of an old receipt.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/print-receipt (id: string, copy?: string) -> Dispatch result from the hub-agent\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pos/tab/{id}/receipt-payload`\n- `POST /storefront/pos/tab/{id}/send-receipt`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"copy","required":false,"in":"query","schema":{"type":"string","enum":["customer","merchant"]},"description":"Selects the matching copy template. Omit to let the resolver use whichever copy the operator configured.","example":"customer"}],"responses":{"201":{"description":"Dispatch result from the hub-agent","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/print-receipt","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/receipt-payload":{"get":{"operationId":"StorefrontController_buildPosReceiptPayload","summary":"Get receipt print primitives","description":"Runs the same template resolution and render pipeline as `print-receipt` — org setting, then factory default; Handlebars-style interpolation; auto-skip-empty; loop, two-column and divider primitives — but returns the resolved lines instead of dispatching them.\n\nThis is the endpoint for clients that own their printer: a mobile app over Bluetooth, a kiosk over USB.\n\n#### Signature\n\n```http\nGET /storefront/pos/tab/{id}/receipt-payload (id: string, copy?: string) -> The resolved print primitives\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/print-receipt`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"copy","required":false,"in":"query","schema":{"type":"string","enum":["customer","merchant"]},"description":"Selects the copy variant template.","example":"customer"}],"responses":{"200":{"description":"The resolved print primitives","content":{"application/json":{"schema":{"type":"array","description":"Resolved print lines, in order.","items":{"type":"object","properties":{"kind":{"type":"string","description":"Primitive type — `text`, `twocol`, `divider`, `loop`, `qr`, `barcode`.","example":"twocol"},"text":{"type":"string","example":"Cola 330ml"},"bold":{"type":"boolean","example":false},"size":{"type":"string","description":"Relative size hint.","example":"normal"},"lines":{"type":"array","items":{"type":"string"},"description":"Column values for `twocol`."},"url":{"type":"string","description":"Payload for `qr` / `barcode`."}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/receipt-payload","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/check-payload":{"get":{"operationId":"StorefrontController_buildPosCheckPayload","summary":"Get check print primitives","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The resolved print primitives","content":{"application/json":{"schema":{"type":"array","description":"Resolved print lines, in order.","items":{"type":"object","properties":{"kind":{"type":"string","description":"Primitive type — `text`, `twocol`, `divider`, `loop`, `qr`, `barcode`.","example":"twocol"},"text":{"type":"string","example":"Cola 330ml"},"bold":{"type":"boolean","example":false},"size":{"type":"string","description":"Relative size hint.","example":"normal"},"lines":{"type":"array","items":{"type":"string"},"description":"Column values for `twocol`."},"url":{"type":"string","description":"Payload for `qr` / `barcode`."}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/check-payload","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"description":"The pre-payment check equivalent of `receipt-payload` — renders the check template for the tab and returns the primitive lines for a client that drives its own printer.\n\n#### Signature\n\n```http\nGET /storefront/pos/tab/{id}/check-payload (id: string) -> The resolved print primitives\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/print-check`"}},"/storefront/pos/tab/{id}/send-receipt":{"post":{"operationId":"StorefrontController_sendPosReceipt","summary":"Email or SMS a receipt","description":"Sends the receipt through the org's notification pipeline, using the same template chain as order-confirmation mail (org → shared-org → factory default).\n\nRecipients resolve in this order: an explicit `to`, `email` or `phone`, then the contact saved on the tab. The channel is inferred — email when an address is available, SMS otherwise — unless `mode` forces one.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/send-receipt (id: string, body) -> Dispatch result per channel\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | NO_RECIPIENT | No recipient — pass `to`, `email`, or `phone`, or save a contact on the tab first. | Neither the body nor the tab supplies a usable address, so no channel could be selected. | Send `to`, `email` or `phone`, or attach a customer to the tab when opening it. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/print-receipt`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"Recipient and channel. All fields optional when the tab has a saved contact.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Recipient email or phone, or several. Falls back to the tab contact.","example":"ada@example.com"},"email":{"type":"string","description":"Explicit email override.","example":"ada@example.com"},"phone":{"type":"string","description":"Explicit phone override.","example":"+15551234567"},"mode":{"type":"string","enum":["email","sms"],"description":"Force a channel instead of inferring it.","example":"email"}}},"examples":{"savedContact":{"summary":"Use the tab's saved contact","value":{}},"explicitEmail":{"summary":"Email a specific address","value":{"to":"ada@example.com","mode":"email"}},"sms":{"summary":"Force SMS","value":{"phone":"+15551234567","mode":"sms"}}}}}},"responses":{"201":{"description":"Dispatch result per channel","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"No recipient — pass `to`, `email`, or `phone`, or save a contact on the tab first. — Neither the body nor the tab supplies a usable address, so no channel could be selected.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"No recipient — pass `to`, `email`, or `phone`, or save a contact on the tab first.","path":"/storefront/pos/tab/{id}/send-receipt","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/send-receipt","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/split":{"post":{"operationId":"StorefrontController_splitPosTab","summary":"Split a POS tab","description":"Moves lines off a tab onto one or more new tabs. Two mutually exclusive modes — pass exactly one:\n\n- **By item** — `itemIds` moves those specific lines to a single new tab. Returns `{ source, target }`.\n- **By count** — `parts` (≥ 2) distributes the lines across N tabs by descending value using a greedy bin-pack, with the source keeping the largest bin. Returns `{ source, targets[] }`.\n\nAlready-fired lines keep their `taskId`, so prep line tickets are never disturbed by a split — only the parent order id moves. Partial payments stay on the source tab.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/split (id: string, body) -> The source tab plus the tab(s) created — `target` for a by-item split, `targets[]` for by-count\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Source order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | NOT_SPLITTABLE | Cannot split <status> order | The source tab is in a status that cannot be split. | Only an active tab can be split. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/settle`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Source tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"Split instruction. Send `itemIds` or `parts`, not both.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string"},"description":"Line ids to move to a new tab (by-item split).","example":["li_7f3a"]},"parts":{"type":"number","minimum":2,"description":"Number of tabs to distribute across (by-count split).","example":3},"alias":{"type":"string","description":"Alias for the new tab(s).","example":"Table 7b"}}},"examples":{"byItem":{"summary":"Move two lines to a new tab","value":{"itemIds":["li_7f3a","li_8b2c"],"alias":"Table 7b"}},"byCount":{"summary":"Split three ways","description":"Source keeps the largest bin.","value":{"parts":3}}}}}},"responses":{"201":{"description":"The source tab plus the tab(s) created — `target` for a by-item split, `targets[]` for by-count","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"target":{"type":"object","description":"By-item split only.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"targets":{"type":"array","items":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"description":"By-count split only."}}}}}},"400":{"description":"Cannot split <status> order — The source tab is in a status that cannot be split.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot split <status> order","path":"/storefront/pos/tab/{id}/split","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Source order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Source order not found","path":"/storefront/pos/tab/{id}/split","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/discount-code":{"post":{"operationId":"StorefrontController_applyPosDiscountCode","summary":"Apply a discount code to a POS tab","description":"Checks the code with the same engine online checkout uses (status, start/end dates, total and per-customer usage limits, customer groups, first order, minimum spend, eligible products and categories) and re-prices the tab. Automatic promotions (active discounts with no code) apply to every tab on their own. **Stacking:** promotions are taken highest priority first and a non-stackable one ends the list; a code combines with promotions only when the code and every promotion are stackable, otherwise the customer gets the better of the two. A staff discount always applies last, on what is left. Tax is charged on the discounted amount. One code per tab. The code counts as used once, when the tab is paid in full; a void never counts and a refund does not give the use back.\n\n`data.discounts` on the returned tab lists each promotion, the code and the staff discount, with `amount`, `applied` and `message`.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/discount-code (id: string, body) -> The re-priced tab.\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | DISCOUNT_CODE_REFUSED | WELCOME5: Minimum cart value of $20 required | The engine refuses the code (unknown, inactive, expired, used up, used by this customer, below the minimum, no eligible items, or beaten by promotions it cannot be combined with). | Show the message to the cashier; nothing was changed. |\n| `409` | ONE_CODE_PER_TAB | This tab already has code X. Remove it first: one code per tab. | Another code is on the tab. | Remove it with POST /storefront/pos/tab/{id}/discount-code/remove. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/discount-code/remove`\n- `POST /storefront/pos/tab/{id}/manual-discount`\n- `POST /storefront/pos/tab/{id}/customer`\n- `GET /storefront/pos/tab/{id}/breakdown`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","example":"WELCOME5"}}}}}},"responses":{"201":{"description":"The re-priced tab.","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"400":{"description":"WELCOME5: Minimum cart value of $20 required — The engine refuses the code (unknown, inactive, expired, used up, used by this customer, below the minimum, no eligible items, or beaten by promotions it cannot be combined with).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"WELCOME5: Minimum cart value of $20 required","path":"/storefront/pos/tab/{id}/discount-code","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/discount-code","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This tab already has code X. Remove it first: one code per tab. — Another code is on the tab.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This tab already has code X. Remove it first: one code per tab.","path":"/storefront/pos/tab/{id}/discount-code","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/discount-code/remove":{"post":{"operationId":"StorefrontController_removePosDiscountCode","summary":"Remove the discount code from a POS tab","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The re-priced tab.","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/discount-code/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"description":"Takes the code off an unpaid tab and re-prices it (promotions may apply again).\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/discount-code/remove (id: string) -> The re-priced tab.\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`."}},"/storefront/pos/tab/{id}/manual-discount":{"post":{"operationId":"StorefrontController_setPosManualDiscount","summary":"Set or remove the staff discount on a POS tab","description":"A percentage or fixed amount with a reason, applied after the code and promotions on what is left; who set it is recorded. `{ remove: true }` takes it off.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/manual-discount (id: string, body) -> The re-priced tab.\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The re-priced tab.","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/manual-discount","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["percent","fixed"]},"value":{"type":"number","example":10},"reason":{"type":"string","example":"Service complaint"},"remove":{"type":"boolean"}}}}}}}},"/storefront/pos/tab/{id}/customer":{"post":{"operationId":"StorefrontController_setPosTabCustomer","summary":"Set the customer on a POS tab","description":"Attaches a customer record (`customerId`) or clears it (`null`) and re-prices the tab for them: group prices, promotions for their groups, and the per-customer limit of a code.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/customer (id: string, body) -> The re-priced tab.\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The re-priced tab.","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/customer","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","nullable":true}}}}}}}},"/storefront/pos/tab/{id}/refund":{"post":{"operationId":"StorefrontController_refundPosTabPayment","summary":"Refund a payment on a POS tab","description":"Refunds one confirmed payment line, in full or in part, and records it on the tab.\n\n- **Cash** (method `cash`, gateway manual/offline): records the cash already handed back — send `cashReturned: true` once the guest has it.\n- **Card / gift card**: refunds through the payments refund first (Stripe back to the card, a gift card back onto the card that paid), then records it. If the provider refuses, nothing is recorded.\n\nThe payment line is kept and marked `refundedAmount`/`refunded`, a negative refund line is added, `amountPaid` goes down, and the tab becomes `refunded` once the whole sale is refunded. Net sales and tax are reversed in proportion (gift cards sold come back out of the gift card liability) and an `sf_refund` is written. If the journal cannot post, the refund is still recorded with `status: needs_attention` and the same call with the same `operationKey` replays it.\n\n**Idempotent on `operationKey`**: a retry with the same key returns the first refund and never refunds twice; the key must match the same payment and amount.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/refund (id: string, body) -> The tab and the refund record\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Anonymous in the code as it stands: StorefrontController is `@PublicRoute()` at class level and this handler does not override it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | OPERATION_KEY_REQUIRED | operationKey is required — a stable id for this refund (8–100 letters, digits, _ or -), reused if the call is retried | Missing or malformed `operationKey`. | — |\n| `409` | KEY_MISMATCH | This refund key belongs to a different payment or amount | The key was used for another payment or amount. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/settle`\n- `GET /storefront/order/{id}/payments`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactionId","amount","operationKey"],"properties":{"transactionId":{"type":"string","description":"The original payment line's `transactionId`."},"amount":{"type":"number","description":"Up to what is left refundable on that line, at most two decimals.","example":12.5},"operationKey":{"type":"string","description":"Stable id for this refund, 8–100 letters, digits, `_` or `-`. Reuse it on retry.","example":"rf_7Kq2M9xa"},"cashReturned":{"type":"boolean","description":"Cash refunds: must be true."},"reason":{"type":"string","example":"Wrong order"}}},"examples":{"card":{"summary":"Partial card refund","value":{"transactionId":"TXN-8KQ2","amount":12.5,"operationKey":"rf_7Kq2M9xa","reason":"Cold food"}},"cash":{"summary":"Cash refund","value":{"transactionId":"TXN-8KQ3","amount":20,"operationKey":"rf_7Kq2M9xb","cashReturned":true}}}}}},"responses":{"201":{"description":"The tab and the refund record","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}},"refund":{"type":"object","additionalProperties":true,"description":"id, operationKey, paymentId, amount, netSales, salesTax, method, gateway, ref, reason, status complete | needs_attention, issues[]."}}}}}},"400":{"description":"operationKey is required — a stable id for this refund (8–100 letters, digits, _ or -), reused if the call is retried — Missing or malformed `operationKey`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"operationKey is required — a stable id for this refund (8–100 letters, digits, _ or -), reused if the call is retried","path":"/storefront/pos/tab/{id}/refund","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/refund","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This refund key belongs to a different payment or amount — The key was used for another payment or amount.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This refund key belongs to a different payment or amount","path":"/storefront/pos/tab/{id}/refund","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/assign-service-point":{"post":{"operationId":"StorefrontController_assignServicePoint","summary":"Assign a service point to a tab","description":"Seats a tab at a table or counter, setting `servicePointId` and optionally renaming the tab. The service point must belong to the same location as the tab — a mismatch is rejected rather than silently seating a tab across locations.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/assign-service-point (id: string, body) -> The updated tab\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | SERVICE_POINT_REQUIRED | servicePointId is required | `servicePointId` is missing. | Send the id of the service point to seat the tab at. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/release-service-point`\n- `POST /storefront/service-point/{id}/status`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"The service point to seat the tab at.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["servicePointId"],"properties":{"servicePointId":{"type":"string","description":"Target `service_point`.","example":"sp_t7"},"alias":{"type":"string","description":"Optionally rename the tab as part of seating it.","example":"Table 7"}}},"example":{"servicePointId":"sp_t7","alias":"Table 7"}}}},"responses":{"201":{"description":"The updated tab","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"400":{"description":"servicePointId is required — `servicePointId` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"servicePointId is required","path":"/storefront/pos/tab/{id}/assign-service-point","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/assign-service-point","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/pos/tab/{id}/release-service-point":{"post":{"operationId":"StorefrontController_releaseServicePoint","summary":"Release a tab's service point","description":"Clears `servicePointId` from the tab and frees the table or counter for the next party. The tab itself stays open — releasing a service point is not the same as closing out.\n\n#### Signature\n\n```http\nPOST /storefront/pos/tab/{id}/release-service-point (id: string, body) -> The updated tab, with no service point held\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Releasing a tab that holds no service point is a no-op, not an error.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/assign-service-point`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"POS tab `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"Optional release details.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Recorded with the release.","example":"Party moved to the patio"}}},"example":{}}}},"responses":{"201":{"description":"The updated tab, with no service point held","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/pos/tab/{id}/release-service-point","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/service-point/{id}/status":{"post":{"operationId":"StorefrontController_setServicePointStatus","summary":"Set a service point status","description":"Updates the state of a table or counter directly — for example marking it dirty, out of service, or ready. This acts on the `service_point` record itself, independently of any tab seated there.\n\n#### Signature\n\n```http\nPOST /storefront/service-point/{id}/status (id: string, body) -> The updated service point\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | STATUS_REQUIRED | status is required | `status` is missing from the body. | Send the new status value. |\n| `404` | SERVICE_POINT_NOT_FOUND | Service point not found | No `service_point` in the org has that id. | Check the id. Note that the assign endpoint returns `400` for the same condition; this one returns `404`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/assign-service-point`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"`service_point` id.","schema":{"type":"string"},"example":"sp_t7"}],"requestBody":{"description":"The new status.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"New service point status, e.g. `available`, `occupied`, `dirty`, `out-of-service`.","example":"dirty"},"note":{"type":"string","description":"Optional note recorded with the change.","example":"Needs bussing"}}},"example":{"status":"dirty","note":"Needs bussing"}}}},"responses":{"201":{"description":"The updated service point","content":{"application/json":{"schema":{"type":"object","description":"A `service_point` record.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"status is required — `status` is missing from the body.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"status is required","path":"/storefront/service-point/{id}/status","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Service point not found — No `service_point` in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Service point not found","path":"/storefront/service-point/{id}/status","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/order/{id}/items":{"post":{"operationId":"StorefrontController_addItemsToOrder","summary":"Add items to an order","description":"Appends lines to an open tab and recomputes `productCount`, `productSubtotal`, `subtotal`, `tax` and `amount`. Each item is resolved against the catalog by `sku`, so pricing and titles come from the product record rather than the client.\n\n#### Signature\n\n```http\nPOST /storefront/order/{id}/items (id: string, body) -> The updated order with recomputed totals\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Adding lines does not fire them. Send them to a workflow with `POST /storefront/order/{id}/fire`.\n- POS gate: adding lines checks the whole-register gate for the operator, then — for a product with `restriction.ageRestricted` / `restriction.permissionScope` (e.g. alcohol) — the gate with that `permissionScope`. A refusal is 423 `readiness_block` naming the product (`sku`, `productName`, `permissionScope`). Lines carry `permissionScope` and any `readinessOverride`; warnings return as `readiness.warnings`.\n- Workforce Readiness: with no requirement rules this endpoint behaves exactly as before. `warn` never stops anything — it comes back as `readiness.warnings` in the response.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | ORDER_NOT_OPEN | Cannot add items to <status> order | The order is in a status that no longer accepts lines. | Open a new tab instead of amending a closed one. |\n| `423` | READINESS_BLOCK | <name> can't sell <product> (alcohol): <requirement titles>. | A requirement rule whose `enforcement.pos` effect is block (or override-with-reason) is unmet for this person, and no override is active. | Show `message` and `reasons`. A location manager or HR can resend the same request with `override: { reasonCode, reason, expiresAt }` — it is written to the readiness ledger with the approver and expiry. The person’s own override is refused. |\n| `403` | OVERRIDE_FORBIDDEN | Sign in as a location manager or HR to override. | The caller may not approve an override (no caller, the person themselves, or only their own supervisor). | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/{id}/fire`\n- `POST /storefront/pos/tab/{id}/settle`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Order `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"The lines to add.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"One entry per line. Sending the same `sku` twice creates two lines.","items":{"type":"object","required":["sku"],"properties":{"sku":{"type":"string","description":"Catalog SKU. Must resolve to an `sf_product`.","example":"DRK-COLA-330"},"quantity":{"type":"number","default":1,"example":2},"course":{"type":"string","description":"Service course for coursed dining.","example":"main"},"seat":{"type":"string","description":"Seat identifier.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"}}}},"override":{"type":"object","description":"Readiness override (manager/HR): lets this action go ahead despite a block. Recorded per blocking requirement.","properties":{"reasonCode":{"type":"string","enum":["renewal_booked","awaiting_document","training_scheduled","business_need","not_applicable","system_error","other"]},"reason":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}},"examples":{"single":{"summary":"One line","value":{"items":[{"sku":"DRK-COLA-330","quantity":2}]}},"coursed":{"summary":"Coursed and seated","value":{"items":[{"sku":"FOO-STEAK","quantity":1,"course":"main","seat":"2","specialInstructions":"medium rare"}]}}}}}},"responses":{"201":{"description":"The updated order with recomputed totals","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"400":{"description":"Cannot add items to <status> order — The order is in a status that no longer accepts lines.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot add items to <status> order","path":"/storefront/order/{id}/items","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"Sign in as a location manager or HR to override. — The caller may not approve an override (no caller, the person themselves, or only their own supervisor).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Sign in as a location manager or HR to override.","path":"/storefront/order/{id}/items","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/{id}/items","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"423":{"description":"<name> can't sell <product> (alcohol): <requirement titles>. — A requirement rule whose `enforcement.pos` effect is block (or override-with-reason) is unmet for this person, and no override is active.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"reason":"readiness_block","code":"READINESS_BLOCK","gate":"pos","message":"Luis Ramirez can't clock in: Food handler card.","employeeId":"E012","employeeName":"Luis Ramirez","effect":"block","blocking":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","expiresAt":"2026-09-20T00:00:00.000Z"}],"warnings":[],"reasons":[{"requirementId":"REQ-FOOD01","title":"Food handler card","kind":"certification","status":"expired","severity":"block"}],"canOverride":true,"override":{"how":"Send the same request again with override: { reasonCode, reason, expiresAt }.","fields":["reasonCode","reason","expiresAt"],"reasonCodes":["renewal_booked","awaiting_document","training_scheduled","business_need","not_applicable","system_error","other"],"approver":"A location manager or HR. The person’s own supervisor alone cannot approve."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/order/{id}/fire":{"post":{"operationId":"StorefrontController_fireOrderItems","summary":"Fire order items to a workflow","description":"Sends selected lines to the prep line (a preparation workflow, `prep-pipeline` by default — food prep, bar, lab, wash bay, service job), one ticket per prep station, and stamps the resulting `taskId` onto each fired line.\n\n**`taskId` is the definition of \"sent\".** Lines that already carry one are skipped, which makes the endpoint safe against double-clicks and stale client caches. If *every* requested line was already fired the request fails rather than silently doing nothing, so the operator gets told.\n\n#### Signature\n\n```http\nPOST /storefront/order/{id}/fire (id: string, body) -> The order with `taskId` stamped on the newly fired lines\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Partial success is normal: unfired lines in `itemIds` are fired and already-fired ones are skipped, with no error.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No `sf_order` in the org has the given `sk`. | Confirm the tab `sk`. `GET /storefront/pos/tabs` lists the open tabs for a location. |\n| `400` | ITEM_IDS_REQUIRED | itemIds required | `itemIds` is missing or empty. | Send at least one line id. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/{id}/items`\n- `GET /storefront/order/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Order `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"description":"Which lines to fire, and where.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["itemIds"],"properties":{"itemIds":{"type":"array","items":{"type":"string"},"description":"Line ids from `productItems[].id`. Already-fired lines are ignored.","example":["li_7f3a","li_8b2c"]},"workflowId":{"type":"string","description":"Target workflow by id. Takes precedence over `workflowName`."},"workflowName":{"type":"string","default":"prep-pipeline","description":"Target workflow by name when `workflowId` is absent.","example":"prep-pipeline"},"course":{"type":"string","description":"Course stamped on the fired task.","example":"main"},"seat":{"type":"string","example":"2"},"specialInstructions":{"type":"string","description":"Carried onto the task ticket.","example":"allergy: shellfish"}}},"examples":{"prepLine":{"summary":"Send two lines to the prep line","value":{"itemIds":["li_7f3a","li_8b2c"],"workflowName":"prep-pipeline"}},"default":{"summary":"Fire to the default pipeline","description":"Omitting both workflow fields uses `prep-pipeline`.","value":{"itemIds":["li_7f3a"]}}}}}},"responses":{"201":{"description":"The order with `taskId` stamped on the newly fired lines","content":{"application/json":{"schema":{"type":"object","description":"A POS tab or web order (`sf_order`). POS tabs and web orders share one shape and one collection.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","description":"Lifecycle status. `new` on open; terminal values close the tab.","example":"new"},"orderType":{"type":"string","example":"product"},"number":{"type":"string","description":"Human display number, stamped at tab open. Payments and refunds are recorded against this, never the `sk` — a tab missing it cannot be settled.","example":"A7K2M9QX4"},"alias":{"type":"string","description":"Operator-facing label (Table 7, Walk-up #3, Smith party).","example":"Table 7"},"businessLocationId":{"type":"string","description":"Location the tab belongs to.","example":"loc_downtown"},"servicePointId":{"type":"string","description":"Assigned table/counter, when one is held.","example":"sp_t7"},"productItems":{"type":"array","items":{"type":"object","description":"A line on the tab.","properties":{"id":{"type":"string","description":"Line id, unique within the order. This is what `itemIds` refers to.","example":"li_7f3a"},"sku":{"type":"string","example":"DRK-COLA-330"},"title":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price at the time the line was added.","example":12},"course":{"type":"string","description":"Service course, e.g. `starter`, `main`.","example":"main"},"seat":{"type":"string","description":"Seat identifier for coursed service.","example":"2"},"specialInstructions":{"type":"string","example":"no ice"},"taskId":{"type":"string","description":"Set once the line has been fired to a workflow. **The presence of `taskId` is what \"sent to the prep line\" means** — it is the idempotency marker, and fired lines are skipped by subsequent fire requests.","example":"tsk_91b2"},"task":{"type":"object","additionalProperties":true,"description":"The workflow task, populated inline on task-enriched reads."}}}},"productCount":{"type":"number","example":2},"subtotal":{"type":"number","example":24},"productSubtotal":{"type":"number","example":24},"tax":{"type":"number","example":1.92},"discount":{"type":"number","example":0},"amount":{"type":"number","description":"Order total.","example":25.92},"amountPaid":{"type":"number","description":"Sum of recorded tenders, net of refunds.","example":0},"currency":{"type":"string","default":"USD","example":"USD"},"payments":{"type":"array","description":"Recorded tenders, newest last. Refunded lines keep `refunded: true` rather than being removed.","items":{"type":"object","properties":{"transactionId":{"type":"string","example":"txn_4a91"},"ref":{"type":"string","description":"Gateway or operator reference.","example":"ch_3Pabc"},"amount":{"type":"number","example":25.92},"method":{"type":"string","example":"card"},"gateway":{"type":"string","example":"stripe"},"tip":{"type":"number","example":3},"refunded":{"type":"boolean","example":false}}}},"customer":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string","example":"Ada Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}}}}}}}}},"400":{"description":"itemIds required — `itemIds` is missing or empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"itemIds required","path":"/storefront/order/{id}/fire","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No `sf_order` in the org has the given `sk`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/{id}/fire","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · POS"]}},"/storefront/cart/mine":{"get":{"operationId":"StorefrontController_savedCart","summary":"Restore my saved cart","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The saved cart, or null","content":{"application/json":{"schema":{"type":"object","description":"A shopping cart (`sf_cart`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"image":{"type":"string"},"options":{"type":"string","description":"Selected variant options.","example":"size:330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}}},"subtotal":{"type":"number","example":24},"discount":{"type":"number","example":0},"tax":{"type":"number","example":1.92},"total":{"type":"number","example":25.92},"currency":{"type":"string","example":"USD"},"couponCode":{"type":"string","description":"Applied coupon, when one validated.","example":"SUMMER20"}}}},"nullable":true}}}},"401":{"description":"Sign in to restore your saved cart — No customer session for this org (a staff/user token does not count).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Sign in to restore your saved cart","path":"/storefront/cart/mine","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Checkout"],"description":"The signed-in customer's saved cart (`sf_cart`), for restoring a basket on a new device. Identity comes only from the customer session — never from a supplied email or id — and the cart is scoped to the customer's shared account when they have one. Read-only: returns `null` rather than creating a cart.\n\n#### Signature\n\n```http\nGET /storefront/cart/mine () -> The saved cart, or null\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | SIGN_IN_REQUIRED | Sign in to restore your saved cart | No customer session for this org (a staff/user token does not count). | — |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/cart/get/{authorid}/{cartid}`"}},"/storefront/cart/get/{authorid}/{cartid}":{"get":{"operationId":"StorefrontController_cart","summary":"Get a cart","description":"Returns a cart with its items and computed totals.\n\n**The `authorid` segment is ignored.** The handler resolves the cart from `cartid` and the authenticated caller only — the path parameter is a historical artefact. It is still required by the route, so pass any non-empty value, but do not expect it to scope the lookup.\n\n#### Signature\n\n```http\nGET /storefront/cart/get/{authorid}/{cartid} (authorid: string, cartid: string) -> The cart with items and totals\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Because `authorid` is not used, do not rely on it to isolate carts between customers.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/cart/update/{cartid}`\n- `POST /storefront/checkout-cart`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"cartid","required":true,"in":"path","description":"Cart id. Optional segment — omitted resolves the caller's current cart.","schema":{"type":"string"},"example":"cart_9f21"},{"name":"authorid","required":true,"in":"path","description":"Ignored by the handler. Required by the route; pass the customer id for readability.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"The cart with items and totals","content":{"application/json":{"schema":{"type":"object","description":"A shopping cart (`sf_cart`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"image":{"type":"string"},"options":{"type":"string","description":"Selected variant options.","example":"size:330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}}},"subtotal":{"type":"number","example":24},"discount":{"type":"number","example":0},"tax":{"type":"number","example":1.92},"total":{"type":"number","example":25.92},"currency":{"type":"string","example":"USD"},"couponCode":{"type":"string","description":"Applied coupon, when one validated.","example":"SUMMER20"}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Cart"]}},"/storefront/cart/update/{cartid}":{"post":{"operationId":"StorefrontController_cartUpdate","summary":"Update a cart","description":"Writes the cart contents and recomputes subtotal, discount, tax and total. This is the single mutation endpoint for carts — adding, changing quantity and removing a line are all expressed as an updated `items` array.\n\nSend a coupon with `couponCode` to have it validated and applied as part of the same call.\n\n#### Signature\n\n```http\nPOST /storefront/cart/update/{cartid} (cartid: string, body) -> The updated cart with recomputed totals\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- `items` replaces the stored array rather than merging. Read the cart, modify the list, send it back.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CART_NOT_FOUND | Cart not found | No cart in the org has that id. | Create a cart by updating one with a new id, or re-read the customer's cart. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/cart/get/{authorid}/{cartid}`\n- `GET /storefront/cart/clear/{cartid}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"cartid","required":true,"in":"path","description":"Cart id.","schema":{"type":"string"},"example":"cart_9f21"}],"requestBody":{"description":"The cart contents to store.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"image":{"type":"string"},"options":{"type":"string","description":"Selected variant options.","example":"size:330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}},"description":"The full line set. Replaces what is stored — send every line you want to keep."},"couponCode":{"type":"string","description":"Coupon to validate and apply.","example":"SUMMER20"},"currency":{"type":"string","example":"USD"}}},"examples":{"setItems":{"summary":"Set the cart contents","value":{"items":[{"sku":"DRK-COLA-330","quantity":2,"price":12}]}},"removeLine":{"summary":"Remove a line","description":"Omit it from `items` — there is no delete endpoint.","value":{"items":[]}},"withCoupon":{"summary":"Apply a coupon","value":{"items":[{"sku":"DRK-COLA-330","quantity":2,"price":12}],"couponCode":"SUMMER20"}}}}}},"responses":{"201":{"description":"The updated cart with recomputed totals","content":{"application/json":{"schema":{"type":"object","description":"A shopping cart (`sf_cart`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"image":{"type":"string"},"options":{"type":"string","description":"Selected variant options.","example":"size:330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}}},"subtotal":{"type":"number","example":24},"discount":{"type":"number","example":0},"tax":{"type":"number","example":1.92},"total":{"type":"number","example":25.92},"currency":{"type":"string","example":"USD"},"couponCode":{"type":"string","description":"Applied coupon, when one validated.","example":"SUMMER20"}}}}}}}},"404":{"description":"Cart not found — No cart in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Cart not found","path":"/storefront/cart/update/{cartid}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Cart"]}},"/storefront/cart/clear/{cartid}":{"get":{"operationId":"StorefrontController_cartClear","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"cartid","in":"path","required":true,"description":"Cart id.","schema":{"type":"string"},"example":"cart_9f21"}],"responses":{"200":{"description":"The emptied cart","content":{"application/json":{"schema":{"type":"object","description":"A shopping cart (`sf_cart`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"image":{"type":"string"},"options":{"type":"string","description":"Selected variant options.","example":"size:330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}}},"subtotal":{"type":"number","example":24},"discount":{"type":"number","example":0},"tax":{"type":"number","example":1.92},"total":{"type":"number","example":25.92},"currency":{"type":"string","example":"USD"},"couponCode":{"type":"string","description":"Applied coupon, when one validated.","example":"SUMMER20"}}}}}}}},"404":{"description":"Cart not found — No cart in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Cart not found","path":"/storefront/cart/clear/{cartid}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Cart"],"summary":"Clear a cart","description":"Empties the cart, leaving the record in place so the same id stays usable.\n\nThis mutation is mounted on `GET`, so anything that follows links — a crawler, a link preview, a browser prefetch — can empty a customer's cart. Do not expose the URL where it may be fetched automatically.\n\n#### Signature\n\n```http\nGET /storefront/cart/clear/{cartid} (cartid: string) -> The emptied cart\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CART_NOT_FOUND | Cart not found | No cart in the org has that id. | Create a cart by updating one with a new id, or re-read the customer's cart. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/cart/update/{cartid}`"}},"/storefront/order/email/{email}/{orderNumber}":{"get":{"operationId":"StorefrontController_orderByEmail","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","in":"path","required":true,"description":"Email address used at checkout.","schema":{"type":"string"},"example":"ada@example.com"},{"name":"orderNumber","in":"path","required":true,"description":"The public order number (`data.number`), not the record `sk`.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"The matching order","content":{"application/json":{"schema":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/email/{email}/{orderNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"summary":"Look up an order by email","description":"Guest order lookup: resolves an order from the email address used at checkout plus the order number. This is the pairing behind \"track my order\" forms, where the customer has no account.\n\n#### Signature\n\n```http\nGET /storefront/order/email/{email}/{orderNumber} (email: string, orderNumber: string) -> The matching order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Knowing an email and an order number is sufficient to read the order. Rate-limit any public form built on this.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/order/get/{author}/{orderNumber}`"}},"/storefront/order/get/{author}/{orderNumber}":{"get":{"operationId":"StorefrontController_order","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"author","in":"path","required":true,"description":"Customer email or username.","schema":{"type":"string"},"example":"ada@example.com"},{"name":"orderNumber","in":"path","required":true,"description":"The public order number (`data.number`), not the record `sk`.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"The matching order","content":{"application/json":{"schema":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/get/{author}/{orderNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"summary":"Get a customer's order","description":"Fetches one order, scoped to the customer who placed it. Both the author and the order number must match.\n\n#### Signature\n\n```http\nGET /storefront/order/get/{author}/{orderNumber} (author: string, orderNumber: string) -> The matching order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/order/email/{email}/{orderNumber}`"}},"/storefront/orders/get/{author}":{"get":{"operationId":"StorefrontController_orders","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"author","in":"path","required":true,"description":"Customer email or username.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"The customer's orders","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"summary":"List a customer's orders","description":"Returns every order placed by the given customer, identified by the email or username recorded as the order author.\n\n#### Signature\n\n```http\nGET /storefront/orders/get/{author} (author: string) -> The customer's orders\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- This is a customer-scoped read on a public route — treat the author value as sensitive and do not expose it in client-side URLs you did not construct.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/order/get/{author}/{orderNumber}`"}},"/storefront/order/remove/{author}/{orderNumber}":{"get":{"operationId":"StorefrontController_orderRemove","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"author","in":"path","required":true,"description":"Customer email or username.","schema":{"type":"string"},"example":"ada@example.com"},{"name":"orderNumber","in":"path","required":true,"description":"The public order number. Optional segment.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/remove/{author}/{orderNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"summary":"Remove an order","description":"Deletes an order belonging to the given customer.\n\nNote that this destructive operation is mounted on `GET`, so it can be triggered by anything that follows a link — a crawler, a prefetch, a preview. Never place this URL where it can be fetched automatically.\n\n#### Signature\n\n```http\nGET /storefront/order/remove/{author}/{orderNumber} (author: string, orderNumber: string) -> Removal result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Prefer `POST /storefront/order/cancel/{orderNumber}`, which preserves the record and its audit trail.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/cancel/{orderNumber}`"}},"/storefront/order/send-welcome/{orderNumber}":{"get":{"operationId":"StorefrontController_orderSendWelcome","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","in":"path","required":true,"description":"The public order number (`data.number`), not the record `sk`.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"Dispatch result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/send-welcome/{orderNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"summary":"Send the order confirmation email","description":"Re-sends the order confirmation to the address on the order, through the org's notification pipeline (template chain: org → shared-org → factory default). Useful when a customer did not receive the original.\n\n#### Signature\n\n```http\nGET /storefront/order/send-welcome/{orderNumber} (orderNumber: string) -> Dispatch result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Sends every time it is called — there is no once-only guard, so a retry mails the customer again.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n\nPlus the standard platform errors: `429`, `500`."}},"/storefront/order/refund/{orderNumber}":{"post":{"operationId":"StorefrontController_orderRefund","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","in":"path","required":true,"description":"The public order number (`data.number`), not the record `sk`.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"201":{"description":"The refund result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}}}}}}},"400":{"description":"Order has no payment to refund — The order has never been paid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Order has no payment to refund","path":"/storefront/order/refund/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/refund/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"summary":"Refund an order","description":"Refunds a paid order, in full or in part, without cancelling it. Use this for goodwill refunds and returns where the order itself stands.\n\nFor refunding one specific tender on a POS tab, use `POST /storefront/pos/tab/{id}/refund`, which targets an individual payment line.\n\n#### Signature\n\n```http\nPOST /storefront/order/refund/{orderNumber} (orderNumber: string, body) -> The refund result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | NO_PAYMENT | Order has no payment to refund | The order has never been paid. | Cancel the order instead — there is nothing to return. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pos/tab/{id}/refund`\n- `POST /storefront/order/cancel/{orderNumber}`","requestBody":{"description":"Refund details.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Amount to refund. Defaults to the full paid amount. Must be positive and within the unrefunded balance.","example":25},"reason":{"type":"string","description":"Recorded with the refund.","example":"Damaged in transit"}}},"examples":{"full":{"summary":"Full refund","value":{"reason":"Damaged in transit"}},"partial":{"summary":"Partial refund","value":{"amount":25,"reason":"Goodwill — late delivery"}}}}}}}},"/storefront/order/cancel/{orderNumber}":{"post":{"operationId":"StorefrontController_orderCancel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","in":"path","required":true,"description":"The public order number (`data.number`), not the record `sk`.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"201":{"description":"The cancelled order, with refund details when one was issued","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"refundResult":{"type":"object","additionalProperties":true,"nullable":true,"description":"The refund that was issued, or `null` when the order was unpaid."},"message":{"type":"string","example":"Order cancelled"}}}}}},"400":{"description":"Cannot cancel order with status \"<status>\". Orders that are shipped, in transit, or delivered cannot be cancelled. — The order status is one of `shipped`, `in_transit`, `delivered`, `cancelled` or `refunded`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot cancel order with status \"<status>\". Orders that are shipped, in transit, or delivered cannot be cancelled.","path":"/storefront/order/cancel/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/cancel/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"summary":"Cancel an order","description":"Cancels an order and, when it has been paid, triggers a refund as part of the same operation.\n\nCancellation is blocked once goods are in the customer's hands or on their way — a shipped, in-transit or delivered order must be returned rather than cancelled.\n\n#### Signature\n\n```http\nPOST /storefront/order/cancel/{orderNumber} (orderNumber: string, body) -> The cancelled order, with refund details when one was issued\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Cancelling a paid order refunds it automatically — do not also call the refund endpoint, or you will attempt to refund twice.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | NOT_CANCELLABLE | Cannot cancel order with status \"<status>\". Orders that are shipped, in transit, or delivered cannot be cancelled. | The order status is one of `shipped`, `in_transit`, `delivered`, `cancelled` or `refunded`. | Process a return or a refund instead. `POST /storefront/order/refund/{orderNumber}` refunds without cancelling. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/refund/{orderNumber}`","requestBody":{"description":"Optional cancellation details.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why the order was cancelled. Recorded in the status history.","example":"Customer changed their mind"},"note":{"type":"string","description":"Additional note."}}},"example":{"reason":"Customer changed their mind"}}}}}},"/storefront/order/process/{orderNumber}":{"post":{"operationId":"StorefrontController_orderProcess","summary":"Mark an order as being fulfilled","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The updated order and a confirmation message","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"400":{"description":"Cannot process order with status \"<status>\" — The order's current status is one of `cancelled`, `refunded`, `shipped`, `delivered`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot process order with status \"<status>\"","path":"/storefront/order/process/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/process/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Moves the order to `processing` and stamps `processedAt`. This is the first step of fulfilment — the point where a warehouse picks up the order.\n\nUnlike `set-status`, this transition fires the automation and events attached to processing.\n\n#### Signature\n\n```http\nPOST /storefront/order/process/{orderNumber} (orderNumber: string, body) -> The updated order and a confirmation message\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | INVALID_TRANSITION | Cannot process order with status \"<status>\" | The order's current status is one of `cancelled`, `refunded`, `shipped`, `delivered`. | An order that has already shipped or been closed cannot re-enter fulfilment. Use `set-status` if you must override. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/ship/{orderNumber}`\n- `POST /storefront/order/set-status/{orderNumber}`","requestBody":{"description":"Optional note recorded in the status history.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Recorded against this transition in `statusHistory`.","example":"Picked and packed"}}},"examples":{"withNote":{"summary":"With a note","value":{"note":"Picked and packed"}},"bare":{"summary":"No note","value":{}}}}}}}},"/storefront/order/ship/{orderNumber}":{"post":{"operationId":"StorefrontController_orderShip","summary":"Ship an order","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The updated order and a confirmation message","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"400":{"description":"Cannot ship order with status \"<status>\" — The order's current status is one of `cancelled`, `refunded`, `delivered`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot ship order with status \"<status>\"","path":"/storefront/order/ship/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/ship/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Records a shipment and moves the order to `shipped`, stamping `shippedAt`.\n\nEach call appends an entry to `shippingInfo[]` rather than replacing it, so an order fulfilled in several parcels accumulates one entry per shipment. Pass `items` to record which lines went in which parcel.\n\n#### Signature\n\n```http\nPOST /storefront/order/ship/{orderNumber} (orderNumber: string, body) -> The updated order and a confirmation message\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- An already-`shipped` order can be shipped again — that is how multi-parcel fulfilment is recorded.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | INVALID_TRANSITION | Cannot ship order with status \"<status>\" | The order's current status is one of `cancelled`, `refunded`, `delivered`. | A cancelled, refunded or already-delivered order cannot be shipped. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/deliver/{orderNumber}`","requestBody":{"description":"Shipment details. `carrier` and `tracking` are both required.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["carrier","tracking"],"properties":{"carrier":{"type":"string","description":"Carrier handling the shipment.","example":"ups"},"tracking":{"type":"string","description":"Tracking number.","example":"1Z999AA10123456784"},"service":{"type":"string","description":"Service level.","example":"ground"},"cost":{"type":"number","description":"Shipping cost, for reporting.","example":12.5},"items":{"type":"array","description":"Lines included in this parcel. Omit when the whole order ships together.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","example":2}}}},"note":{"type":"string","description":"Recorded in the status history.","example":"Left with front desk"}}},"examples":{"whole":{"summary":"Ship the whole order","value":{"carrier":"ups","tracking":"1Z999AA10123456784","service":"ground","cost":12.5}},"partial":{"summary":"Ship part of the order","description":"Call again with the remaining lines to add a second shipment.","value":{"carrier":"ups","tracking":"1Z999AA10123456784","items":[{"sku":"DRK-COLA-330","quantity":2}]}}}}}}}},"/storefront/order/stock-retry/{orderNumber}":{"post":{"operationId":"StorefrontController_orderStockRetry","summary":"Retry stock for an order","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The order and its stock record (`data.orderInventory`) after the retry","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"stock":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/stock-retry/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This is a POS sale — use Retry stock on the tab — The order is a POS tab.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This is a POS sale — use Retry stock on the tab","path":"/storefront/order/stock-retry/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Takes out of stock what has already shipped but could not be drawn — the inventory row had no unit cost, or no single stock location holds the SKU — and posts its cost of goods.\n\nGoods never leave stock unvalued: like a POS sale, an order line with no unit cost is not drawn and the order's `orderInventory` says \"Set a non-negative unit cost on inventory for <SKU> at <location>, then retry stock\". Set the cost in Inventory, then call this. A shipped, delivered or completed order owes every line; a partially shipped one owes what its shipments carried. Never takes a unit twice.\n\n#### Signature\n\n```http\nPOST /storefront/order/stock-retry/{orderNumber} (orderNumber: string) -> The order and its stock record (`data.orderInventory`) after the retry\n```\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `409` | POS_SALE | This is a POS sale — use Retry stock on the tab | The order is a POS tab. | Use Retry stock on the tab in POS. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/ship/{orderNumber}`\n- `POST /storefront/order/complete/{orderNumber}`"}},"/storefront/order/deliver/{orderNumber}":{"post":{"operationId":"StorefrontController_orderDeliver","summary":"Mark an order as delivered","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The updated order and a confirmation message","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"400":{"description":"Cannot mark as delivered - order status is \"<status>\" — The order is not in `shipped`, `in_transit` or `out_for_delivery`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot mark as delivered - order status is \"<status>\"","path":"/storefront/order/deliver/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/deliver/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Moves the order to `delivered` and stamps `deliveredAt`.\n\nThis transition is gated the opposite way to the others: rather than blocking a set of statuses it **requires** the order to already be in transit — `shipped`, `in_transit` or `out_for_delivery`. An order that was never marked shipped cannot be marked delivered.\n\n#### Signature\n\n```http\nPOST /storefront/order/deliver/{orderNumber} (orderNumber: string, body) -> The updated order and a confirmation message\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | NOT_IN_TRANSIT | Cannot mark as delivered - order status is \"<status>\" | The order is not in `shipped`, `in_transit` or `out_for_delivery`. | Ship the order first, or use `set-status` for a flow that skips shipping — local pickup, for instance. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/ship/{orderNumber}`\n- `POST /storefront/order/complete/{orderNumber}`","requestBody":{"description":"Optional note recorded in the status history.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Recorded against this transition in `statusHistory`.","example":"Signed for by Ada"}}},"examples":{"withNote":{"summary":"With a note","value":{"note":"Signed for by Ada"}},"bare":{"summary":"No note","value":{}}}}}}}},"/storefront/order/hold/{orderNumber}":{"post":{"operationId":"StorefrontController_orderHold","summary":"Put an order on hold","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The held order and a confirmation message","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"400":{"description":"Cannot hold order with status \"<status>\" — The order's current status is one of `cancelled`, `refunded`, `delivered`, `completed`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot hold order with status \"<status>\"","path":"/storefront/order/hold/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/hold/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Pauses an order: sets the status to `on_hold`, records `holdReason` and `heldAt`, and saves the current status in `previousStatus` so the order can be restored exactly where it left off.\n\nA `reason` is required — a held order with no explanation is not useful to whoever picks it up next.\n\n#### Signature\n\n```http\nPOST /storefront/order/hold/{orderNumber} (orderNumber: string, body) -> The held order and a confirmation message\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Holding an already-held order overwrites `previousStatus` with `on_hold`, so release would restore it to `on_hold`. Check the status before holding.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | INVALID_TRANSITION | Cannot hold order with status \"<status>\" | The order's current status is one of `cancelled`, `refunded`, `delivered`, `completed`. | A closed order cannot be held. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/release/{orderNumber}`","requestBody":{"description":"Why the order is being held.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Stored as `holdReason` and recorded in the status history.","example":"Awaiting stock"}}},"example":{"reason":"Awaiting stock"}}}}}},"/storefront/order/release/{orderNumber}":{"post":{"operationId":"StorefrontController_orderRelease","summary":"Release an order from hold","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The released order and a confirmation message","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"400":{"description":"Order is not on hold — The order status is anything other than `on_hold`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Order is not on hold","path":"/storefront/order/release/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/release/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Restores a held order to the status it had before the hold, clearing `previousStatus` and `holdReason`. When no previous status was recorded the order falls back to `processing`.\n\n#### Signature\n\n```http\nPOST /storefront/order/release/{orderNumber} (orderNumber: string) -> The released order and a confirmation message\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | NOT_ON_HOLD | Order is not on hold | The order status is anything other than `on_hold`. | Only a held order can be released. Read the order first if you are unsure of its state. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/hold/{orderNumber}`"}},"/storefront/order/complete/{orderNumber}":{"post":{"operationId":"StorefrontController_orderComplete","summary":"Complete an order","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The completed order and a confirmation message","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"400":{"description":"Cannot complete order - must be delivered first — The order status is anything other than `delivered`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot complete order - must be delivered first","path":"/storefront/order/complete/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/complete/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Closes the order, moving it to `completed` and stamping `completedAt`. This is the terminal step of a successful order.\n\nThe order **must** be `delivered` first — completion is not a shortcut past the rest of the lifecycle.\n\n#### Signature\n\n```http\nPOST /storefront/order/complete/{orderNumber} (orderNumber: string) -> The completed order and a confirmation message\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | NOT_DELIVERED | Cannot complete order - must be delivered first | The order status is anything other than `delivered`. | Mark the order delivered first, or use `set-status` to close an order that never followed the ship → deliver path. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/deliver/{orderNumber}`"}},"/storefront/order/set-status/{orderNumber}":{"post":{"operationId":"StorefrontController_orderSetStatus","summary":"Set an order status directly","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The updated order and a confirmation message","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"400":{"description":"Invalid status \"<status>\" — `status` is missing, or is not one of the recognised values.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid status \"<status>\"","path":"/storefront/order/set-status/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/set-status/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Operator override. Sets `data.status`, stamps the matching timestamp field and appends to the status history — and does nothing else.\n\n**It deliberately skips both the preconditions and the automation** of the dedicated transitions: no delivery emails, no workflow advance, no step validation. Reach for it to correct a mistaken state, or to drive an order that never follows ship → deliver (local pickup, digital goods). Use the dedicated endpoints whenever you want the side effects.\n\nThe status must be one of the recognised values; anything else is rejected rather than stored.\n\n#### Signature\n\n```http\nPOST /storefront/order/set-status/{orderNumber} (orderNumber: string, body) -> The updated order and a confirmation message\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- No events fire. If a customer should be notified of this change, send the notification yourself.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n| `400` | INVALID_STATUS | Invalid status \"<status>\" | `status` is missing, or is not one of the recognised values. | Use one of: `new`, `awaiting-payment`, `paid-partial`, `paid`, `confirmed`, `processing`, `shipped`, `in_transit`, `out_for_delivery`, `delivered`, `completed`, `on_hold`, `failed`, `returned`, `refunded`, `cancelled`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/order/process/{orderNumber}`\n- `POST /storefront/order/deliver/{orderNumber}`","requestBody":{"description":"The status to set.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"description":"The new status. Must be one of the recognised values.","example":"completed"},"note":{"type":"string","description":"Recorded in the status history.","example":"Collected in store"}}},"examples":{"localPickup":{"summary":"Close a local-pickup order","description":"Skips ship → deliver, which local pickup never goes through.","value":{"status":"completed","note":"Collected in store"}},"correction":{"summary":"Correct a mistaken status","value":{"status":"processing","note":"Marked shipped in error"}}}}}}}},"/storefront/order/update/{orderNumber}":{"post":{"operationId":"StorefrontController_orderUpdateInfo","summary":"Update order details","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","schema":{"type":"string"},"description":"The public order number (`data.number`), not the record `sk`.","example":"A7K2M9QX4"}],"responses":{"201":{"description":"The updated order","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"An order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Public order number — the identifier these endpoints take.","example":"A7K2M9QX4"},"status":{"type":"string","enum":["new","awaiting-payment","paid-partial","paid","confirmed","processing","shipped","in_transit","out_for_delivery","delivered","completed","on_hold","failed","returned","refunded","cancelled"],"example":"processing"},"amount":{"type":"number","example":129.99},"amountPaid":{"type":"number","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"statusHistory":{"type":"array","description":"Append-only audit trail. Each transition records where it came from, where it went, when, and any note.","items":{"type":"object","properties":{"from":{"type":"string","example":"paid"},"to":{"type":"string","example":"processing"},"note":{"type":"string","example":"Picked and packed"},"at":{"type":"string","format":"date-time","example":"2026-08-29T14:03:22.118Z"}}}},"shippingInfo":{"type":"array","description":"One entry per shipment. An order shipped in parts accumulates several.","items":{"type":"object","properties":{"id":{"type":"string","example":"ship-1756476202118"},"carrier":{"type":"string","example":"ups"},"tracking":{"type":"string","example":"1Z999AA10123456784"},"service":{"type":"string","example":"ground"},"cost":{"type":"number","example":12.5},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}}},"previousStatus":{"type":"string","description":"Set while an order is `on_hold` so release can restore it. Removed on release.","example":"processing"},"holdReason":{"type":"string","description":"Present only while on hold.","example":"Awaiting stock"},"paidAt":{"type":"string","format":"date-time"},"fulfilledAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"message":{"type":"string","description":"Human-readable confirmation of what happened.","example":"Order placed on hold"}}}}}},"404":{"description":"Order not found — No order in the org has that public order number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order not found","path":"/storefront/order/update/{orderNumber}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Orders"],"description":"Edits the non-lifecycle fields of an order — addresses, notes and tags. It does not change the status; use the lifecycle endpoints for that.\n\nOnly the fields present in the body are written, so a partial update leaves everything else intact.\n\n#### Signature\n\n```http\nPOST /storefront/order/update/{orderNumber} (orderNumber: string, body) -> The updated order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- `tags` replaces the whole array rather than merging — send the full set you want to keep.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | ORDER_NOT_FOUND | Order not found | No order in the org has that public order number. | Confirm the number. These endpoints take `data.number`, not the record `sk`. |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"description":"Fields to update. All optional; omitted fields are left unchanged.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shippingInfo":{"type":"object","additionalProperties":true,"description":"Shipping details."},"shippingAddress":{"type":"object","additionalProperties":true,"description":"Delivery address."},"billingAddress":{"type":"object","additionalProperties":true,"description":"Billing address."},"notes":{"type":"string","description":"Customer-visible notes.","example":"Leave with the neighbour"},"internalNotes":{"type":"string","description":"Operator-only notes. Not shown to the customer.","example":"VIP — expedite"},"tags":{"type":"array","items":{"type":"string"},"description":"Replaces the existing tags.","example":["vip","fragile"]}}},"examples":{"address":{"summary":"Correct the delivery address","value":{"shippingAddress":{"line1":"12 Ada Way","city":"London","postcode":"E1 6AN","country":"GB"}}},"notes":{"summary":"Add an internal note and tags","value":{"internalNotes":"VIP — expedite","tags":["vip","fragile"]}}}}}}}},"/storefront/subscriptions/get/{author}/{subscriptionid}":{"get":{"operationId":"StorefrontController_getSubscriptions","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"author","in":"path","required":true,"description":"Customer email or username.","schema":{"type":"string"},"example":"ada@example.com"},{"name":"subscriptionid","in":"path","required":true,"description":"Subscription number. Omit to list every subscription for the customer.","schema":{"type":"string"},"example":"SUB-4821"},{"name":"enrich","in":"query","required":false,"description":"Resolve linked plan and product records inline.","schema":{"type":"boolean","default":false},"example":true}],"responses":{"200":{"description":"The customer's subscriptions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Get a customer's subscriptions","description":"Returns the subscriptions belonging to a customer. Supply `subscriptionid` to fetch one; omit the segment to list them all.\n\nPass `enrich=true` to resolve the linked plan and product records inline instead of returning bare references.\n\n#### Signature\n\n```http\nGET /storefront/subscriptions/get/{author}/{subscriptionid} (author: string, subscriptionid: string, enrich?: boolean) -> The customer's subscriptions\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/update-subscription`"}},"/storefront/verify-payment/{provider}/{configId}/{paymentId}":{"get":{"operationId":"StorefrontController_verifyPayment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"provider","in":"path","required":true,"description":"Payment provider.","schema":{"type":"string"},"example":"stripe"},{"name":"configId","in":"path","required":true,"description":"Which configured gateway instance to verify against.","schema":{"type":"string"},"example":"gw_live_1"},{"name":"paymentId","in":"path","required":true,"description":"The provider's payment identifier.","schema":{"type":"string"},"example":"pi_3PabcXYZ"}],"responses":{"200":{"description":"The verification result from the provider","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"verified":{"type":"boolean","example":true},"status":{"type":"string","example":"succeeded"},"amount":{"type":"number","example":129.99}}}}}},"400":{"description":"The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The payment gateway rejected the request.","path":"/storefront/verify-payment/{provider}/{configId}/{paymentId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"summary":"Verify a payment with the provider","description":"Asks the provider directly whether a payment succeeded, rather than trusting the client. Use it to confirm a redirect-based payment when the customer returns to your site.\n\n#### Signature\n\n```http\nGET /storefront/verify-payment/{provider}/{configId}/{paymentId} (provider: string, configId: string, paymentId: string) -> The verification result from the provider\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Anonymous in the code as it stands: StorefrontController is `@PublicRoute()` at class level, and the handler's `@Roles(User)` is never checked because the guard returns early for public routes.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |\n\nPlus the standard platform errors: `429`, `500`."}},"/storefront/stripe/intent":{"post":{"operationId":"StorefrontController_stripePaymentIntent","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The PaymentIntent, including `client_secret`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","example":"pi_3PabcXYZ"},"client_secret":{"type":"string","description":"Pass to the browser SDK. Never log it."},"status":{"type":"string","example":"requires_payment_method"}}}}}},"400":{"description":"The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The payment gateway rejected the request.","path":"/storefront/stripe/intent","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"summary":"Create a Stripe PaymentIntent","description":"Creates an online (card-not-present) PaymentIntent and returns its client secret for the browser Stripe SDK to confirm.\n\n#### Signature\n\n```http\nPOST /storefront/stripe/intent (body) -> The PaymentIntent, including `client_secret`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/stripe/capture`","requestBody":{"description":"Intent details.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Amount in the currency's major unit.","example":129.99},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"orderId":{"type":"string","description":"Order to associate the intent with."}}},"example":{"amount":129.99,"currency":"USD","email":"ada@example.com"}}}}}},"/storefront/stripe/intent/check":{"post":{"operationId":"StorefrontController_stripePaymentIntentCheck","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/stripe/terminal/connection-token":{"post":{"operationId":"StorefrontController_stripeTerminalConnectionToken","summary":"Get a Stripe Terminal connection token","description":"Returns a single-use token that the Terminal SDK uses to initialise a card reader (BLE M2, WisePOS, …).\n\nThe token rotates on every call — fetch a fresh one each time the SDK asks, and never cache it.\n\n#### Signature\n\n```http\nPOST /storefront/stripe/terminal/connection-token () -> A single-use connection token\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/stripe/terminal/intent`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"A single-use connection token","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"string","description":"Hand straight to the Terminal SDK."}}}}}},"400":{"description":"The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The payment gateway rejected the request.","path":"/storefront/stripe/terminal/connection-token","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"]}},"/storefront/stripe/terminal/location/ensure":{"post":{"operationId":"StorefrontController_stripeTerminalEnsureLocation","summary":"Find or create a Stripe Terminal location","description":"Maps one of your business locations onto a Stripe Terminal Location, creating it if it does not exist yet. The client sends only `businessLocationId`; the server reads the authoritative title and address from the location record, so Stripe never receives address data typed on a device.\n\nIf the location record is missing address fields Stripe requires, the request is refused with a message naming what to fix rather than creating a half-configured Location.\n\n#### Signature\n\n```http\nPOST /storefront/stripe/terminal/location/ensure (body) -> The existing or newly created Stripe Terminal Location\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Safe to call repeatedly — an existing matching Location is returned rather than duplicated.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | LOCATION_INCOMPLETE | Location is missing required address fields | The business location record lacks an address field Stripe requires. | Complete the address on the location record — the error names the missing fields — then retry. |\n| `404` | LOCATION_NOT_FOUND | Business location not found | `businessLocationId` does not resolve in the org. | Check the location id. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/stripe/terminal/connection-token`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Which business location to map.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["businessLocationId"],"properties":{"businessLocationId":{"type":"string","description":"Your location record id.","example":"loc_downtown"}}},"example":{"businessLocationId":"loc_downtown"}}}},"responses":{"201":{"description":"The existing or newly created Stripe Terminal Location","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","example":"tml_Fabc123"},"display_name":{"type":"string","example":"Downtown"}}}}}},"400":{"description":"Location is missing required address fields — The business location record lacks an address field Stripe requires.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Location is missing required address fields","path":"/storefront/stripe/terminal/location/ensure","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Business location not found — `businessLocationId` does not resolve in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Business location not found","path":"/storefront/stripe/terminal/location/ensure","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"]}},"/storefront/stripe/terminal/intent":{"post":{"operationId":"StorefrontController_stripeTerminalIntent","summary":"Create a card-present PaymentIntent","description":"Creates a PaymentIntent restricted to `card_present`, for a physical reader driven by the Terminal SDK.\n\nSet `captureMethod: \"manual\"` to authorise now and capture later — the tip-adjustment flow — then complete it with `POST /storefront/stripe/capture`.\n\n#### Signature\n\n```http\nPOST /storefront/stripe/terminal/intent (body) -> The card-present PaymentIntent\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/stripe/capture`\n- `POST /storefront/pos/tab/{id}/settle`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Card-present intent details.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","example":25.92},"currency":{"type":"string","example":"USD"},"orderId":{"type":"string","description":"POS tab or order this payment belongs to.","example":"66f1a2b3c4d5e6f708192a3b"},"email":{"type":"string","example":"ada@example.com"},"captureMethod":{"type":"string","enum":["automatic","manual"],"default":"automatic","description":"`manual` authorises now and captures later, which is what tip adjustment needs.","example":"manual"}}},"examples":{"immediate":{"summary":"Capture immediately","value":{"amount":25.92,"currency":"USD","orderId":"66f1a2b3c4d5e6f708192a3b"}},"authorizeOnly":{"summary":"Authorise for later capture","description":"Use with `stripe/capture` once the tip is known.","value":{"amount":25.92,"currency":"USD","captureMethod":"manual"}}}}}},"responses":{"201":{"description":"The card-present PaymentIntent","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The payment gateway rejected the request.","path":"/storefront/stripe/terminal/intent","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"]}},"/storefront/stripe/capture":{"post":{"operationId":"StorefrontController_stripeCapture","summary":"Capture an authorized PaymentIntent","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Which intent to capture, and how much.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentIntentId"],"properties":{"paymentIntentId":{"type":"string","description":"The authorised PaymentIntent.","example":"pi_3PabcXYZ"},"amount":{"type":"number","description":"Amount to capture. Defaults to the full authorised amount.","example":28.92}}},"examples":{"full":{"summary":"Capture the full authorisation","value":{"paymentIntentId":"pi_3PabcXYZ"}},"withTip":{"summary":"Capture including a tip","value":{"paymentIntentId":"pi_3PabcXYZ","amount":28.92}}}}}},"responses":{"201":{"description":"The captured PaymentIntent","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"PaymentIntent is not in a capturable state — The intent was created with automatic capture, was already captured, or has expired.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"PaymentIntent is not in a capturable state","path":"/storefront/stripe/capture","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"description":"Captures a PaymentIntent that was created with `captureMethod: \"manual\"`. Pass `amount` to capture less than was authorised, or more where the gateway permits it — this is how a tip added after the card is presented gets charged.\n\n#### Signature\n\n```http\nPOST /storefront/stripe/capture (body) -> The captured PaymentIntent\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_CAPTURABLE | PaymentIntent is not in a capturable state | The intent was created with automatic capture, was already captured, or has expired. | Only intents created with `captureMethod: \"manual\"` and still authorised can be captured. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/stripe/terminal/intent`"}},"/storefront/stripe/checkout-session":{"post":{"operationId":"StorefrontController_stripeCheckSession","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The session, including the redirect URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","example":"cs_test_abc"},"url":{"type":"string","description":"Redirect the customer here."}}}}}},"400":{"description":"The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The payment gateway rejected the request.","path":"/storefront/stripe/checkout-session","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"summary":"Create a Stripe Checkout session","description":"Creates a hosted Stripe Checkout session for a one-off purchase and returns the URL to redirect the customer to.\n\n#### Signature\n\n```http\nPOST /storefront/stripe/checkout-session (body) -> The session, including the redirect URL\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Confirm the outcome with `GET /storefront/verify-payment/...` when the customer returns — do not trust the redirect alone.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/subscribe`","requestBody":{"description":"Session details.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"image":{"type":"string"},"options":{"type":"string","description":"Selected variant options.","example":"size:330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}},"description":"Lines to bill."},"successUrl":{"type":"string","description":"Where Stripe returns the customer on success.","example":"https://shop.example.com/thanks"},"cancelUrl":{"type":"string","description":"Where Stripe returns the customer on cancellation.","example":"https://shop.example.com/cart"},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"}}},"example":{"items":[{"sku":"DRK-COLA-330","quantity":2,"price":12}],"successUrl":"https://shop.example.com/thanks","cancelUrl":"https://shop.example.com/cart","currency":"USD"}}}}}},"/storefront/squad/start":{"post":{"operationId":"StorefrontController_squadStart","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/paypal/config":{"get":{"operationId":"StorefrontController_paypalConfig","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Public PayPal fields, or an empty body","content":{"application/json":{"schema":{"type":"object","properties":{"sk":{"type":"string"},"configured":{"type":"boolean"},"data":{"type":"object","properties":{"provider":{"type":"string","example":"PayPalProvider"},"clientId":{"type":"string"},"sandbox":{"type":"boolean"}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"summary":"Get the PayPal configuration","description":"What the browser PayPal SDK needs for this org: the public fields of its active PayPal integration only — `data.provider`, `data.clientId`, `data.sandbox` — plus `configured` (false when the app secret is missing, so the button should not be offered). Credentials never leave the server. With no active PayPal config the response is an empty 200.\n\n#### Signature\n\n```http\nGET /storefront/paypal/config () -> Public PayPal fields, or an empty body\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Prefer `GET /storefront/payment-gateways`, which returns only the public fields of each gateway including PayPal's `clientId` and `sandbox`.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/payment-gateways`"}},"/storefront/payments/charge-link":{"post":{"operationId":"StorefrontController_createChargeLink","summary":"Create a standalone charge and its payment link","description":"A charge with no invoice behind it: writes a pending `sf_transaction` (type `charge`, source `take-payment`) for `amount` and returns the URL the customer pays at — the site's Payment page with `?ref=<id>`, which is also what the QR encodes. `url` is null, with a `reason`, when the site has no Payment page configured (Site Config › Site Features).\n\n#### Signature\n\n```http\nPOST /storefront/payments/charge-link (body) -> The charge and its link\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Anonymous: StorefrontController is `@PublicRoute()` at class level and this handler does not override it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | AMOUNT_REQUIRED | An amount greater than zero is required | `amount` is missing, not a number, or not positive. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/payments/charge-link/{id}/send`\n- `GET /storefront/payments/charge-link/{id}/status`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The charge and its link","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string","description":"Same as id."},"amount":{"type":"number"},"currency":{"type":"string"},"url":{"type":"string","nullable":true,"example":"https://shop.example.com/pay?ref=66f1a2b3c4d5"},"reason":{"type":"string"}}}}}},"400":{"description":"An amount greater than zero is required — `amount` is missing, not a number, or not positive.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"An amount greater than zero is required","path":"/storefront/payments/charge-link","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","example":45},"currency":{"type":"string","default":"USD"},"description":{"type":"string","example":"Deposit for event booking"},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}}},"example":{"amount":45,"currency":"USD","description":"Deposit for event booking","name":"Ada Lovelace","email":"ada@example.com"}}}}}},"/storefront/payments/charge-link/{id}/send":{"post":{"operationId":"StorefrontController_sendChargeLink","summary":"Send a charge's payment link","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Charge id (`sf_transaction` sk) from POST /storefront/payments/charge-link."}],"responses":{"201":{"description":"Channels sent and the link","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"array","items":{"type":"string"}},"url":{"type":"string","nullable":true}}}}}},"400":{"description":"No Payment page is configured on the site — set one in Site Config > Site Features. — The site has no Payment page.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"No Payment page is configured on the site — set one in Site Config > Site Features.","path":"/storefront/payments/charge-link/{id}/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Charge not found — No transaction with that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Charge not found","path":"/storefront/payments/charge-link/{id}/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"description":"Emails and/or texts the charge's payment link (the same URL the QR encodes) with the `payment-request` / `payment-request-sms` templates. Addresses default to the ones given when the charge was created; `channels` defaults to every channel with an address.\n\n#### Signature\n\n```http\nPOST /storefront/payments/charge-link/{id}/send (id: string, body) -> Channels sent and the link\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Anonymous: StorefrontController is `@PublicRoute()` at class level and this handler does not override it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CHARGE_NOT_FOUND | Charge not found | No transaction with that id. | — |\n| `400` | NO_PAYMENT_PAGE | No Payment page is configured on the site — set one in Site Config > Site Features. | The site has no Payment page. | — |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"channels":{"type":"array","items":{"type":"string","enum":["email","sms"]}}}},"example":{"phone":"+15555550123","channels":["sms"]}}}}}},"/storefront/payments/charge-link/{id}/withdraw":{"post":{"operationId":"StorefrontController_withdrawChargeLink","summary":"Withdraw a charge's payment link","description":"Takes a pending payment request back: any card form the customer has open is cancelled at the gateway, and the link stops accepting payment (the pay page and the record step both refuse it). Refused when the customer has already paid.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/payments/charge-link/{id}/apply-deposit":{"post":{"operationId":"StorefrontController_applyDeposit","summary":"Apply a customer deposit to an invoice","description":"For a paid payment request booked as a customer deposit (Books › Posting choices). Body: { invoice: number, amount? }. The invoice must be issued and for the same customer (customer id or email). Records a \"deposit\" payment on the invoice and books Dr Customer Deposits / Cr Accounts Receivable. Defaults to the lesser of what is left on the deposit and what the invoice owes.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/payments/charge-link/{id}/status":{"get":{"operationId":"StorefrontController_chargeLinkStatus","summary":"Has a charge been paid","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Charge id."}],"responses":{"200":{"description":"Payment state","content":{"application/json":{"schema":{"type":"object","properties":{"paid":{"type":"boolean"},"amount":{"type":"number"},"currency":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string","example":"pending"}}}}}},"404":{"description":"Charge not found — No transaction with that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Charge not found","path":"/storefront/payments/charge-link/{id}/status","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"description":"Polled by the till while the customer pays on their own device. `paid` is true once the transaction status is paid, succeeded or completed.\n\n#### Signature\n\n```http\nGET /storefront/payments/charge-link/{id}/status (id: string) -> Payment state\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CHARGE_NOT_FOUND | Charge not found | No transaction with that id. | — |\n\nPlus the standard platform errors: `429`, `500`."}},"/storefront/payment-gateways":{"get":{"operationId":"StorefrontController_listPaymentGateways","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"amount","required":false,"in":"query","schema":{"type":"string"},"description":"With `currency`: create a Stripe PaymentIntent for this amount.","example":"129.99"},{"name":"currency","required":false,"in":"query","schema":{"type":"string"},"description":"With `amount`.","example":"USD"},{"name":"email","required":false,"in":"query","schema":{"type":"string"},"description":"Customer email for the eager Stripe intent.","example":"ada@example.com"}],"responses":{"200":{"description":"The gateways, public fields only","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"sk":{"type":"string"},"name":{"type":"string"},"datatype":{"type":"string","example":"config"},"configured":{"type":"boolean"},"data":{"type":"object","additionalProperties":true,"properties":{"provider":{"type":"string","example":"StripeProvider"},"name":{"type":"string"},"publishableKey":{"type":"string"},"clientId":{"type":"string"},"sandbox":{"type":"boolean"},"testMode":{"type":"boolean"},"instructions":{"type":"string"}}},"payIntent":{"type":"object","description":"Stripe only, when amount + currency were given.","properties":{"id":{"type":"string"},"client_secret":{"type":"string"},"publishableKey":{"type":"string"}}}}}},"example":[{"sk":"66f1…","name":"default","datatype":"config","configured":true,"data":{"provider":"StripeProvider","name":"default","publishableKey":"pk_live_…"},"payIntent":{"id":"pi_3Pab…","client_secret":"pi_3Pab…_secret_…","publishableKey":"pk_live_…"}}]}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"summary":"List available payment gateways","description":"The org's configured, **active** gateways from Stripe, PayPal, Offline, Gift card and Account balance (the `default` config of each), in that order — build the payment selector from this rather than hard-coding options.\n\nWhen `amount` and `currency` are both given, a Stripe PaymentIntent is created up front and attached to the Stripe entry as `payIntent`, so the client can mount Stripe Elements without a second round-trip. `email` is passed to that intent.\n\n**Only the public view of each gateway is returned**: `sk`, `name`, `datatype`, `configured` and `data` limited to presentation and client-SDK fields (`name`, `provider`, `type`, `status`, `displayName`, `description`, `clientId`, `publishableKey`, `publicKey`, `clientToken`, `testMode`, `sandbox`, `default`, `merchantName`, `supportedMethods`, `instructions`, `bankDetails`). Secret keys, API keys and webhook secrets never leave the server. `configured` is false when the gateway is missing a credential it needs to take money (Stripe secret + publishable key, PayPal app secret + client id).\n\n#### Signature\n\n```http\nGET /storefront/payment-gateways (amount?: string, currency?: string, email?: string) -> The gateways, public fields only\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A gateway that errors while loading is skipped (logged), not returned as an error.\n- Inactive or deprecated gateway configs are never listed.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/take-payment`\n- `GET /storefront/paypal/config`\n- `POST /storefront/stripe/intent`"}},"/storefront/take-payment":{"post":{"operationId":"StorefrontController_takePayment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The payment result, including the reference to pass as `paymentRef`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The payment gateway rejected the request.","path":"/storefront/take-payment","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Payments"],"summary":"Take a payment","description":"Charges the customer through the configured gateway and returns the payment result. Use the returned reference as `paymentRef` when creating the order.\n\n#### Signature\n\n```http\nPOST /storefront/take-payment (body) -> The payment result, including the reference to pass as `paymentRef`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Not idempotent. A retry charges again — capture the reference from the first response before retrying.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/checkout-cart`\n- `GET /storefront/payment-gateways`","requestBody":{"description":"Payment details.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Amount to charge.","example":129.99},"currency":{"type":"string","example":"USD"},"gateway":{"type":"string","description":"Which configured gateway to charge through.","example":"stripe"},"paymentMethod":{"type":"string","description":"Gateway payment-method token.","example":"pm_1PabcXYZ"},"email":{"type":"string","example":"ada@example.com"},"orderId":{"type":"string","description":"Order this payment belongs to, when it already exists."}}},"example":{"amount":129.99,"currency":"USD","gateway":"stripe","paymentMethod":"pm_1PabcXYZ","email":"ada@example.com"}}}}}},"/storefront/admin/order/quote":{"post":{"operationId":"StorefrontController_adminOrderQuote","summary":"Staff: price an order for a customer — the shop checkout cart calculation, run as that customer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/admin/order":{"post":{"operationId":"StorefrontController_adminPlaceOrder","summary":"Staff: place an order for a customer — the shop checkout, with who placed it recorded","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront"]}},"/storefront/checkout-cart":{"post":{"operationId":"StorefrontController_checkoutCart","summary":"Check out a cart","description":"Converts a cart into an order: creates the `sf_order`, records the payment reference, and triggers the order-confirmation notification.\n\nThis is the standard product-only checkout. Use `checkout-mixed` when the basket contains rentals.\n\n#### Signature\n\n```http\nPOST /storefront/checkout-cart (body) -> The created order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Payment is expected to have been taken already — pass its reference in `paymentRef`. Take the payment with `POST /storefront/take-payment` or a Stripe intent first.\n- Not idempotent: calling it twice creates two orders. Guard against double submission on the client.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/checkout-mixed`\n- `POST /storefront/take-payment`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Checkout details — contents, addresses, and the payment already taken.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"image":{"type":"string"},"options":{"type":"string","description":"Selected variant options.","example":"size:330ml"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}},"description":"Lines to order."},"cartId":{"type":"string","description":"Cart being checked out.","example":"cart_9f21"},"email":{"type":"string","description":"Customer email. Where the confirmation is sent.","example":"ada@example.com"},"name":{"type":"string","example":"Ada Lovelace"},"phone":{"type":"string","example":"+442071234567"},"shippingAddress":{"type":"object","description":"A postal address.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"line1":{"type":"string","example":"12 Ada Way"},"line2":{"type":"string"},"city":{"type":"string","example":"London"},"state":{"type":"string"},"postcode":{"type":"string","example":"E1 6AN"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"GB"},"phone":{"type":"string","example":"+442071234567"}}},"billingAddress":{"type":"object","description":"A postal address.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"line1":{"type":"string","example":"12 Ada Way"},"line2":{"type":"string"},"city":{"type":"string","example":"London"},"state":{"type":"string"},"postcode":{"type":"string","example":"E1 6AN"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"GB"},"phone":{"type":"string","example":"+442071234567"}}},"shippingMethod":{"type":"string","example":"ground"},"shippingFee":{"type":"number","example":4.99},"tax":{"type":"number","example":1.92},"discounts":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"number","example":30.91},"currency":{"type":"string","example":"USD"},"paymentRef":{"type":"string","description":"Reference for the payment already captured.","example":"pi_3PabcXYZ"},"paymentGateway":{"type":"string","example":"stripe"}}},"example":{"items":[{"sku":"DRK-COLA-330","quantity":2,"price":12}],"email":"ada@example.com","shippingAddress":{"name":"Ada Lovelace","line1":"12 Ada Way","city":"London","postcode":"E1 6AN","country":"GB"},"total":30.91,"currency":"USD","paymentRef":"pi_3PabcXYZ","paymentGateway":"stripe"}}}},"responses":{"201":{"description":"The created order","content":{"application/json":{"schema":{"type":"object","description":"The created order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Checkout"]}},"/storefront/checkout-mixed":{"post":{"operationId":"StorefrontController_checkoutMixed","summary":"Check out a basket of products and rentals","description":"Checks out a basket containing both ordinary products and rental items. The two are routed differently: products become lines on a standard order, while rentals are created as **separate rental bookings** with their own dates and availability rules.\n\nEach line declares which it is via `itemType`. Rental lines additionally need `startDate`, `endDate` and `rentalPeriod`. The response carries both the order and the bookings that were created.\n\n#### Signature\n\n```http\nPOST /storefront/checkout-mixed (body) -> The order and the rental bookings created alongside it\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A line with no `itemType` is treated as a product. Rentals must set it explicitly or they will not be booked.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/checkout-cart`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Mixed basket plus checkout details.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["sku"],"properties":{"sku":{"type":"string","description":"Product or rental SKU.","example":"DRK-COLA-330"},"name":{"type":"string"},"image":{"type":"string"},"options":{"type":"string"},"quantity":{"type":"number","example":1},"price":{"type":"number","example":12},"itemType":{"type":"string","enum":["product","rental"],"description":"Routes the line. `rental` items are booked separately from the order and need the date fields below.","example":"product"},"startDate":{"type":"string","format":"date-time","description":"Rental start. Required for `rental` lines.","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","description":"Rental end. Required for `rental` lines.","example":"2026-09-04T17:00:00.000Z"},"rentalPeriod":{"type":"string","enum":["hourly","daily","weekly","monthly"],"description":"Billing granularity for the rental.","example":"daily"},"optionalFees":{"type":"array","items":{"type":"string"},"description":"Selected optional fees, e.g. insurance."}}},"description":"Products and rentals together. `itemType` routes each line."},"total":{"type":"number","example":189.99},"shippingAddress":{"type":"object","description":"A postal address.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"line1":{"type":"string","example":"12 Ada Way"},"line2":{"type":"string"},"city":{"type":"string","example":"London"},"state":{"type":"string"},"postcode":{"type":"string","example":"E1 6AN"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"GB"},"phone":{"type":"string","example":"+442071234567"}}},"billingAddress":{"type":"object","description":"A postal address.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"line1":{"type":"string","example":"12 Ada Way"},"line2":{"type":"string"},"city":{"type":"string","example":"London"},"state":{"type":"string"},"postcode":{"type":"string","example":"E1 6AN"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"GB"},"phone":{"type":"string","example":"+442071234567"}}},"paymentRef":{"type":"string","example":"pi_3PabcXYZ"},"paymentGateway":{"type":"string","example":"stripe"},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"name":{"type":"string","example":"Ada Lovelace"},"phone":{"type":"string"},"shippingMethod":{"type":"string","example":"ground"},"shippingFee":{"type":"number","example":4.99},"discounts":{"type":"array","items":{"type":"object","additionalProperties":true}},"tax":{"type":"number","example":12}}},"examples":{"mixed":{"summary":"One product and one rental","value":{"items":[{"sku":"DRK-COLA-330","quantity":2,"price":12,"itemType":"product"},{"sku":"CAM-RED-KOMODO","quantity":1,"price":165.99,"itemType":"rental","startDate":"2026-09-01T09:00:00.000Z","endDate":"2026-09-04T17:00:00.000Z","rentalPeriod":"daily"}],"email":"ada@example.com","total":189.99,"currency":"USD","paymentRef":"pi_3PabcXYZ","paymentGateway":"stripe"}}}}}},"responses":{"201":{"description":"The order and the rental bookings created alongside it","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","description":"The created order (`sf_order`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}},"rentals":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"One booking per rental line."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Checkout"]}},"/storefront/update-subscription":{"post":{"operationId":"StorefrontController_subscriptionUpdate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The subscription with `allowedActions` and `nextBoundary`","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"400":{"description":"A subscription plan is required — No `plan` (or `productId`) given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A subscription plan is required","path":"/storefront/update-subscription","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"The first payment was refused — The payment provider refused the charge for a paid plan.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"The first payment was refused","path":"/storefront/update-subscription","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Subscription plan … not found — No `sf_subscription_plan` by that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription plan … not found","path":"/storefront/update-subscription","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/update-subscription","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Subscribe, pay, renew or change plan (site entry point)","description":"The entry point sites use. Same engine as the `storefront/subscriptions/*` routes:\n- without `number` it subscribes (see `POST /storefront/subscriptions/subscribe`) — a plan priced 0 is active at once, no payment step;\n- with `number` and a `transaction` it records that payment (activates a new one, ends a trial, clears past_due, or pays the next period);\n- with `number` and a different `products[0].plan` it changes plan now;\n- with `number` alone it renews.\n\nPrices always come from the plan record; a price in the request is ignored. A signed-in shopper subscribes themselves (their own email); staff subscribe the customer named by `email`. To cancel, pause or resume use the `storefront/subscriptions/{id}/…` routes.\n\n#### Signature\n\n```http\nPOST /storefront/update-subscription (body) -> The subscription with `allowedActions` and `nextBoundary`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SUBSCRIPTION_PLAN_REQUIRED | A subscription plan is required | No `plan` (or `productId`) given. | — |\n| `404` | SUBSCRIPTION_PLAN_NOT_FOUND | Subscription plan … not found | No `sf_subscription_plan` by that name. | — |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n| `402` | SUBSCRIPTION_PAYMENT_FAILED | The first payment was refused | The payment provider refused the charge for a paid plan. | Use another card, or a free plan. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/subscribe`\n- `GET /storefront/subscriptions/{id}`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","description":"One entry naming the plan.","items":{"type":"object","properties":{"plan":{"type":"string","example":"pro-monthly"}}}},"email":{"type":"string","description":"Subscriber (staff calls). A shopper session uses its own email.","example":"ada@example.com"},"number":{"type":"string","description":"Existing subscription number, to pay / renew / change it.","example":"K7Q2M9XWA"},"transaction":{"type":"object","description":"A payment already taken: `{ ref, gateway, amount }`.","additionalProperties":true},"isTrial":{"type":"boolean","description":"`false` skips the plan's trial."}}},"examples":{"subscribeFree":{"summary":"Subscribe to a free plan","value":{"products":[{"plan":"newsletter-free"}],"email":"ada@example.com"}},"changePlan":{"summary":"Move to another plan","value":{"number":"K7Q2M9XWA","products":[{"plan":"pro-annual"}]}},"pay":{"summary":"Apply a payment","value":{"number":"K7Q2M9XWA","transaction":{"ref":"pi_123","gateway":"stripe","amount":20}}}}}}}}},"/storefront/sync/partners":{"get":{"operationId":"StorefrontController_getShoppingPartners","summary":"List shopping partners","description":"Returns the marketplace and shopping partners available for product sync, with each one's connection state for this org. Use it to build a sync UI rather than hard-coding the partner list.\n\n#### Signature\n\n```http\nGET /storefront/sync/partners (configId?: string) -> The available partners and their connection state\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/{partner}/{productId}`\n- `POST /storefront/sync/add-products`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"configId","required":false,"in":"query","schema":{"type":"string","default":"default"},"description":"Which configured connection to the partner to use. An org can hold several connections to one partner — separate Google Merchant accounts, for instance. Omit to use the connection named `default`.","example":"default"}],"responses":{"200":{"description":"The available partners and their connection state","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Partner identifier to pass as `partner`.","example":"google"},"name":{"type":"string","example":"Google Merchant Center"},"connected":{"type":"boolean","description":"Whether this org has a working connection.","example":true},"configId":{"type":"string","example":"default"}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]}},"/storefront/sync/partners/{partner}/choices":{"get":{"operationId":"StorefrontController_getPartnerChoices","summary":"Choices for a partner setup step","description":"A setup step can be a choice from the partner's own list — for Google, the Merchant Center account to send products to. `GET /storefront/sync/partners` marks that step with `pick`; this call reads its choices from the partner now. When there is exactly one choice it is saved straight away (`saved: true`).\n\n#### Signature\n\n```http\nGET /storefront/sync/partners/{partner}/choices (partner: string, configId?: string) -> The step and its choices\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/partners/{partner}/choose`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"partner","required":true,"in":"path","description":"Partner identifier, e.g. `google`, `facebook`, `tiktok`, `amazon`, `shopify`. List the supported values with `GET /storefront/sync/partners`.","schema":{"type":"string"},"example":"google"},{"name":"configId","required":false,"in":"query","schema":{"type":"string","default":"default"},"description":"Which configured connection to the partner to use. An org can hold several connections to one partner — separate Google Merchant accounts, for instance. Omit to use the connection named `default`.","example":"default"}],"responses":{"200":{"description":"The step and its choices","content":{"application/json":{"schema":{"type":"object","properties":{"field":{"type":"string","description":"The connection field the choice is saved to.","example":"merchantId"},"label":{"type":"string","example":"Choose your Merchant Center account"},"choices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"123456789"},"name":{"type":"string","example":"My Store"}}}},"value":{"type":"string","nullable":true,"description":"The id chosen now, or null.","example":"123456789"},"saved":{"type":"boolean","description":"True when the only choice was just saved."},"message":{"type":"string","description":"What to do when the partner lists no choices."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]}},"/storefront/sync/partners/{partner}/choose":{"post":{"operationId":"StorefrontController_choosePartnerValue","summary":"Choose for a partner setup step","description":"Saves the choice for the partner's pick step on its connection. The value must be one of the choices the partner lists now.\n\n#### Signature\n\n```http\nPOST /storefront/sync/partners/{partner}/choose (partner: string, body) -> The choice and the setup as it now stands\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/sync/partners/{partner}/choices`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"partner","required":true,"in":"path","description":"Partner identifier, e.g. `google`, `facebook`, `tiktok`, `amazon`, `shopify`. List the supported values with `GET /storefront/sync/partners`.","schema":{"type":"string"},"example":"google"}],"responses":{"201":{"description":"The choice and the setup as it now stands","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"],"requestBody":{"description":"The chosen id.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"type":"string","example":"123456789"},"configId":{"type":"string","example":"default"}}}}}}}},"/storefront/sync/{partner}/{productId}":{"post":{"operationId":"StorefrontController_syncProduct","summary":"Sync one product to a partner","description":"Pushes a single product to one marketplace, creating or updating its listing. This is the call to make right after a product is edited, so the marketplace copy does not drift.\n\n#### Signature\n\n```http\nPOST /storefront/sync/{partner}/{productId} (partner: string, productId: string, configId?: string) -> The sync result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Safe to repeat — a product already listed is updated rather than duplicated.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRODUCT_NOT_FOUND | Product not found | The product id or SK does not resolve in the org. | Check the identifier with `GET /storefront/products`. |\n| `400` | PARTNER_API_ERROR | The partner rejected the request. | The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential. | The partner's message is passed through. Fix the reported problem, or re-authorise the connection if the credential expired. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/all/{productId}`\n- `DELETE /storefront/sync/{partner}/{productId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"partner","required":true,"in":"path","description":"Partner identifier, e.g. `google`, `facebook`, `tiktok`, `amazon`, `shopify`. List the supported values with `GET /storefront/sync/partners`.","schema":{"type":"string"},"example":"google"},{"name":"productId","required":true,"in":"path","description":"Product `sk` or id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"configId","required":false,"in":"query","schema":{"type":"string","default":"default"},"description":"Which configured connection to the partner to use. An org can hold several connections to one partner — separate Google Merchant accounts, for instance. Omit to use the connection named `default`.","example":"default"}],"responses":{"201":{"description":"The sync result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Outcome of the sync, per product.","properties":{"success":{"type":"boolean","example":true},"partner":{"type":"string","example":"google"},"results":{"type":"array","description":"One entry per product. Individual failures are reported here rather than failing the whole request.","items":{"type":"object","properties":{"productId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"},"sku":{"type":"string","example":"DRK-COLA-330"},"status":{"type":"string","description":"`synced`, `failed`, or `skipped`.","example":"synced"},"message":{"type":"string","description":"Partner-reported detail when the line did not succeed."}}}}}}}}},"400":{"description":"The partner rejected the request. — The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The partner rejected the request.","path":"/storefront/sync/{partner}/{productId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Product not found — The product id or SK does not resolve in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Product not found","path":"/storefront/sync/{partner}/{productId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]},"delete":{"operationId":"StorefrontController_deleteProduct","summary":"Remove a product from a partner","description":"Delists a single product from one marketplace. The product itself is untouched in your catalog — only the partner's copy is removed.\n\n#### Signature\n\n```http\nDELETE /storefront/sync/{partner}/{productId} (partner: string, productId: string, configId?: string) -> The delist result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Deleting a product that is not listed is not treated as an error by most partners.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PARTNER_NOT_CONFIGURED | Partner integration not found for this organization | The org has no connection to that partner, or none under the given `configId`. | Connect the partner first. `GET /storefront/sync/partners` lists what is configured. |\n| `400` | PARTNER_API_ERROR | The partner rejected the request. | The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential. | The partner's message is passed through. Fix the reported problem, or re-authorise the connection if the credential expired. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/delete-products`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"partner","required":true,"in":"path","description":"Partner identifier, e.g. `google`, `facebook`, `tiktok`, `amazon`, `shopify`. List the supported values with `GET /storefront/sync/partners`.","schema":{"type":"string"},"example":"google"},{"name":"productId","required":true,"in":"path","description":"Product id as known to the partner, or the local `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"configId","required":false,"in":"query","schema":{"type":"string","default":"default"},"description":"Which configured connection to the partner to use. An org can hold several connections to one partner — separate Google Merchant accounts, for instance. Omit to use the connection named `default`.","example":"default"}],"responses":{"200":{"description":"The delist result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Outcome of the sync, per product.","properties":{"success":{"type":"boolean","example":true},"partner":{"type":"string","example":"google"},"results":{"type":"array","description":"One entry per product. Individual failures are reported here rather than failing the whole request.","items":{"type":"object","properties":{"productId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"},"sku":{"type":"string","example":"DRK-COLA-330"},"status":{"type":"string","description":"`synced`, `failed`, or `skipped`.","example":"synced"},"message":{"type":"string","description":"Partner-reported detail when the line did not succeed."}}}}}}}}},"400":{"description":"The partner rejected the request. — The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The partner rejected the request.","path":"/storefront/sync/{partner}/{productId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Partner integration not found for this organization — The org has no connection to that partner, or none under the given `configId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Partner integration not found for this organization","path":"/storefront/sync/{partner}/{productId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]}},"/storefront/sync/all/{productId}":{"post":{"operationId":"StorefrontController_syncProductToAll","summary":"Sync one product to every partner","description":"Pushes a product to every partner the org has configured, in one call. Partners are attempted independently — one marketplace rejecting the product does not stop the others.\n\n#### Signature\n\n```http\nPOST /storefront/sync/all/{productId} (productId: string) -> One result per configured partner\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Check every entry in the response: a `200` here means the request ran, not that every partner accepted the product.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRODUCT_NOT_FOUND | Product not found | The product id or SK does not resolve in the org. | Check the identifier with `GET /storefront/products`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/{partner}/{productId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"productId","required":true,"in":"path","description":"Product `sk` or id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"One result per configured partner","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Outcome of the sync, per product.","properties":{"success":{"type":"boolean","example":true},"partner":{"type":"string","example":"google"},"results":{"type":"array","description":"One entry per product. Individual failures are reported here rather than failing the whole request.","items":{"type":"object","properties":{"productId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"},"sku":{"type":"string","example":"DRK-COLA-330"},"status":{"type":"string","description":"`synced`, `failed`, or `skipped`.","example":"synced"},"message":{"type":"string","description":"Partner-reported detail when the line did not succeed."}}}}}}}}}},"404":{"description":"Product not found — The product id or SK does not resolve in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Product not found","path":"/storefront/sync/all/{productId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]}},"/storefront/sync/add-products":{"post":{"operationId":"StorefrontController_syncServiceAdd","summary":"Sync several products to a partner","description":"Bulk version of the single-product sync: pushes many products to one marketplace in a single call.\n\nSet `alsoPostToSocial` to publish a social post for the same products as part of the operation, configured through `postOptions`. That is a convenience over calling `sync/post-to-social` separately, and it uses the same rendering.\n\n#### Signature\n\n```http\nPOST /storefront/sync/add-products (body) -> Per-product sync results, plus the social post result when one was requested\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PARTNER_NOT_CONFIGURED | Partner integration not found for this organization | The org has no connection to that partner, or none under the given `configId`. | Connect the partner first. `GET /storefront/sync/partners` lists what is configured. |\n| `400` | PARTNER_API_ERROR | The partner rejected the request. | The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential. | The partner's message is passed through. Fix the reported problem, or re-authorise the connection if the credential expired. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/delete-products`\n- `POST /storefront/sync/post-to-social`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which products to push where.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["partner","productIds"],"properties":{"partner":{"type":"string","description":"Partner identifier.","example":"google"},"productIds":{"type":"array","items":{"type":"string"},"description":"Product `sk` values to sync.","example":["66f1a2b3c4d5e6f708192a3b"]},"configId":{"type":"string","default":"default","description":"Which configured connection to use."},"baseURL":{"type":"string","description":"Base URL for product links. Defaults to the site settings.","example":"https://shop.example.com"},"alsoPostToSocial":{"type":"boolean","default":false,"description":"Also publish a social post for these products.","example":false},"postOptions":{"type":"object","description":"Social post settings. Only read when `alsoPostToSocial` is true.","properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","twitter","linkedin","pinterest"]},"postType":{"type":"string","enum":["image","carousel","video","story","reel"]},"customCaption":{"type":"string"},"customHashtags":{"type":"array","items":{"type":"string"}},"includePrice":{"type":"boolean","default":true},"includeHashtags":{"type":"boolean","default":true},"scheduleAt":{"type":"string","format":"date-time","description":"Publish later instead of now."}}}}},"examples":{"bulk":{"summary":"Sync three products to Google","value":{"partner":"google","productIds":["sk_1","sk_2","sk_3"]}},"withSocial":{"summary":"Sync and post to Instagram","value":{"partner":"google","productIds":["sk_1"],"alsoPostToSocial":true,"postOptions":{"platform":"instagram","postType":"image","includePrice":true}}}}}}},"responses":{"201":{"description":"Per-product sync results, plus the social post result when one was requested","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Outcome of the sync, per product.","properties":{"success":{"type":"boolean","example":true},"partner":{"type":"string","example":"google"},"results":{"type":"array","description":"One entry per product. Individual failures are reported here rather than failing the whole request.","items":{"type":"object","properties":{"productId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"},"sku":{"type":"string","example":"DRK-COLA-330"},"status":{"type":"string","description":"`synced`, `failed`, or `skipped`.","example":"synced"},"message":{"type":"string","description":"Partner-reported detail when the line did not succeed."}}}}}}}}},"400":{"description":"The partner rejected the request. — The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The partner rejected the request.","path":"/storefront/sync/add-products","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Partner integration not found for this organization — The org has no connection to that partner, or none under the given `configId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Partner integration not found for this organization","path":"/storefront/sync/add-products","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]}},"/storefront/sync/delete-products":{"post":{"operationId":"StorefrontController_syncServiceDelete","summary":"Remove several products from a partner","description":"Bulk delist: removes many products from one marketplace catalog in a single call. Your own catalog is unaffected.\n\n#### Signature\n\n```http\nPOST /storefront/sync/delete-products (body) -> Per-product delist results\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PARTNER_NOT_CONFIGURED | Partner integration not found for this organization | The org has no connection to that partner, or none under the given `configId`. | Connect the partner first. `GET /storefront/sync/partners` lists what is configured. |\n| `400` | PARTNER_API_ERROR | The partner rejected the request. | The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential. | The partner's message is passed through. Fix the reported problem, or re-authorise the connection if the credential expired. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `DELETE /storefront/sync/{partner}/{productId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which products to remove from where.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["partner","productIds"],"properties":{"partner":{"type":"string","description":"Partner identifier.","example":"google"},"productIds":{"type":"array","items":{"type":"string"},"description":"Product ids to delist.","example":["sk_1","sk_2"]},"configId":{"type":"string","default":"default"},"skus":{"type":"array","items":{"type":"string"},"description":"Optional SKUs, for partners that key their catalog on SKU rather than id.","example":["DRK-COLA-330"]}}},"example":{"partner":"google","productIds":["sk_1","sk_2"]}}}},"responses":{"201":{"description":"Per-product delist results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Outcome of the sync, per product.","properties":{"success":{"type":"boolean","example":true},"partner":{"type":"string","example":"google"},"results":{"type":"array","description":"One entry per product. Individual failures are reported here rather than failing the whole request.","items":{"type":"object","properties":{"productId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"},"sku":{"type":"string","example":"DRK-COLA-330"},"status":{"type":"string","description":"`synced`, `failed`, or `skipped`.","example":"synced"},"message":{"type":"string","description":"Partner-reported detail when the line did not succeed."}}}}}}}}},"400":{"description":"The partner rejected the request. — The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The partner rejected the request.","path":"/storefront/sync/delete-products","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Partner integration not found for this organization — The org has no connection to that partner, or none under the given `configId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Partner integration not found for this organization","path":"/storefront/sync/delete-products","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]}},"/storefront/sync/products":{"get":{"operationId":"StorefrontController_listAllProducts","summary":"List products across all partners","description":"Returns the products currently listed at every configured partner — what the marketplaces think you are selling, which is the thing to compare against your own catalog when reconciling.\n\n**This endpoint takes no parameters.** It accepts neither paging nor a partner filter, and returns whatever each partner's default page size yields. Use `GET /storefront/sync/products/{partner}` when you need `limit`, `pageToken` or `configId`.\n\n#### Signature\n\n```http\nGET /storefront/sync/products () -> Listed products grouped by partner\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unpaged. On a large catalog the result is truncated by each partner's own default page size, with no way to fetch the rest — use the per-partner endpoint for a complete listing.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/sync/products/{partner}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"pageToken","required":false,"in":"query","description":"Page token for pagination","schema":{}},{"name":"limit","required":false,"in":"query","description":"Maximum number of products to return","schema":{}},{"name":"configId","required":false,"in":"query","description":"Config ID (optional)","schema":{}},{"name":"partner","required":false,"in":"path","description":"Partner ID (google, facebook, amazon, shopify, etc.) - optional","schema":{}}],"responses":{"200":{"description":"Listed products grouped by partner","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Keyed by partner id, each holding that partner's listed products."}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"]}},"/storefront/sync/products/{partner}":{"get":{"operationId":"StorefrontController_listPartnerProducts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"partner","required":true,"in":"path","schema":{"type":"string"},"description":"Partner identifier, e.g. `google`, `facebook`, `tiktok`, `amazon`, `shopify`. List the supported values with `GET /storefront/sync/partners`.","example":"google"},{"name":"configId","required":false,"in":"query","schema":{"type":"string","default":"default"},"description":"Which configured connection to the partner to use. An org can hold several connections to one partner — separate Google Merchant accounts, for instance. Omit to use the connection named `default`.","example":"default"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"Maximum products to return. The partner's own maximum still applies.","example":100},{"name":"pageToken","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response. Omit for the first page."}],"responses":{"200":{"description":"A page of listed products, with a token for the next page","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The partner's listing records, in the partner's own shape."},"nextPageToken":{"type":"string","description":"Pass as `pageToken` to continue. Absent on the last page."}}}}}},"400":{"description":"The partner rejected the request. — The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The partner rejected the request.","path":"/storefront/sync/products/{partner}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Partner integration not found for this organization — The org has no connection to that partner, or none under the given `configId`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Partner integration not found for this organization","path":"/storefront/sync/products/{partner}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Sync"],"summary":"List products at one partner","description":"Returns the products currently listed at a single marketplace, with paging. This is the endpoint to use for reconciliation — it is the only listing that can walk a full catalog.\n\nPaging is the partner's own: pass the `pageToken` from the previous response to fetch the next page, and stop when no token comes back.\n\n#### Signature\n\n```http\nGET /storefront/sync/products/{partner} (partner: string, configId?: string, limit?: integer, pageToken?: string) -> A page of listed products, with a token for the next page\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- The product shape is the partner's, not the platform's — fields differ between Google, Facebook and Shopify.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PARTNER_NOT_CONFIGURED | Partner integration not found for this organization | The org has no connection to that partner, or none under the given `configId`. | Connect the partner first. `GET /storefront/sync/partners` lists what is configured. |\n| `400` | PARTNER_API_ERROR | The partner rejected the request. | The marketplace API returned an error — a policy violation, a missing required attribute, or an expired credential. | The partner's message is passed through. Fix the reported problem, or re-authorise the connection if the credential expired. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/sync/products`"}},"/storefront/sync/post-to-social":{"post":{"operationId":"StorefrontController_postToSocial","summary":"Post products to social media","description":"Builds a social post from one or more products and publishes it, or schedules it for later.\n\nThe caption is assembled from the products unless `customCaption` overrides it; price, hashtags and a product link are included by default and can each be switched off. `postType` is auto-detected from the product media when omitted.\n\nPreview the result first with `POST /storefront/sync/preview-social-post` — that runs the same rendering without publishing.\n\n#### Signature\n\n```http\nPOST /storefront/sync/post-to-social (body) -> The published or scheduled post\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRODUCT_NOT_FOUND | Product not found | The product id or SK does not resolve in the org. | Check the identifier with `GET /storefront/products`. |\n| `400` | INVALID_TARGET | Invalid or unreachable post target | `to` is malformed for the platform, or names a page the connection cannot publish to. | Use a `to` value from `GET /storefront/sync/social-targets/{platform}`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/preview-social-post`\n- `GET /storefront/sync/social-targets/{platform}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to post, and where.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","productIds","to","siteName"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","twitter","linkedin","pinterest"],"description":"Target platform.","example":"instagram"},"productIds":{"type":"array","items":{"type":"string"},"description":"Product `sk` values to feature.","example":["66f1a2b3c4d5e6f708192a3b"]},"to":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Destination, in the platform's own format. Take it from `GET /storefront/sync/social-targets/{platform}` rather than building it.","example":"x/1234567890/17841400000000000"},"siteName":{"type":"string","description":"Site whose store URL is used to build product links. Required even when `includeLink` is false.","example":"main-store"},"postType":{"type":"string","enum":["image","carousel","video","story","reel"],"description":"Auto-detected from the product media when omitted.","example":"carousel"},"customCaption":{"type":"string","description":"Replaces the generated caption entirely.","example":"Summer refresh — now 20% off."},"customHashtags":{"type":"array","items":{"type":"string"},"description":"Hashtags to use instead of the generated ones.","example":["summer","sale"]},"includePrice":{"type":"boolean","default":true,"description":"Include the price in the caption."},"includeHashtags":{"type":"boolean","default":true,"description":"Include hashtags."},"includeLink":{"type":"boolean","default":true,"description":"Include a product link."},"scheduleAt":{"type":"string","format":"date-time","description":"Publish at this time instead of immediately.","example":"2026-09-01T09:00:00.000Z"},"configId":{"type":"string","description":"Which configured integration to publish through."}}},"examples":{"single":{"summary":"Post one product to Instagram now","value":{"platform":"instagram","productIds":["66f1a2b3c4d5e6f708192a3b"],"to":"x/1234567890/17841400000000000","siteName":"main-store"}},"scheduledCarousel":{"summary":"Schedule a carousel with a custom caption","value":{"platform":"instagram","productIds":["sk_1","sk_2","sk_3"],"to":"x/1234567890/17841400000000000","siteName":"main-store","postType":"carousel","customCaption":"Summer refresh — now 20% off.","customHashtags":["summer","sale"],"scheduleAt":"2026-09-01T09:00:00.000Z"}}}}}},"responses":{"201":{"description":"The published or scheduled post","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"success":{"type":"boolean","example":true},"postId":{"type":"string","description":"Platform post id. Absent for a scheduled post that has not published yet."},"scheduledAt":{"type":"string","format":"date-time","description":"Present when the post was scheduled rather than published."}}}}}},"400":{"description":"Invalid or unreachable post target — `to` is malformed for the platform, or names a page the connection cannot publish to.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid or unreachable post target","path":"/storefront/sync/post-to-social","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Product not found — The product id or SK does not resolve in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Product not found","path":"/storefront/sync/post-to-social","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Social"]}},"/storefront/sync/preview-social-post":{"post":{"operationId":"StorefrontController_previewSocialPost","summary":"Preview a social post","description":"Renders exactly what `post-to-social` would publish — caption, hashtags, link and selected media — and returns it without posting anything. Nothing is sent to the platform and no integration is required.\n\nIt takes the same body minus `to`, `scheduleAt` and `configId`, since there is no destination involved.\n\n#### Signature\n\n```http\nPOST /storefront/sync/preview-social-post (body) -> The rendered post\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRODUCT_NOT_FOUND | Product not found | The product id or SK does not resolve in the org. | Check the identifier with `GET /storefront/products`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/post-to-social`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The rendered post","content":{"application/json":{"schema":{"type":"object","properties":{"caption":{"type":"string","description":"The full caption as it would be published.","example":"Cola 330ml — $9.60\n\nShop now: https://shop.example.com/p/cola-330ml\n\n#drinks #sale"},"hashtags":{"type":"array","items":{"type":"string"},"example":["drinks","sale"]},"media":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The images or video that would be attached."},"postType":{"type":"string","description":"The resolved post type.","example":"image"}}}}}},"404":{"description":"Product not found — The product id or SK does not resolve in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Product not found","path":"/storefront/sync/preview-social-post","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Social"],"requestBody":{"description":"The post to render.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","productIds","siteName"],"properties":{"platform":{"type":"string","enum":["facebook","instagram","tiktok","twitter","linkedin","pinterest"],"example":"instagram"},"productIds":{"type":"array","items":{"type":"string"},"example":["66f1a2b3c4d5e6f708192a3b"]},"siteName":{"type":"string","description":"Site whose store URL builds the product links.","example":"main-store"},"postType":{"type":"string","enum":["image","carousel","video","story","reel"]},"customCaption":{"type":"string"},"customHashtags":{"type":"array","items":{"type":"string"}},"includePrice":{"type":"boolean","default":true},"includeHashtags":{"type":"boolean","default":true},"includeLink":{"type":"boolean","default":true}}},"example":{"platform":"instagram","productIds":["66f1a2b3c4d5e6f708192a3b"],"siteName":"main-store","includePrice":true}}}}}},"/storefront/sync/social-targets/{platform}":{"get":{"operationId":"StorefrontController_getSocialTargets","summary":"List social post targets","description":"Lists the pages, accounts and boards a product post can be published to on a platform. Each target includes a ready-to-use `to` value, so a client never has to assemble the platform-specific format itself.\n\nCall this to populate a destination picker before posting.\n\n#### Signature\n\n```http\nGET /storefront/sync/social-targets/{platform} (platform: string) -> The available targets\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Always take `to` from this response. Its format differs per platform — Facebook uses `x/pageId`, Instagram `x/pageId/instagramId`, Pinterest a board id, and the rest a bare account id.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PLATFORM_NOT_CONNECTED | No integration configured for this platform | The org has not connected that social platform. | Connect the platform in the org integration settings. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/sync/post-to-social`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"platform","required":true,"in":"path","description":"One of `facebook`, `instagram`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","schema":{"type":"string"},"example":"instagram"}],"responses":{"200":{"description":"The available targets","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Platform-native identifier.","example":"17841400000000000"},"name":{"type":"string","description":"Human-readable name.","example":"Acme Retail"},"to":{"type":"string","description":"Pass this verbatim as `to` when posting.","example":"x/1234567890/17841400000000000"}}}}}}},"404":{"description":"No integration configured for this platform — The org has not connected that social platform.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No integration configured for this platform","path":"/storefront/sync/social-targets/{platform}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Social"]}},"/storefront/workflows/order-management":{"post":{"operationId":"StorefrontController_createOrderManagementWorkflow","summary":"Create an order management workflow","description":"Creates a standard order-management workflow from the built-in template, giving orders a pipeline with the usual fulfilment stages. Customise the stages afterwards through the workflow API — this endpoint only scaffolds the template.\n\n#### Signature\n\n```http\nPOST /storefront/workflows/order-management (body) -> The created workflow\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | WORKFLOW_EXISTS | A workflow with this name already exists | The org already has a workflow with that name. | Read the existing one with `GET /storefront/workflows/order-management/{name}`, or create it under a different name. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/workflows/order-management/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Workflow name.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","default":"order-management","description":"Unique workflow name. Defaults to `order-management`.","example":"order-management"}}},"examples":{"default":{"summary":"Use the default name","value":{}},"named":{"summary":"Name it explicitly","value":{"name":"wholesale-orders"}}}}}},"responses":{"201":{"description":"The created workflow","content":{"application/json":{"schema":{"type":"object","description":"A workflow definition.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"A workflow with this name already exists — The org already has a workflow with that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A workflow with this name already exists","path":"/storefront/workflows/order-management","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Workflows"]}},"/storefront/workflows/order-management/{name}":{"get":{"operationId":"StorefrontController_getOrderManagementWorkflow","summary":"Get the order management workflow","description":"Fetches an order-management workflow by name. Omit the `name` segment and the workflow is found instead by its owner — the one bound to `sf_order` — which is the reliable way to ask \"what pipeline are orders running on?\" without knowing what it was called.\n\n#### Signature\n\n```http\nGET /storefront/workflows/order-management/{name} (name: string) -> The workflow definition\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORKFLOW_NOT_FOUND | Order management workflow not found | No workflow matches the name, or none is bound to `sf_order`. | Create one with `POST /storefront/workflows/order-management`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/workflows/order-management`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Workflow name. Omit to find the workflow bound to `sf_order`.","schema":{"type":"string"},"example":"order-management"}],"responses":{"200":{"description":"The workflow definition","content":{"application/json":{"schema":{"type":"object","description":"A workflow definition.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"404":{"description":"Order management workflow not found — No workflow matches the name, or none is bound to `sf_order`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Order management workflow not found","path":"/storefront/workflows/order-management/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Workflows"]}},"/storefront/subscriptions/check":{"post":{"operationId":"StorefrontSubscriptionController_check","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"What the run did","content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"type":"string","format":"date-time"},"processed":{"type":"number","description":"Subscriptions that were due and were run."},"charged":{"type":"number","description":"Charges that went through."},"failed":{"type":"number","description":"Charges refused (now past_due)."},"expired":{"type":"number","description":"Subscriptions that ended this run."},"rolled":{"type":"number","description":"Free renewals, trial ends and resumes with nothing charged."},"errors":{"type":"number","description":"Subscriptions the run could not process."},"problems":{"type":"array","items":{"type":"object","properties":{"subscription":{"type":"string"},"error":{"type":"string"}}}}}},"example":{"orgId":"demo","startedAt":"2026-10-03T06:00:00.000Z","finishedAt":"2026-10-03T06:00:04.000Z","processed":3,"charged":2,"failed":1,"expired":0,"rolled":0,"errors":0,"problems":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Run the subscription sweep now","description":"The daily subscription sweep, for this business, now. Every live subscription (new, trialing, active, past_due, paused) whose next step is due (`nextCycleAt` ≤ now) is run, one at a time: renewal charge to the saved card, trial end, payment retry (1, 3, 5 days after a decline; then `expired`), resume date of a paused one, end of a subscription set to cancel or not to renew, a plan change booked for period end. A failure on one never stops the rest. Safe to repeat: a subscription that is not due is left alone and every charge carries an idempotency key per subscription + period + attempt, so a second run the same day charges nothing more. The scheduled run (once a day per business) is set up by the scheduled-jobs framework. Staff only.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/check (body) -> What the run did\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/subscriptions/sweep`\n- `POST /storefront/subscriptions/{id}/run-cycle`","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionIds":{"type":"array","items":{"type":"string"},"description":"Only these subscriptions (record ids or numbers)."}}}}}}}},"/storefront/subscriptions/sweep":{"get":{"operationId":"StorefrontSubscriptionController_lastSweep","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The last run","content":{"application/json":{"schema":{"type":"object","properties":{"lastRun":{"type":"object","nullable":true,"additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Last subscription sweep","description":"The last full sweep of this business on this server (`lastRun`: the same summary `POST …/check` answers), or null — for \"Last billing run: …\". Staff only.\n\n#### Signature\n\n```http\nGET /storefront/subscriptions/sweep () -> The last run\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/check`"}},"/storefront/subscriptions/providers":{"get":{"operationId":"StorefrontSubscriptionController_listProviders","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"One entry per payment provider; usable ones first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Value for the plan's `upstream.name`.","example":"stripe"},"provider":{"type":"string","example":"StripeProvider"},"title":{"type":"string","example":"Stripe"},"configured":{"type":"boolean","description":"This business has an active config for it."},"recurring":{"type":"boolean","description":"It can save a payment method and charge it off-session."},"reason":{"type":"string","description":"Why it cannot be used for a paid plan — what it lacks (absent when it can)."}}}},"example":[{"name":"stripe","provider":"StripeProvider","title":"Stripe","configured":true,"recurring":true},{"name":"paypal","provider":"PayPalProvider","title":"PayPal","configured":false,"recurring":false,"reason":"PayPal here takes one-off orders only. Charging a subscription needs a saved PayPal payment method: the PayPal Vault (POST /v3/vault/setup-tokens, /v3/vault/payment-tokens) and orders paid with that vault id are not built into this integration."}]}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Payment providers that can charge a subscription","description":"Every payment provider the platform has, whether this business has it set up, and whether it can be used for a paid plan — the plan's provider (`upstream.name`). Subscriptions are ours alone: our engine and the daily sweep own every status, period, renewal, retry and cancellation; a provider only keeps the customer's card and charges it off-session when the engine asks. So `recurring: true` means exactly that: it can save a payment method and charge it later without the customer. Only Stripe can today; for the others `reason` names what the integration lacks. Money always moves through the business's own provider account. A plan priced 0 needs no provider.\n\nWhich provider charges a paid subscription: the one holding its saved card (`data.paymentMethod.provider`), else the plan's `upstream.name`, else the only configured provider that can charge a saved card.\n\n#### Signature\n\n```http\nGET /storefront/subscriptions/providers () -> One entry per payment provider; usable ones first\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Stripe webhooks never move a subscription by themselves. `payment_intent.succeeded` / `payment_intent.payment_failed` for a PaymentIntent our engine created (metadata `subscriptionId`) only settle that subscription's pending charge (`data.pendingCharge`, a charge the bank asked the customer to confirm); anything else — a replay, a charge already applied — changes nothing. Stripe Billing events (`customer.subscription.*`, `invoice.*`) are not applied to storefront subscriptions.\n- A Stripe config without a webhook signing secret accepts an event only by its id: the event is fetched from Stripe with the business's key, so a forged body is refused.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/subscribe`\n- `POST /storefront/subscriptions/{id}/payment-method`"}},"/storefront/subscriptions/plans":{"get":{"operationId":"StorefrontSubscriptionController_listPlans","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront · Subscriptions"]}},"/storefront/subscriptions/subscribe":{"post":{"operationId":"StorefrontSubscriptionController_subscribe","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The new subscription with `allowedActions` and `nextBoundary`","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"400":{"description":"A subscription plan is required — No `plan` (or `productId`) given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A subscription plan is required","path":"/storefront/subscriptions/subscribe","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"The first payment was refused — The payment provider refused the charge for a paid plan.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"The first payment was refused","path":"/storefront/subscriptions/subscribe","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Subscription plan … not found — No `sf_subscription_plan` by that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription plan … not found","path":"/storefront/subscriptions/subscribe","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Subscribe a customer to a plan","description":"Creates an `sf_subscription` on a plan. The server computes everything: price and currency from the plan, the first period (`periodStart` → `renewalDate`, calendar months/years in UTC; a `forever` plan has no renewal), the status, the first history entry, when the daily sweep next runs it (`nextCycleAt`) and the customer's confirmation email.\n\n- **Free plan (price 0)**: `active` at once. No payment provider, no payment step, never sent to a provider.\n- **Paid plan**: the card is kept with the plan's provider (`paymentMethodId` from Stripe Elements or a saved card, or a confirmed `setupIntentId` / `checkoutSessionId`) and the first period is charged now, off-session, for the plan's price — `active` when paid, 402 when refused (nothing is kept). If the bank asks the customer to confirm (3-D Secure) it is `new` with `payment.clientSecret`; it turns `active` when they confirm.\n- **No card sent**: `new` (awaiting a card) with `setup` in the answer — a SetupIntent client secret for Stripe Elements, or with `successUrl` a hosted Stripe page that saves the card. Then `POST /storefront/subscriptions/{id}/payment-method` saves it and charges the first period.\n- **Paid plan with a trial** (`plan.trial` days): `trialing`, nothing charged; the sweep charges the saved card when the trial ends (no card by then → `past_due`).\n\nA signed-in shopper subscribes themselves; staff subscribe the customer named by `email` (linked to the customer record by email when one exists).\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/subscribe (body) -> The new subscription with `allowedActions` and `nextBoundary`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SUBSCRIPTION_PLAN_REQUIRED | A subscription plan is required | No `plan` (or `productId`) given. | — |\n| `404` | SUBSCRIPTION_PLAN_NOT_FOUND | Subscription plan … not found | No `sf_subscription_plan` by that name. | — |\n| `402` | SUBSCRIPTION_PAYMENT_FAILED | The first payment was refused | The payment provider refused the charge for a paid plan. | Use another card, or a free plan. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/subscriptions/{id}`\n- `POST /storefront/subscriptions/{id}/payment-method`\n- `GET /storefront/subscriptions/providers`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","description":"Plan name (`sf_subscription_plan.name`). Or give `productId` of a product whose `plan` names it.","example":"newsletter-free"},"productId":{"type":"string","description":"A product that sells the plan (its `plan` field)."},"email":{"type":"string","description":"Subscriber. Required for staff calls; a shopper session uses its own.","example":"ada@example.com"},"trial":{"type":"boolean","description":"`false` skips the plan's trial. Free plans have no trial."},"autoRenew":{"type":"boolean","description":"Default true. `false` = the subscription expires at the end of its first period.","default":true},"transaction":{"type":"object","description":"A payment already taken for the first period: `{ ref, gateway, amount }`.","additionalProperties":true},"paymentMethodId":{"type":"string","description":"A card already collected (Stripe PaymentMethod id, e.g. from Stripe Elements).","example":"pm_1Pabc"},"setupIntentId":{"type":"string","description":"A SetupIntent the customer confirmed (from `setup.clientSecret`)."},"checkoutSessionId":{"type":"string","description":"A finished hosted card page (`session_id` on the return URL)."},"successUrl":{"type":"string","description":"No card sent: use a hosted Stripe page that saves the card; it returns here with `session_id`. `setup.redirectUrl` in the answer is where to send the customer."},"cancelUrl":{"type":"string","description":"Where the hosted card page returns when the customer gives up."},"note":{"type":"string","description":"Written on the first history entry."}}},"example":{"plan":"newsletter-free","email":"ada@example.com"}}}}}},"/storefront/subscriptions/{id}":{"get":{"operationId":"StorefrontSubscriptionController_get","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"200":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Get one subscription","description":"One subscription by record id or subscription number, enriched with its plan and payments, plus `allowedActions` — the lifecycle actions it accepts in its current state (render these; do not work them out) — and `nextBoundary`, when the daily sweep next runs it. A shopper reaches only their own (others answer 404).\n\n#### Signature\n\n```http\nGET /storefront/subscriptions/{id} (id: string) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Statuses: `new` (awaiting first payment) · `trialing` · `active` · `past_due` (a renewal payment failed; retried after 1, 3 and 5 days, then `expired`) · `paused` · `cancelled` · `expired`.\n- allowedActions by status — new: change-plan, cancel · trialing/active: pause, change-plan, renew, cancel (reactivate instead of pause/renew while set to cancel at period end) · past_due: renew, change-plan, cancel · paused: resume, cancel · cancelled/expired: reactivate.\n- `data.history[]` records every change: `{ date, action, status, from?, plan, by, note? }`. `data.renewals[]` records every paid (or free) period.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/{id}/run-cycle`"}},"/storefront/subscriptions/{id}/renew":{"post":{"operationId":"StorefrontSubscriptionController_renew","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/renew","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/subscriptions/{id}/renew","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Renew now / retry a failed payment","description":"Starts the next period now. Free: the period rolls (renewing early extends the current period; a period long gone starts fresh from now). Paid: the saved card is charged the plan price off-session — paid rolls the period, a decline (or a bank asking the customer to confirm) moves it to `past_due` with a retry booked (1, 3, 5 days; then `expired`). On a `past_due` subscription this is \"retry the payment\"; on a `trialing` one it ends the trial now. The charge carries an idempotency key per subscription + period + attempt, so repeating it never charges twice.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/renew (id: string, body) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/{id}/run-cycle`","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"transaction":{"type":"object","description":"A payment already taken: `{ ref, gateway, amount }`.","additionalProperties":true}}}}}}}},"/storefront/subscriptions/{id}/pause":{"post":{"operationId":"StorefrontSubscriptionController_pause","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription (status `paused`)","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"400":{"description":"resumeAt must be a future date — `resumeAt` is not a date or is in the past.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"resumeAt must be a future date","path":"/storefront/subscriptions/{id}/pause","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/pause","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/subscriptions/{id}/pause","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Pause a subscription","description":"Pauses an `active` or `trialing` subscription: nothing renews while paused. With `resumeAt` it resumes by itself on that date (the daily sweep resumes it that day); without, it waits for `resume`. The time spent paused is added to the current period on resume. The customer is emailed.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/pause (id: string, body) -> The subscription (status `paused`)\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n| `400` | SUBSCRIPTION_BAD_RESUME_DATE | resumeAt must be a future date | `resumeAt` is not a date or is in the past. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/{id}/resume`","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resumeAt":{"type":"string","format":"date-time","description":"Future date to resume by itself."},"reason":{"type":"string"}}},"example":{"resumeAt":"2026-12-01T00:00:00.000Z","reason":"Away for November"}}}}}},"/storefront/subscriptions/{id}/resume":{"post":{"operationId":"StorefrontSubscriptionController_resume","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/resume","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/subscriptions/{id}/resume","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Resume a paused subscription","description":"Back to the status it was paused from (`active` or `trialing`); the paused time is added to `renewalDate`, `nextCycleAt` moves with it and the customer is emailed.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/resume (id: string) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/{id}/pause`"}},"/storefront/subscriptions/{id}/change-plan":{"post":{"operationId":"StorefrontSubscriptionController_changePlan","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"400":{"description":"A subscription plan is required — No `plan` (or `productId`) given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A subscription plan is required","path":"/storefront/subscriptions/{id}/change-plan","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"The first payment was refused — The payment provider refused the charge for a paid plan.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"The first payment was refused","path":"/storefront/subscriptions/{id}/change-plan","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Subscription plan … not found — No `sf_subscription_plan` by that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription plan … not found","path":"/storefront/subscriptions/{id}/change-plan","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/subscriptions/{id}/change-plan","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Change plan (upgrade / downgrade)","description":"`when: \"now\"` (default) switches at once. Proration (computed here, charged to the saved card): while a paid period is running (`active`), the period end stays and the customer is charged (new price − old price) × the unused share of the period when that is above 0; moving to a cheaper plan charges nothing and refunds nothing. Outside a running paid period (`new`, `past_due`, from a free plan) a new period starts now and the full new price is charged. Inside a trial only the plan changes. A refused charge leaves the subscription unchanged and answers 402. `when: \"period_end\"` books the switch for the end of the current period (`data.pendingPlan`, no charge until that renewal); asking for the current plan with `period_end` withdraws a booked change.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/change-plan (id: string, body) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SUBSCRIPTION_PLAN_REQUIRED | A subscription plan is required | No `plan` (or `productId`) given. | — |\n| `404` | SUBSCRIPTION_PLAN_NOT_FOUND | Subscription plan … not found | No `sf_subscription_plan` by that name. | — |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n| `402` | SUBSCRIPTION_PAYMENT_FAILED | The first payment was refused | The payment provider refused the charge for a paid plan. | Use another card, or a free plan. |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","example":"pro-annual"},"when":{"type":"string","enum":["now","period_end"],"default":"now"},"transaction":{"type":"object","additionalProperties":true}}},"examples":{"now":{"summary":"Switch now","value":{"plan":"pro-annual"}},"later":{"summary":"Switch at period end","value":{"plan":"basic-monthly","when":"period_end"}}}}}}}},"/storefront/subscriptions/{id}/cancel":{"post":{"operationId":"StorefrontSubscriptionController_cancel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/subscriptions/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Cancel now or at period end","description":"`when: \"period_end\"` keeps it running to the end of the current period (`cancelAtPeriodEnd`, `endDate` = `renewalDate`) and ends it then as `cancelled`; it is the default while a period is running. `when: \"now\"` ends it immediately (`cancelled`; the sweep never charges it again). No payment provider is called — the card simply stops being charged. The customer is emailed.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/cancel (id: string, body) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/subscriptions/{id}/reactivate`","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"when":{"type":"string","enum":["now","period_end"]},"reason":{"type":"string"}}},"example":{"when":"period_end","reason":"Moving to another provider"}}}}}},"/storefront/subscriptions/{id}/reactivate":{"post":{"operationId":"StorefrontSubscriptionController_reactivate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"402":{"description":"The first payment was refused — The payment provider refused the charge for a paid plan.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"The first payment was refused","path":"/storefront/subscriptions/{id}/reactivate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/reactivate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/subscriptions/{id}/reactivate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Reactivate a subscription","description":"Set to cancel at period end → keeps renewing (cancellation withdrawn, nothing charged). `cancelled` / `expired` → a new period starts now on its plan: free plans are `active` at once; paid plans charge the saved card the plan price (402 when refused); with no card on file it waits as `new` for `POST …/payment-method`.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/reactivate (id: string, body) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n| `402` | SUBSCRIPTION_PAYMENT_FAILED | The first payment was refused | The payment provider refused the charge for a paid plan. | Use another card, or a free plan. |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"transaction":{"type":"object","additionalProperties":true}}}}}}}},"/storefront/subscriptions/{id}/payment-method":{"post":{"operationId":"StorefrontSubscriptionController_paymentMethod","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription (with `setup` when no card was sent)","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"400":{"description":"The card could not be saved — The provider refused the card, or the SetupIntent / page was not completed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The card could not be saved","path":"/storefront/subscriptions/{id}/payment-method","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"The first payment was refused — The payment provider refused the charge for a paid plan.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"The first payment was refused","path":"/storefront/subscriptions/{id}/payment-method","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/payment-method","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"A paused subscription cannot renew — The action is not one of the subscription's `allowedActions` in its current status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"A paused subscription cannot renew","path":"/storefront/subscriptions/{id}/payment-method","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Save a new card on a subscription","description":"Keeps a new card for a paid subscription with its provider (it becomes the customer's default there). The next charge uses it. A `past_due` subscription is charged again at once (a new attempt); a `new` one (awaiting its first payment) is charged its first period and turns `active`. Without a card in the body the answer carries `setup` — a SetupIntent client secret for Stripe Elements, or with `successUrl` a hosted Stripe page — and nothing changes until the card comes back here as `setupIntentId` / `checkoutSessionId`.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/payment-method (id: string, body) -> The subscription (with `setup` when no card was sent)\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n| `409` | SUBSCRIPTION_ACTION_NOT_ALLOWED | A paused subscription cannot renew | The action is not one of the subscription's `allowedActions` in its current status. | Read `allowedActions` from the subscription and offer only those. |\n| `402` | SUBSCRIPTION_PAYMENT_FAILED | The first payment was refused | The payment provider refused the charge for a paid plan. | Use another card, or a free plan. |\n| `400` | SUBSCRIPTION_CARD_REFUSED | The card could not be saved | The provider refused the card, or the SetupIntent / page was not completed. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/subscriptions/providers`","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentMethodId":{"type":"string","example":"pm_1Pabc"},"setupIntentId":{"type":"string","example":"seti_1Pabc"},"checkoutSessionId":{"type":"string","example":"cs_test_abc"},"successUrl":{"type":"string"},"cancelUrl":{"type":"string"}}},"examples":{"card":{"summary":"A card from Stripe Elements","value":{"paymentMethodId":"pm_1Pabc"}},"setup":{"summary":"Ask how to add one","value":{}}}}}}}},"/storefront/subscriptions/{id}/record-payment":{"post":{"operationId":"StorefrontSubscriptionController_recordPayment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/record-payment","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Record a payment taken outside the provider","description":"Staff record cash, a bank transfer or another payment for this subscription: it activates a `new` one, ends a trial, clears `past_due`, or pays the next period, and writes an `sf_transaction` (invoiceType `subscription`). A payment ref already applied is ignored. Take-payment with `invoiceType: \"subscription\"` applies the same way.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/record-payment (id: string, body) -> The subscription\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","example":"CASH-0192"},"gateway":{"type":"string","default":"offline"},"amount":{"type":"number","example":20}}},"example":{"ref":"CASH-0192","gateway":"offline","amount":20}}}}}},"/storefront/subscriptions/{id}/refund":{"post":{"operationId":"StorefrontSubscriptionController_refund","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront · Subscriptions"]}},"/storefront/subscriptions/{id}/books":{"put":{"operationId":"StorefrontSubscriptionController_postToBooks","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Storefront · Subscriptions"]}},"/storefront/subscriptions/{id}/run-cycle":{"post":{"operationId":"StorefrontSubscriptionController_runCycle","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Subscription record id or subscription number.","example":"K7Q2M9XWA"}],"responses":{"201":{"description":"The subscription after the run","content":{"application/json":{"schema":{"type":"object","description":"A subscription.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Subscription number.","example":"K7Q2M9XWA"},"plan":{"type":"string","example":"pro-monthly"},"planTitle":{"type":"string","example":"Pro"},"status":{"type":"string","enum":["new","trialing","active","past_due","paused","cancelled","expired"]},"amount":{"type":"number","description":"Price per period, from the plan. 0 = free.","example":20},"currency":{"type":"string","example":"USD"},"email":{"type":"string","example":"ada@example.com"},"customer":{"type":"string","description":"Customer record id, when one exists."},"startDate":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"End of the current period / next billing. Null for a `forever` plan or while awaiting first payment."},"endDate":{"type":"string","format":"date-time","nullable":true},"autoRenew":{"type":"boolean"},"cancelAtPeriodEnd":{"type":"boolean"},"pendingPlan":{"type":"string","nullable":true,"description":"Plan it switches to at the end of this period."},"pausedAt":{"type":"string","nullable":true},"resumeAt":{"type":"string","nullable":true},"failedAttempts":{"type":"number"},"nextRetry":{"type":"string","nullable":true},"lastPaymentError":{"type":"string","nullable":true},"nextCycleAt":{"type":"string","nullable":true,"description":"When the daily subscription sweep next runs it (renewal, trial end, retry, resume date, end of term)."},"paymentMethod":{"type":"object","nullable":true,"description":"Paid only: the provider's references to the saved payment method the engine charges — `{ provider, customerId, id }`. No card information is kept (no number, brand, last digits or expiry); the provider holds the card.","properties":{"provider":{"type":"string","example":"stripe"},"customerId":{"type":"string","example":"cus_Q1abc"},"id":{"type":"string","example":"pm_1Pabc"}}},"pendingCharge":{"type":"object","nullable":true,"description":"A charge the bank asked the customer to confirm (3-D Secure): `{ ref, amount, purpose, at }`. Its webhook marks it paid or failed."},"renewals":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"action":{"type":"string","example":"renewed"},"status":{"type":"string"},"from":{"type":"string"},"plan":{"type":"string"},"by":{"type":"string"},"note":{"type":"string"}}}}}},"allowedActions":{"type":"array","items":{"type":"string","enum":["pause","resume","change-plan","renew","cancel","reactivate","payment-method","record-payment"]},"description":"Lifecycle actions it accepts now."},"nextBoundary":{"type":"string","nullable":true,"description":"When the daily sweep next runs it."},"paymentMethodSaved":{"type":"object","nullable":true,"description":"Set when a payment method is saved with the provider: `{ provider }`. Null when none is saved.","properties":{"provider":{"type":"string","example":"stripe"}}},"nextChargeDate":{"type":"string","nullable":true,"description":"When the saved card is next charged (renewal / trial end; the retry date when past_due). Null when nothing will be charged — free, cancelling, paused, ended."},"payment":{"type":"object","additionalProperties":true,"description":"Only when the bank asked the customer to confirm a charge: `{ outcome: \"pending\", clientSecret, publishableKey }` — confirm it with Stripe.js."},"setup":{"type":"object","additionalProperties":true,"description":"Only when a card is needed and none was sent: `{ provider, clientSecret, setupIntentId, publishableKey }` (confirm with Stripe Elements) or `{ provider, redirectUrl, checkoutSessionId }` (hosted card page). Then send `setupIntentId` / `checkoutSessionId` to `POST /storefront/subscriptions/{id}/payment-method`."}}}}}},"404":{"description":"Subscription … not found — No subscription by that id/number in the org, or a shopper asked for someone else's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Subscription … not found","path":"/storefront/subscriptions/{id}/run-cycle","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Subscriptions"],"summary":"Run this subscription's next step now","description":"Runs, now, exactly what the daily sweep runs for this subscription when its next step is due (`nextBoundary`): the period end (renew and charge the saved card / trial end / switch a booked plan / end one set to cancel or not to renew → `cancelled` / `expired`), the resume date of a paused one, or the next payment retry of a past_due one. Not due yet → nothing changes.\n\n#### Signature\n\n```http\nPOST /storefront/subscriptions/{id}/run-cycle (id: string) -> The subscription after the run\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Customer emails per step (templates an org can override by name): subscription-confirmation, -renewal, -paused, -resumed, -plan-changed, -cancelled, -reactivated, -expired, -payment-failed.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SUBSCRIPTION_NOT_FOUND | Subscription … not found | No subscription by that id/number in the org, or a shopper asked for someone else's. | Use the id or number from the subscription record. |\n\nPlus the standard platform errors: `429`, `500`."}},"/storefront/giftcards/balance":{"get":{"operationId":"GiftCardController_checkBalance","summary":"Check a gift card balance","description":"Looks a card up by its **redemption code** and reports whether it can be spent and how much is on it. Separators and case in the code are ignored.\n\n**A card that cannot be used is still a `200`.** The response carries `valid: false` with a `status` that says why — `not_found`, `invalid_pin`, `expired`, or the card's own status when it is inactive, suspended or cancelled. Branch on `valid` and `status`, not on the HTTP code.\n\nFor an unusable card `balance` is reported as `0` regardless of what the card holds. An active card found past its date is marked `expired` on the way through.\n\n**Staff only** — the till and admin. Shoppers check a card through `GET /client/giftcards/balance`, which carries the per-address throttle.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/balance (code?: string, pin?: string) -> The card's spendability and balance\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The PIN is never echoed back and is never stored — only an HMAC of it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | FORBIDDEN | This needs someone signed in to the business | Called with a site's app token or a customer token. | Shoppers use GET /client/giftcards/balance. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/giftcards/redeem`\n- `GET /client/giftcards/balance`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"code","required":true,"in":"query","schema":{"type":"string"},"description":"The redemption code. Not the serial.","example":"YMFB-CDZ2-KDXS-KLM9"},{"name":"pin","required":false,"in":"query","schema":{"type":"string"},"description":"Required for physical cards. A wrong or missing PIN yields `status: \"invalid_pin\"`.","example":"4821"}],"responses":{"200":{"description":"The card's spendability and balance","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"balance":{"type":"number","description":"Remaining value. **`0` whenever `valid` is false.**","example":35.5},"currency":{"type":"string","example":"USD"},"status":{"type":"string","description":"The card status, or `not_found` / `invalid_pin`.","example":"active"},"expirationDate":{"type":"string","format":"date-time"},"maxUsePerTransaction":{"type":"number","description":"Present on a valid card that carries the restriction, so a checkout can size the tender without another call."},"minPurchase":{"type":"number"},"message":{"type":"string","description":"Shopper-facing explanation. Present only when `valid` is false."}}},"examples":{"valid":{"summary":"Spendable card","value":{"valid":true,"balance":35.5,"currency":"USD","status":"active"}},"expired":{"summary":"Expired card","value":{"valid":false,"balance":0,"currency":"USD","status":"expired","expirationDate":"2026-01-01T00:00:00.000Z","message":"Gift card has expired"}},"badPin":{"summary":"Wrong PIN","value":{"valid":false,"balance":0,"currency":"USD","status":"invalid_pin","message":"Invalid PIN"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"This needs someone signed in to the business — Called with a site's app token or a customer token.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This needs someone signed in to the business","path":"/storefront/giftcards/balance","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/wallet/status":{"get":{"operationId":"GiftCardController_walletStatus","summary":"Which wallet passes this store can issue","description":"`{ apple, google }` — true when the pass credentials are set on the gift card integration (Payment gateways › Gift card). Staff version of `GET /client/giftcards/wallet/status`.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/wallet/status () -> { apple, google }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/wallet/apple`\n- `GET /storefront/giftcards/wallet/google`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"{ apple, google }","content":{"application/json":{"schema":{"type":"object","properties":{"apple":{"type":"boolean"},"google":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/wallet/apple":{"get":{"operationId":"GiftCardController_applePass","summary":"Apple Wallet pass for a card","description":"A signed `.pkpass` for the card with this **code** — balance, a QR of the code, expiry — sent as a file download (`Content-Type: application/vnd.apple.pkpass`). Staff only; shoppers use `GET /client/giftcards/wallet/apple`.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/wallet/apple (code?: string) -> The .pkpass file (binary)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `501` | WALLET_NOT_SET_UP | Apple Wallet is not set up for this store | The pass credentials are not configured on the gift card integration. | Check GET …/wallet/status first and only offer the button when true. |\n| `400` | CODE_REQUIRED | A gift card code is needed | No `code`. | — |\n| `404` | GIFT_CARD_NOT_FOUND | Gift card not found | The code does not resolve. (This one is a real 404.) | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/wallet/status`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"code","required":true,"in":"query","schema":{"type":"string"},"description":"The redemption code, not the serial.","example":"YMFB-CDZ2-KDXS-KLM9"}],"responses":{"200":{"description":"The .pkpass file (binary)","content":{"application/json":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"A gift card code is needed — No `code`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A gift card code is needed","path":"/storefront/giftcards/wallet/apple","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Gift card not found — The code does not resolve. (This one is a real 404.)","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Gift card not found","path":"/storefront/giftcards/wallet/apple","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"501":{"description":"Apple Wallet is not set up for this store — The pass credentials are not configured on the gift card integration.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":501,"error":"Apple Wallet is not set up for this store","path":"/storefront/giftcards/wallet/apple","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/wallet/google":{"get":{"operationId":"GiftCardController_googlePass","summary":"Google Wallet link for a card","description":"The \"Save to Google Wallet\" link for the card with this **code**. Staff only; shoppers use `GET /client/giftcards/wallet/google`.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/wallet/google (code?: string) -> { url }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `501` | WALLET_NOT_SET_UP | Google Wallet is not set up for this store | The pass credentials are not configured on the gift card integration. | Check GET …/wallet/status first and only offer the button when true. |\n| `400` | CODE_REQUIRED | A gift card code is needed | No `code`. | — |\n| `404` | GIFT_CARD_NOT_FOUND | Gift card not found | The code does not resolve. (This one is a real 404.) | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/wallet/status`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"code","required":true,"in":"query","schema":{"type":"string"},"description":"The redemption code, not the serial.","example":"YMFB-CDZ2-KDXS-KLM9"}],"responses":{"200":{"description":"{ url }","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://pay.google.com/gp/v/save/eyJhbGciOi…"}}}}}},"400":{"description":"A gift card code is needed — No `code`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A gift card code is needed","path":"/storefront/giftcards/wallet/google","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Gift card not found — The code does not resolve. (This one is a real 404.)","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Gift card not found","path":"/storefront/giftcards/wallet/google","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"501":{"description":"Google Wallet is not set up for this store — The pass credentials are not configured on the gift card integration.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":501,"error":"Google Wallet is not set up for this store","path":"/storefront/giftcards/wallet/google","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/redeem":{"post":{"operationId":"GiftCardController_redeem","summary":"Redeem a gift card","description":"Spends value from a card against an order, under a per-card lock, and appends the movement to the card's `uses[]`. **Staff only** (the till); a shopper's checkout spends through `POST /client/giftcards/redeem`, which behaves the same.\n\n**The amount is clamped** to the available balance and to the card's `maxUsePerTransaction`. Asking for more is not an error — the card pays what it can and `amountRedeemed` says how much. Always trust `amountRedeemed`, never the amount you asked for, and collect the difference another way.\n\nThe card is re-validated here, so an expired, suspended or inactive card is refused even if your balance check passed earlier. Restrictions are enforced when `context` describes the order.\n\n**Idempotent on a key.** Send an `Idempotency-Key` header (or `idempotencyKey` in the body). A repeat with the same key returns the first result and moves no value — the site's checkout always sends one.\n\nThe response `transactionId` (GCT-…) is the **payment reference**: record the payment with `gateway: \"giftcard\"` and `ref: <transactionId>` and the ledger verifies it against the card before writing it as paid. One reference can back one payment.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/redeem (body) -> What was actually redeemed\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Two concurrent redemptions on one card are serialised; the balance can never be spent twice.\n- `amountRedeemed` is the number your order should trust, never the amount you requested.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card not found | The code does not resolve. | Check the code. This is a `400`, not a `404`. |\n| `409` | LOCKED | The gift card is being updated by another request. Try again. | Another redemption on the same card held the lock for longer than the retry window (~3s). | Retry with the same idempotency key. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/balance`\n- `POST /storefront/giftcards/{serial}/refund`\n- `POST /storefront/take-payment`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Same key → same result, no second spend.","schema":{"type":"string"}}],"responses":{"201":{"description":"What was actually redeemed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"amountRedeemed":{"type":"number","description":"**What was actually taken** — may be less than requested.","example":14.5},"remainingBalance":{"type":"number","example":21},"transactionId":{"type":"string","description":"The payment reference, prefixed `GCT-`.","example":"GCT-VB8C-SZ7F-E33V"},"serial":{"type":"string","example":"GC-7K2M-9QX4-H1P7"},"currency":{"type":"string","example":"USD"},"idempotent":{"type":"boolean","description":"Present and true when this response is a replay of an earlier one with the same key."}}},"example":{"success":true,"amountRedeemed":14.5,"remainingBalance":21,"transactionId":"GCT-VB8C-SZ7F-E33V","serial":"GC-7K2M-9QX4-H1P7","currency":"USD"}}}},"400":{"description":"Gift card not found — The code does not resolve.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card not found","path":"/storefront/giftcards/redeem","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The gift card is being updated by another request. Try again. — Another redemption on the same card held the lock for longer than the retry window (~3s).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"The gift card is being updated by another request. Try again.","path":"/storefront/giftcards/redeem","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"The card, the amount and the order.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","amount","orderNumber"],"properties":{"code":{"type":"string","description":"Redemption code, not the serial.","example":"YMFB-CDZ2-KDXS-KLM9"},"amount":{"type":"number","description":"Amount to spend. Clamped to the balance and the per-transaction cap.","example":14.5},"orderNumber":{"type":"string","description":"What the redemption is recorded against — an order, invoice or tab number, or the cart id before an order exists.","example":"A7K2M9QX4"},"pin":{"type":"string","description":"Required for physical cards."},"idempotencyKey":{"type":"string","description":"Alternative to the header."},"context":{"type":"object","description":"What the card is paying for, so its restrictions can be enforced.","properties":{"orderTotal":{"type":"number"},"skus":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"hasDiscountedItems":{"type":"boolean"},"channel":{"type":"string","example":"checkout"}}}}},"examples":{"partial":{"summary":"Spend part of the balance","value":{"code":"YMFB-CDZ2-KDXS-KLM9","amount":14.5,"orderNumber":"A7K2M9QX4","idempotencyKey":"9f1c-…"}},"overAsk":{"summary":"Ask for more than the card holds","description":"Succeeds, redeeming only the balance. Check `amountRedeemed`.","value":{"code":"YMFB-CDZ2-KDXS-KLM9","amount":200,"orderNumber":"A7K2M9QX4"}}}}}}}},"/storefront/giftcards":{"post":{"operationId":"GiftCardController_create","summary":"Create a gift card","description":"Issues a single card. The serial and code are generated by the server; a caller may bring a `code` (a printed stock run) and it is checked for a clash.\n\nCards are `inactive` unless `activate: true` is sent — activate physical stock when it is sold. A physical card gets a PIN, which is **returned once on this response as `data.pin` and never again**; only its hash is stored.\n\n**Issuing does not send anything.** To email/text the card to its recipient, call `POST /storefront/giftcards/{serial}/send` next.\n\nPick `type` by where the value came from: `digital`/`physical` for a card someone paid for (a liability), `promotional` for a free card — a goodwill or apology card, a giveaway — which is not a liability.\n\n**Expiry follows the org policy** (`GET /storefront/giftcards/policy`) for purchased cards: no `expirationDate` takes the policy default (none = never expires), and a date sooner than the policy minimum is refused. Promotional cards may expire whenever.\n\n**Cards sold as products are not issued here.** A product with `giftCard.enabled` on `sf_product` is a gift card: the product page asks for the value (`denominations[]`, or a custom amount within `minAmount`–`maxAmount` when `allowCustomAmount`), a recipient, a message and a delivery date, carried on the cart line as the options \"Gift card amount\", \"Recipient name\", \"Recipient email\", \"Gift message\", \"Deliver on\". Pricing honours \"Gift card amount\" and applies no tier, price list, benefit or discount to the line. When the order is paid — cart checkout, a pay link, or a POS settle — one active digital card is issued per unit (idempotent per order, line and unit), `purchaseOrderNumber` ties it to the order, and it is emailed at once or on the chosen date.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards (body) -> The created card, with its serial and code (and `pin`, once, for a physical card)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_VALUE | A gift card needs a value greater than zero | `initialAmount` is missing or not positive. | Send the value. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/giftcards/batch`\n- `PUT /storefront/giftcards/{serial}/activate`\n- `POST /storefront/giftcards/{serial}/send`\n- `GET /storefront/giftcards/policy`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created card, with its serial and code (and `pin`, once, for a physical card)","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"A gift card needs a value greater than zero — `initialAmount` is missing or not positive.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A gift card needs a value greater than zero","path":"/storefront/giftcards","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"The card to issue.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}},"activate":{"type":"boolean","description":"Issue the card ready to spend."},"pin":{"type":"string","description":"Physical cards only: 4–8 digits. Generated when omitted."}}},"example":{"initialAmount":50,"currency":"USD","type":"digital","activate":true,"recipientEmail":"ada@example.com","recipientName":"Ada"}}}}},"get":{"operationId":"GiftCardController_list","summary":"List gift cards","description":"Operator list with **server-side** search, filters, sort and paging. `search` matches serial, code, recipient name/email, buyer, the selling order and any order the card was spent on. Full records including balances and use history — an operator read.\n\n#### Signature\n\n```http\nGET /storefront/giftcards (search?: string, status?: string, type?: string, batch?: string, campaign?: string, customerId?: string, expiringWithinDays?: integer, sort?: string, sortType?: string, page?: integer, pageSize?: integer) -> A page of gift cards\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/stats`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"]}},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["physical","digital","promotional"]}},{"name":"batch","required":false,"in":"query","schema":{"type":"string"}},{"name":"campaign","required":false,"in":"query","schema":{"type":"string"},"description":"Promotional campaign name."},{"name":"search","required":false,"in":"query","schema":{"type":"string"},"example":"ada@example.com"},{"name":"customerId","required":false,"in":"query","schema":{"type":"string"}},{"name":"expiringWithinDays","required":false,"in":"query","schema":{"type":"integer"},"description":"Live cards whose date falls within this many days.","example":30},{"name":"sort","required":false,"in":"query","schema":{"type":"string","default":"createdate"},"description":"createdate, modifydate, data.balance, data.initialAmount, data.expirationDate, data.status, data.type, data.serial, data.recipientEmail"},{"name":"sortType","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":50},"description":"Max 200."}],"responses":{"200":{"description":"A page of gift cards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/batch":{"post":{"operationId":"GiftCardController_createBatch","summary":"Create a batch of gift cards","description":"Issues `count` identical cards (1–1000) in one call, each with its own serial and code, under a shared `batch` id so they can be listed and managed together. Physical cards come back with their PINs, once, for the printer.\n\nThis is how physical stock and promotional runs are produced. Filter them later with `GET /storefront/giftcards?batch=…`.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/batch (body) -> The issued cards and their batch identifier\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The batch is written synchronously, one card at a time; 1000 is the ceiling per call.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | BATCH_SIZE | A batch is between 1 and 1000 cards | `count` is below 1 or above 1000. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards`\n- `GET /storefront/giftcards/batches`\n- `POST /storefront/giftcards/import`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The issued cards and their batch identifier","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string"},"count":{"type":"number"},"cards":{"type":"array","items":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}}}}},"400":{"description":"A batch is between 1 and 1000 cards — `count` is below 1 or above 1000.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A batch is between 1 and 1000 cards","path":"/storefront/giftcards/batch","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"How many cards, and what they are worth.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["count","amount"],"properties":{"count":{"type":"number","example":100},"amount":{"type":"number","description":"Value of each card.","example":25},"currency":{"type":"string","example":"USD"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"physical"},"name":{"type":"string","description":"Card name; each gets \" n/count\" appended."},"expirationDate":{"type":"string","format":"date-time"},"restrictions":{"type":"object","additionalProperties":true},"activate":{"type":"boolean","description":"Issue the run ready to spend (promotional cards); physical stock is normally activated at the till."}}},"example":{"count":100,"amount":25,"currency":"USD","type":"physical"}}}}}},"/storefront/giftcards/stats":{"get":{"operationId":"GiftCardController_getStats","summary":"Gift card statistics","description":"The finance view, computed in the database: how much value is still owed to customers (`liability`), what was issued and redeemed, what expired unspent (`breakage`), what is about to expire, and the last 30 days. Promotional cards are reported separately and are never counted as a liability.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/stats () -> Aggregate gift card statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Declared before `GET /storefront/giftcards/{serial}`, so `stats` always resolves as this route.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Aggregate gift card statistics","content":{"application/json":{"schema":{"type":"object","properties":{"totalCards":{"type":"integer"},"activeCards":{"type":"integer"},"byStatus":{"type":"object","additionalProperties":{"type":"integer"}},"totalIssued":{"type":"number","description":"Purchased cards only."},"totalRedeemed":{"type":"number"},"totalBalance":{"type":"number","description":"Same as `liability`."},"liability":{"type":"number","description":"Outstanding value on live purchased cards."},"breakage":{"type":"object","properties":{"cards":{"type":"integer"},"value":{"type":"number"}}},"promotional":{"type":"object","properties":{"cards":{"type":"integer"},"issued":{"type":"number"},"outstanding":{"type":"number"}}},"expiringSoon":{"type":"object","properties":{"days":{"type":"integer"},"cards":{"type":"integer"},"value":{"type":"number"}}},"last30Days":{"type":"object","properties":{"issued":{"type":"object"},"redeemed":{"type":"object"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/verify/{transactionId}":{"get":{"operationId":"GiftCardController_verify","summary":"Verify a redemption reference","description":"Whether a GCT-… reference is a real redemption, for how much, on which card. This is what the transaction ledger asks before it writes a `giftcard` payment as paid; exposed so an operator can chase a reference by hand.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/verify/{transactionId} (transactionId: string) -> The verification — always a `200`; read `isValid`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/giftcards/redeem`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"transactionId","required":true,"in":"path","schema":{"type":"string"},"description":"The GCT-… reference from a redemption.","example":"GCT-VB8C-SZ7F-E33V"}],"responses":{"200":{"description":"The verification — always a `200`; read `isValid`","content":{"application/json":{"schema":{"type":"object","properties":{"isValid":{"type":"boolean"},"transactionId":{"type":"string"},"amountUsed":{"type":"number"},"currency":{"type":"string"},"cardNumber":{"type":"string","description":"The card serial."},"orderNumber":{"type":"string"},"usedBy":{"type":"string"},"date":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["completed","not_found"]},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/expire-due":{"post":{"operationId":"GiftCardController_expireDue","summary":"Expire due cards","description":"Flips every live card whose expiration date has passed to `expired` and posts the value left on purchased cards to the ledger as breakage income. A nightly job runs this per org (03:20); calling it is safe at any time and posts nothing twice.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/expire-due () -> What the sweep did\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"What the sweep did","content":{"application/json":{"schema":{"type":"object","properties":{"expired":{"type":"integer"},"breakage":{"type":"number"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/import":{"post":{"operationId":"GiftCardController_importCards","summary":"Issue cards from a list","description":"One card per row — a customer list, an apology run, a promotion. Rows share the type, currency, expiry, message template and campaign given at the top level, and all land in one new batch (`BATCH-…`). With `send: true` each activated card is emailed and/or texted to its row.\n\n**Bad rows are reported, not fatal**: a row without a positive amount, with a malformed email, or (when sending) with neither email nor phone comes back as `ok: false` with the `problem`, and the rest are issued. Cards are activated unless `activate: false`.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/import (body) -> The batch and one result per row\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | EMPTY_LIST | The list has no rows | `rows` is missing or empty. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/batches`\n- `POST /storefront/giftcards/{serial}/send`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The batch and one result per row","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string"},"issued":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"ok":{"type":"boolean"},"serial":{"type":"string"},"to":{"type":"string"},"sent":{"type":"array","items":{"type":"string","enum":["email","sms"]}},"problem":{"type":"string"}}}}}},"example":{"batch":"BATCH-7K2M","issued":1,"failed":1,"results":[{"row":1,"ok":true,"serial":"GC-7K2M-9QX4-H1P7","to":"Ada Lovelace","sent":["email"]},{"row":2,"ok":false,"problem":"Amount must be greater than zero"}]}}}},"400":{"description":"The list has no rows — `rows` is missing or empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The list has no rows","path":"/storefront/giftcards/import","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","description":"At most 1000.","items":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"amount":{"type":"number","description":"Currency symbols and separators are stripped (\"$25.00\" works)."},"message":{"type":"string"}}}},"currency":{"type":"string","example":"USD"},"type":{"type":"string","enum":["physical","digital","promotional"],"default":"digital"},"expirationDate":{"type":"string","format":"date-time"},"messageTemplate":{"type":"string"},"campaign":{"type":"string"},"batchName":{"type":"string"},"activate":{"type":"boolean","default":true},"send":{"type":"boolean","description":"Deliver each activated card to its row's email/phone."}}},"example":{"type":"promotional","campaign":"Spring apology","send":true,"rows":[{"name":"Ada Lovelace","email":"ada@example.com","amount":20,"message":"Sorry for the wait!"},{"name":"Grace","phone":"+15555550123","amount":"$15"}]}}}}}},"/storefront/giftcards/reconciliation":{"get":{"operationId":"GiftCardController_reconciliation","summary":"Reconcile gift cards with the books","description":"Compares the ledger's gift card liability account (the mapped `giftCardLiability` role, account 2030 by default) with the sum of balances on live purchased cards (active, inactive, suspended; promotional cards excluded).\n\nHow the books treat cards: the value of cards **sold** is booked to the liability account, not to sales; a payment made with a card debits that liability instead of cash; cards that expire unspent are released as breakage income by the nightly sweep. Promotional cards touch none of this.\n\n`issuedWithoutSale` lists purchased cards issued by hand with no order behind them — their value was never booked as owed, which is the usual cause of a difference; `unexplained` is what remains once those are accounted for. `status` is `balanced`, `out_of_balance`, or `no_account` when the liability account does not exist, and `message` explains it in words.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/reconciliation () -> The comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/stats`\n- `GET /storefront/giftcards/insights`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The comparison","content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","format":"date-time"},"cards":{"type":"object","properties":{"count":{"type":"integer"},"outstanding":{"type":"number"}}},"ledger":{"type":"object","properties":{"accountCode":{"type":"string","example":"2030"},"accountName":{"type":"string","nullable":true},"found":{"type":"boolean"},"balance":{"type":"number","nullable":true}}},"difference":{"type":"number","nullable":true,"description":"Ledger balance minus card balances; null with no account."},"issuedWithoutSale":{"type":"object","properties":{"cards":{"type":"integer"},"issued":{"type":"number"},"serials":{"type":"array","items":{"type":"string"},"description":"Up to 20."}}},"unexplained":{"type":"number","nullable":true},"status":{"type":"string","enum":["balanced","out_of_balance","no_account"]},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/repair-unbooked":{"post":{"operationId":"GiftCardController_repairUnbooked","summary":"QA-only repair: book purchased cards issued by hand with no sale (Dr Marketing / Cr gift card liability)","description":"Dry run by default. Writes only when body.apply is true, body.orgs names this org, the caller is the owner AND the org is a QA org (qa1002-/qa1003-/qa1004-). Idempotent per card serial.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/unusual":{"get":{"operationId":"GiftCardController_unusual","summary":"Unusual gift card redemptions","description":"Redemptions for someone to check, over the last `days`: a card **emptied within an hour** of being issued or activated (the usual shape of a stolen or leaked code), and a card **redeemed five or more times within a day**. Newest first, at most 100 flags.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/unusual (days?: integer) -> The flags\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"days","required":false,"in":"query","schema":{"type":"integer","default":30},"description":"1–365."}],"responses":{"200":{"description":"The flags","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"count":{"type":"integer"},"flags":{"type":"array","items":{"type":"object","properties":{"serial":{"type":"string"},"holder":{"type":"string","nullable":true},"reason":{"type":"string","example":"Emptied within an hour of being issued"},"at":{"type":"string","format":"date-time"},"amount":{"type":"number"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/insights":{"get":{"operationId":"GiftCardController_insights","summary":"Gift card insights","description":"The gift card dashboard over the last `months`: liability aging (0–30 days … over 2 years), outstanding by batch (top 10), redemption by channel, monthly issued vs redeemed/refunded/reloaded, purchased vs promotional totals, breakage (expired value) for each, and promotional campaigns with their redemption rate.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/insights (months?: integer) -> The dashboard figures\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/stats`\n- `GET /storefront/giftcards/reconciliation`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"months","required":false,"in":"query","schema":{"type":"integer","default":12},"description":"1–36."}],"responses":{"200":{"description":"The dashboard figures","content":{"application/json":{"schema":{"type":"object","properties":{"months":{"type":"integer"},"liabilityAging":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","example":"0–30 days"},"cards":{"type":"integer"},"outstanding":{"type":"number"}}}},"outstandingByBatch":{"type":"array","items":{"type":"object","properties":{"batch":{"type":"string"},"name":{"type":"string","nullable":true},"cards":{"type":"integer"},"outstanding":{"type":"number"}}}},"redemptionByChannel":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"count":{"type":"integer"},"amount":{"type":"number"}}}},"monthly":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","example":"2026-09"},"issuedCount":{"type":"integer"},"issued":{"type":"number"},"redeemed":{"type":"number"},"refunded":{"type":"number"},"reloaded":{"type":"number"}}}},"purchased":{"type":"object","properties":{"cards":{"type":"integer"},"issued":{"type":"number"},"redeemed":{"type":"number"},"outstanding":{"type":"number"}}},"promotional":{"type":"object","properties":{"cards":{"type":"integer"},"issued":{"type":"number"},"redeemed":{"type":"number"},"outstanding":{"type":"number"}}},"breakage":{"type":"object","properties":{"purchased":{"type":"object","properties":{"cards":{"type":"integer"},"value":{"type":"number"}}},"promotional":{"type":"object","properties":{"cards":{"type":"integer"},"value":{"type":"number"}}}}},"byCampaign":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string"},"cards":{"type":"integer"},"issued":{"type":"number"},"redeemed":{"type":"number"},"outstanding":{"type":"number"},"used":{"type":"integer"},"redemptionRate":{"type":"number","description":"Percent."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/batches":{"get":{"operationId":"GiftCardController_listBatches","summary":"List gift card batches","description":"Each batch id with its name, note, type, size, total value, balance left and cards by status — computed from the cards, newest first. `search` matches the batch id, card name or batch name.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/batches (search?: string, page?: integer, pageSize?: integer) -> A page of batches\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/batches/{batch}/cards`\n- `POST /storefront/giftcards/batches/{batch}/{action}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":25},"description":"Max 100."}],"responses":{"200":{"description":"A page of batches","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"batch":{"type":"string"},"name":{"type":"string"},"note":{"type":"string"},"type":{"type":"string","enum":["physical","digital","promotional"]},"currency":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"count":{"type":"integer"},"value":{"type":"number"},"balance":{"type":"number"},"byStatus":{"type":"object","properties":{"inactive":{"type":"integer"},"active":{"type":"integer"},"used":{"type":"integer"},"expired":{"type":"integer"},"cancelled":{"type":"integer"},"suspended":{"type":"integer"}}}}}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/campaigns":{"get":{"operationId":"GiftCardController_listCampaigns","summary":"Gift card campaigns","description":"The campaign names already on cards, with how many cards and how much value each carries — for pickers, so a campaign is chosen, not retyped.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"search","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/policy":{"get":{"operationId":"GiftCardController_getPolicy","summary":"Get the gift card expiry policy","description":"How long a **purchased** card lasts when no date is given (`defaultExpiresAfterDays`, null = never expires) and the earliest date an operator may set (`minimumExpiryDays`, default 1825 days / 5 years). Promotional cards are not bound by it.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/policy () -> The policy\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/giftcards/policy`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The policy","content":{"application/json":{"schema":{"type":"object","properties":{"defaultExpiresAfterDays":{"type":"integer","nullable":true,"description":"Days until a purchased card expires when no date is given; null = never."},"minimumExpiryDays":{"type":"integer","description":"Earliest allowed expiry for a purchased card, in days from issue.","example":1825}}},"example":{"defaultExpiresAfterDays":null,"minimumExpiryDays":1825}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]},"post":{"operationId":"GiftCardController_setPolicy","summary":"Set the gift card expiry policy","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The policy now in force","content":{"application/json":{"schema":{"type":"object","properties":{"defaultExpiresAfterDays":{"type":"integer","nullable":true,"description":"Days until a purchased card expires when no date is given; null = never."},"minimumExpiryDays":{"type":"integer","description":"Earliest allowed expiry for a purchased card, in days from issue.","example":1825}}}}}},"400":{"description":"The default expiry (<n> days) is shorter than the minimum (<m> days) — `defaultExpiresAfterDays` is set and below `minimumExpiryDays`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The default expiry (<n> days) is shorter than the minimum (<m> days)","path":"/storefront/giftcards/policy","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"description":"Omitted fields keep their current value. `defaultExpiresAfterDays` null or 0 means purchased cards never expire by default. A default shorter than the minimum is refused.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/policy (body) -> The policy now in force\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DEFAULT_BELOW_MINIMUM | The default expiry (<n> days) is shorter than the minimum (<m> days) | `defaultExpiresAfterDays` is set and below `minimumExpiryDays`. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"defaultExpiresAfterDays":{"type":"integer","nullable":true,"description":"Days until a purchased card expires when no date is given; null = never."},"minimumExpiryDays":{"type":"integer","description":"Earliest allowed expiry for a purchased card, in days from issue.","example":1825}}},"example":{"defaultExpiresAfterDays":1825,"minimumExpiryDays":1825}}}}}},"/storefront/giftcards/batches/{batch}/details":{"post":{"operationId":"GiftCardController_updateBatch","summary":"Rename a batch or add a note","description":"Writes `name` (as `batchName`) and/or `note` onto every card in the batch. An empty string clears it.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/batches/{batch}/details (batch: string, body) -> How many cards were updated\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOTHING_TO_CHANGE | Nothing to change | Neither `name` nor `note` was sent. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"batch","required":true,"in":"path","schema":{"type":"string"},"description":"Batch id (`BATCH-…`).","example":"BATCH-7K2M-9QX4"}],"responses":{"201":{"description":"How many cards were updated","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string"},"updated":{"type":"integer"},"name":{"type":"string"},"note":{"type":"string"}}}}}},"400":{"description":"Nothing to change — Neither `name` nor `note` was sent.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Nothing to change","path":"/storefront/giftcards/batches/{batch}/details","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"note":{"type":"string"}}},"example":{"name":"Holiday stock 2026","note":"Printed run, box 3"}}}}}},"/storefront/giftcards/batches/{batch}/cards":{"get":{"operationId":"GiftCardController_batchCards","summary":"Cards in a batch","description":"Every card in the batch, oldest first, for re-export. Includes the redemption codes — **never the PINs**.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/batches/{batch}/cards (batch: string) -> The batch's cards\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"batch","required":true,"in":"path","schema":{"type":"string"},"description":"Batch id (`BATCH-…`).","example":"BATCH-7K2M-9QX4"}],"responses":{"200":{"description":"The batch's cards","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string"},"data":{"type":"array","items":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/batches/{batch}/{action}":{"post":{"operationId":"GiftCardController_batchAction","summary":"Block, unblock or cancel a whole batch","description":"`action` is `suspend`, `reactivate` or `cancel` — lost stock, leaked codes. Each card goes through the same guarded action as a single card, so a card with a redemption on it is never cancelled. Cards already in the target state (or, for reactivate, not blocked) are skipped with the reason. A `reason` is required for suspend and cancel.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/batches/{batch}/{action} (batch: string, action: string, body) -> What was done and what was skipped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_ACTION | Unknown batch action | `action` is not suspend, reactivate or cancel. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"batch","required":true,"in":"path","schema":{"type":"string"},"description":"Batch id (`BATCH-…`).","example":"BATCH-7K2M-9QX4"},{"name":"action","in":"path","required":true,"description":"suspend, reactivate or cancel.","schema":{"type":"string","enum":["suspend","reactivate","cancel"]},"example":"suspend"}],"responses":{"201":{"description":"What was done and what was skipped","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"string"},"action":{"type":"string"},"done":{"type":"integer"},"skipped":{"type":"array","items":{"type":"object","properties":{"serial":{"type":"string"},"reason":{"type":"string"}}}}}}}}},"400":{"description":"Unknown batch action — `action` is not suspend, reactivate or cancel.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown batch action","path":"/storefront/giftcards/batches/{batch}/{action}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Box of cards reported stolen"}}}}}},"/storefront/giftcards/activity":{"get":{"operationId":"GiftCardController_activity","summary":"Gift card activity","description":"Every movement on every card — redemptions, refunds, reloads, adjustments, transfers — newest first, filtered and paged in the database, with totals for the filtered set by kind and (for redemptions) by channel. `search` matches serial, holder name/email/phone, order number, redeemer and GCT reference.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/activity (kind?: string, channel?: string, from?: string, to?: string, batch?: string, search?: string, page?: integer, pageSize?: integer) -> A page of movements with summary totals\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/giftcards/{serial}/timeline`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]}},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"description":"checkout, pos, invoice, admin, gateway."},{"name":"from","required":false,"in":"query","schema":{"type":"string"},"description":"Date, YYYY-MM-DD.","example":"2026-09-01"},{"name":"to","required":false,"in":"query","schema":{"type":"string"},"description":"Date, YYYY-MM-DD.","example":"2026-09-30"},{"name":"batch","required":false,"in":"query","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":50},"description":"Max 200."}],"responses":{"200":{"description":"A page of movements with summary totals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"serial":{"type":"string"},"cardName":{"type":"string"},"type":{"type":"string"},"batch":{"type":"string"},"currency":{"type":"string"},"holderName":{"type":"string"},"holderEmail":{"type":"string"},"holderPhone":{"type":"string"},"customerId":{"type":"string"},"transactionId":{"type":"string"},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on."},"balanceAfter":{"type":"number"},"orderNumber":{"type":"string"},"usedBy":{"type":"string"},"channel":{"type":"string"},"reason":{"type":"string"}}}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"summary":{"type":"object","properties":{"byKind":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"count":{"type":"integer"},"amount":{"type":"number","description":"Absolute value."}}}},"byChannel":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"count":{"type":"integer"},"amount":{"type":"number"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/link-owners":{"post":{"operationId":"GiftCardController_linkOwners","summary":"Link cards to customers","description":"Backfill: every card with no `customerId` whose recipient email (or buyer email) or phone matches an existing customer is linked to that customer. Never creates customers. Looks at up to 5000 unowned cards per call.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/link-owners () -> How many were checked and linked\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"How many were checked and linked","content":{"application/json":{"schema":{"type":"object","properties":{"checked":{"type":"integer"},"linked":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/link-owners/preview":{"get":{"operationId":"GiftCardController_previewLinkOwners","summary":"Preview linking cards to customers","description":"The unowned cards whose holder matches a CRM customer (by email, else phone), paged, with the totals over all cards. Nothing is changed. Owner or admin.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/link-owners/runs":{"get":{"operationId":"GiftCardController_linkOwnerRuns","summary":"Link runs","description":"Each bulk link run: when, by whom, how many cards, how many undone. Owner or admin.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/link-owners/runs/{runId}/undo":{"post":{"operationId":"GiftCardController_undoLinkOwners","summary":"Undo a link run","description":"Unlinks the cards that run linked and that still point at the customer it set. Owner or admin.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"runId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/{serial}":{"get":{"operationId":"GiftCardController_getBySerial","summary":"Get a gift card","description":"One card by serial, with its balance and full ledger. Exposes the redemption `code`, so it is staff only — shoppers use `GET /client/giftcards/balance`, or `GET /client/giftcards/me` for their own cards.\n\n#### Signature\n\n```http\nGET /storefront/giftcards/{serial} (serial: string) -> The gift card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"200":{"description":"The gift card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/{serial}/timeline":{"get":{"operationId":"GiftCardController_timeline","summary":"A card's timeline","description":"One card's whole story, newest first: money movements (`type: money`), sends (`type: sent`) and everything else — status, holder and template changes (`type: event`).\n\n#### Signature\n\n```http\nGET /storefront/giftcards/{serial}/timeline (serial: string) -> The timeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"200":{"description":"The timeline","content":{"application/json":{"schema":{"type":"object","properties":{"serial":{"type":"string"},"currency":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["money","sent","event"]},"kind":{"type":"string"},"amount":{"type":"number"},"balanceAfter":{"type":"number"},"orderNumber":{"type":"string"},"by":{"type":"string"},"channel":{"type":"string"},"to":{"type":"string"},"reason":{"type":"string"},"detail":{"type":"string"},"reference":{"type":"string"}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/timeline","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/{serial}/reissue":{"post":{"operationId":"GiftCardController_reissue","summary":"Reissue a card","description":"Replaces a damaged, lost or leaked card: a new card is issued to the same holder with the same rules and expiry, the whole balance moves onto it, and the old card is voided — both ledgers record the move. The new card is then sent to the holder; `delivery` says how that went.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/{serial}/reissue (serial: string, body) -> The voided card, the new one and the send result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"201":{"description":"The voided card, the new one and the send result","content":{"application/json":{"schema":{"type":"object","properties":{"old":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}},"card":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}},"delivery":{"type":"object","properties":{"delivered":{"type":"boolean"},"to":{"type":"string"},"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms"]},"to":{"type":"string"}}}},"reason":{"type":"string","description":"Why nothing was sent, when `delivered` is false."}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/reissue","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}},"example":{"reason":"Code shared publicly"}}}}}},"/storefront/giftcards/{serial}/activate":{"put":{"operationId":"GiftCardController_activate","summary":"Activate a gift card","description":"Brings an inactive card into service. This is the step that arms physical stock once it is sold. A card already in another state is refused rather than treated as a no-op.\n\n#### Signature\n\n```http\nPUT /storefront/giftcards/{serial}/activate (serial: string) -> The activated card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/giftcards/{serial}/suspend`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"200":{"description":"The activated card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/activate","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"]}},"/storefront/giftcards/batch-jobs/{id}":{"get":{"operationId":"GiftCardController_batchJob","summary":"A batch being issued","description":"Progress of a batch issued in the background (more than 50 cards): created of count, status. With ?cards=1 once done, the cards — with physical PINs once.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"cards","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/sale-product":{"post":{"operationId":"GiftCardController_saleProduct","summary":"The till gift card product","description":"Finds or creates the \"Gift card\" product (SKU GIFT-CARD, any amount, not taxed) that the till sells cards as.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/{serial}/suspend":{"put":{"operationId":"GiftCardController_suspend","summary":"Suspend a gift card","description":"Reversible block — the response to a card reported lost or suspected stolen. The balance is untouched and redemption fails while it is suspended. Use this rather than cancel for anything you might undo, and for any card that has been spent against, since those cannot be cancelled.\n\n#### Signature\n\n```http\nPUT /storefront/giftcards/{serial}/suspend (serial: string, body) -> The suspended card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/giftcards/{serial}/reactivate`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"200":{"description":"The suspended card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/suspend","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"Why.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","example":"Reported stolen"}}}}}}}},"/storefront/giftcards/{serial}/expiry":{"put":{"operationId":"GiftCardController_changeExpiry","summary":"Change a gift card's expiry","description":"Moves a live card's expiry to a future date, or clears it (`expirationDate: null` = never expires). Purchased cards stay inside the expiry policy. Recorded on the card's timeline with the reason.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"serial","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Gift Cards"]}},"/storefront/giftcards/{serial}/reactivate":{"put":{"operationId":"GiftCardController_reactivate","summary":"Reactivate a suspended gift card","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"200":{"description":"The reactivated card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/reactivate","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"description":"Lifts a suspension. The card returns to the state it had before — active, or inactive if it had never been activated — with its balance intact.\n\n#### Signature\n\n```http\nPUT /storefront/giftcards/{serial}/reactivate (serial: string) -> The reactivated card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/storefront/giftcards/{serial}/cancel":{"put":{"operationId":"GiftCardController_cancel","summary":"Cancel a gift card","description":"Voids an **unused** card permanently. **A card with a redemption on it cannot be cancelled** — its ledger is a record of value already given to a customer. Suspend it instead.\n\n#### Signature\n\n```http\nPUT /storefront/giftcards/{serial}/cancel (serial: string, body) -> The cancelled card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"200":{"description":"The cancelled card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/cancel","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"Why.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","example":"Issued in error"}}}}}}}},"/storefront/giftcards/{serial}/refund":{"post":{"operationId":"GiftCardController_refund","summary":"Refund value onto a gift card","description":"Adds balance back, recording it against an order — a returned item refunded to store credit, or a redemption reversed. A fully-used card becomes active again. Send an `Idempotency-Key` header (or `idempotencyKey` in the body). A repeat with the same key returns the first result and moves no value — the site's checkout always sends one.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/{serial}/refund (serial: string, body) -> The card with its increased balance\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The amount is not checked against what was originally redeemed; a card can hold more than its initial value.\n- Returns completed with `refundMethod: giftcard` call this themselves — see `POST /storefront/returns/{rma}/complete`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional.","schema":{"type":"string"}}],"responses":{"201":{"description":"The card with its increased balance","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/refund","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"How much, against what.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","orderNumber"],"properties":{"amount":{"type":"number","example":14.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"reason":{"type":"string"},"idempotencyKey":{"type":"string"}}}}}}}},"/storefront/giftcards/{serial}/resend":{"post":{"operationId":"GiftCardController_resend","summary":"Resend a gift card email","description":"Emails the card again — to its recipient, or to the address given. The operator's answer to \"it never arrived\". The email carries the code, never a PIN.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/{serial}/resend (serial: string, body) -> Whether it went, and where\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"201":{"description":"Whether it went, and where","content":{"application/json":{"schema":{"type":"object","properties":{"delivered":{"type":"boolean"},"to":{"type":"string"},"reason":{"type":"string"}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/resend","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"Optional other address.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","format":"email"}}}}}}}},"/storefront/giftcards/{serial}/send":{"post":{"operationId":"GiftCardController_send","summary":"Send a gift card","description":"Sends the card by email and by SMS through the platform notification channels, using the card's message template (or `gift-card-issued`) and its SMS sibling. An `email`/`phone` given here replaces the one on the card (`to` may be either); with neither on the card, the buyer's email is used. Every send is recorded on the card.\n\n**Not being able to send is a `201` with `delivered: false`** and a `reason` (e.g. \"no email or phone on the card\") — check it.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/{serial}/send (serial: string, body) -> What was sent where\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/giftcards/{serial}/resend`\n- `POST /storefront/giftcards/{serial}/template`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"201":{"description":"What was sent where","content":{"application/json":{"schema":{"type":"object","properties":{"delivered":{"type":"boolean"},"to":{"type":"string"},"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms"]},"to":{"type":"string"}}}},"reason":{"type":"string","description":"Why nothing was sent, when `delivered` is false."}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"to":{"type":"string","description":"An email or a phone; used when neither `email` nor `phone` is given."}}},"example":{"email":"ada@example.com"}}}}}},"/storefront/giftcards/{serial}/owner":{"post":{"operationId":"GiftCardController_setOwner","summary":"Set the holder of a card","description":"Pick a customer by `customerId` — their name, email and phone come with them (anything also given in the body wins) — or give `name`/`email`/`phone`, linked to a matching customer when one exists. Recorded as a holder-changed event.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/{serial}/owner (serial: string, body) -> The card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"201":{"description":"The card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/owner","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}}},"example":{"customerId":"66f1c0ffee12"}}}}}},"/storefront/giftcards/{serial}/template":{"post":{"operationId":"GiftCardController_setTemplate","summary":"Set the message template a card is sent with","description":"The email template used by `send` (its SMS sibling is used for texts). An empty or missing `messageTemplate` clears it back to the platform default.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/{serial}/template (serial: string, body) -> The card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"201":{"description":"The card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/template","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messageTemplate":{"type":"string","example":"holiday-gift-card"}}}}}}}},"/storefront/giftcards/{serial}/adjust":{"post":{"operationId":"GiftCardController_adjust","summary":"Adjust a gift card balance","description":"Operator correction, up or down, always with a reason, recorded on the card's ledger as `kind: adjust`. Cannot take the balance below zero.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/{serial}/adjust (serial: string, body) -> The adjusted card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GIFT_CARD_NOT_FOUND | Gift card <serial> not found | No gift card in the org has that serial. | Check the serial with `GET /storefront/giftcards?search=`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"},"description":"Gift card **serial number**, not the redemption code. Case-insensitive.","example":"GC-7K2M-9QX4-H1P7"}],"responses":{"201":{"description":"The adjusted card","content":{"application/json":{"schema":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}},"400":{"description":"Gift card <serial> not found — No gift card in the org has that serial.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Gift card <serial> not found","path":"/storefront/giftcards/{serial}/adjust","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"Signed amount and why.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","reason"],"properties":{"amount":{"type":"number","description":"Positive adds, negative removes.","example":-5},"reason":{"type":"string","example":"Goodwill after a late delivery"}}}}}}}},"/storefront/giftcards/transfer":{"post":{"operationId":"GiftCardController_transfer","summary":"Transfer balance between gift cards","description":"Moves value from one active card to another of the same currency — consolidating balances, or reissuing a damaged card onto a fresh one. Unlike redemption the amount is **not** clamped: an over-ask is refused, not partially performed. Both cards are locked for the move.\n\n#### Signature\n\n```http\nPOST /storefront/giftcards/transfer (body) -> Both cards after the move\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Uses serials, not redemption codes — the opposite of `redeem` and `balance`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SOURCE_NOT_FOUND | Source gift card <serial> not found | `fromSerial` does not resolve. | Check the serial. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Both cards after the move","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}},"to":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}}}}}},"400":{"description":"Source gift card <serial> not found — `fromSerial` does not resolve.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Source gift card <serial> not found","path":"/storefront/giftcards/transfer","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards"],"requestBody":{"description":"From, to, how much.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromSerial","toSerial","amount"],"properties":{"fromSerial":{"type":"string"},"toSerial":{"type":"string"},"amount":{"type":"number"}}}}}}}},"/client/giftcards/balance":{"get":{"operationId":"GiftCardClientController_balance","summary":"Look a card up by its code (shopper)","description":"The shopper-side balance check: whether the card can be spent, what is left, and what is written on it — never an address or the PIN. Same answers as the staff check (`valid: false` with a `status` for an unusable card).\n\n**Throttled**: 30 checks per client address per 10 minutes, then `429`. A balance check is a code-existence oracle, and this is what keeps it from being an enumeration tool.\n\n#### Signature\n\n```http\nGET /client/giftcards/balance () -> The balance check\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `429` | TOO_MANY_REQUESTS | Too many balance checks. Try again in a few minutes. | More than 30 checks from one address in 10 minutes. | Wait, or use GET /client/giftcards/me, which lists the customer's own cards without a lookup. |\n\nPlus the standard platform errors: `401`, `403`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"code","required":true,"in":"query","schema":{"type":"string"}},{"name":"pin","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The balance check","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"description":"Too many balance checks. Try again in a few minutes. — More than 30 checks from one address in 10 minutes.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":429,"error":"Too many balance checks. Try again in a few minutes.","path":"/client/giftcards/balance","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards","Client account"]}},"/client/giftcards/redeem":{"post":{"operationId":"GiftCardClientController_redeem","summary":"Spend a card at checkout (shopper)","description":"Clamped to the balance and the per-transaction cap; `amountRedeemed` is the figure to trust. Send an idempotency key so a retry cannot spend twice. `usedBy` is the signed-in customer, else `guest`.\n\n#### Signature\n\n```http\nPOST /client/giftcards/redeem () -> The redemption, with its GCT reference\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"The redemption, with its GCT reference","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards","Client account"]}},"/client/giftcards/wallet/status":{"get":{"operationId":"GiftCardClientController_walletStatus","summary":"Which wallet passes this store can issue","description":"`{ apple, google }` — true when the store has put its pass credentials on the gift card integration (Payment gateways › Gift card). Show an Add-to-Wallet button only when true. `GET /client/giftcards/wallet/apple?code=` returns the signed `.pkpass`; `GET /client/giftcards/wallet/google?code=` returns `{ url }`, the Save to Google Wallet link. Both are throttled like the balance check; `501` until set up.\n\n#### Signature\n\n```http\nGET /client/giftcards/wallet/status () -> { apple, google }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"{ apple, google }","content":{"application/json":{"schema":{"type":"object","properties":{"apple":{"type":"boolean"},"google":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards","Client account"]}},"/client/giftcards/wallet/apple":{"get":{"operationId":"GiftCardClientController_applePass","summary":"Apple Wallet pass for my card","description":"The signed `.pkpass` for the card with this code, as a file download. Counts against the same per-address throttle as the balance check (30 checks per 10 minutes).\n\n#### Signature\n\n```http\nGET /client/giftcards/wallet/apple (code?: string) -> The .pkpass file (binary)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `501` | WALLET_NOT_SET_UP | Apple Wallet is not set up for this store | The pass credentials are not configured on the gift card integration. | Check GET …/wallet/status first and only offer the button when true. |\n| `400` | CODE_REQUIRED | A gift card code is needed | No `code`. | — |\n| `404` | GIFT_CARD_NOT_FOUND | Gift card not found | The code does not resolve. (This one is a real 404.) | — |\n| `429` | TOO_MANY_CHECKS | Too many gift card checks. Try again in a few minutes. | More than 30 checks from one address in 10 minutes (shared with the balance check). | — |\n\nPlus the standard platform errors: `401`, `403`, `500`.\n\n#### See also\n\n- `GET /client/giftcards/wallet/status`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"code","required":true,"in":"query","schema":{"type":"string"},"description":"The redemption code, not the serial.","example":"YMFB-CDZ2-KDXS-KLM9"}],"responses":{"200":{"description":"The .pkpass file (binary)","content":{"application/json":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"A gift card code is needed — No `code`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A gift card code is needed","path":"/client/giftcards/wallet/apple","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Gift card not found — The code does not resolve. (This one is a real 404.)","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Gift card not found","path":"/client/giftcards/wallet/apple","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"description":"Too many gift card checks. Try again in a few minutes. — More than 30 checks from one address in 10 minutes (shared with the balance check).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":429,"error":"Too many gift card checks. Try again in a few minutes.","path":"/client/giftcards/wallet/apple","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"500":{"$ref":"#/components/responses/ServerError"},"501":{"description":"Apple Wallet is not set up for this store — The pass credentials are not configured on the gift card integration.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":501,"error":"Apple Wallet is not set up for this store","path":"/client/giftcards/wallet/apple","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Gift cards","Client account"]}},"/client/giftcards/wallet/google":{"get":{"operationId":"GiftCardClientController_googlePass","summary":"Google Wallet link for my card","description":"The \"Save to Google Wallet\" link for the card with this code. Counts against the same per-address throttle as the balance check.\n\n#### Signature\n\n```http\nGET /client/giftcards/wallet/google (code?: string) -> { url }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `501` | WALLET_NOT_SET_UP | Google Wallet is not set up for this store | The pass credentials are not configured on the gift card integration. | Check GET …/wallet/status first and only offer the button when true. |\n| `400` | CODE_REQUIRED | A gift card code is needed | No `code`. | — |\n| `404` | GIFT_CARD_NOT_FOUND | Gift card not found | The code does not resolve. (This one is a real 404.) | — |\n| `429` | TOO_MANY_CHECKS | Too many gift card checks. Try again in a few minutes. | More than 30 checks from one address in 10 minutes (shared with the balance check). | — |\n\nPlus the standard platform errors: `401`, `403`, `500`.\n\n#### See also\n\n- `GET /client/giftcards/wallet/status`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"code","required":true,"in":"query","schema":{"type":"string"},"description":"The redemption code, not the serial.","example":"YMFB-CDZ2-KDXS-KLM9"}],"responses":{"200":{"description":"{ url }","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"400":{"description":"A gift card code is needed — No `code`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A gift card code is needed","path":"/client/giftcards/wallet/google","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Gift card not found — The code does not resolve. (This one is a real 404.)","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Gift card not found","path":"/client/giftcards/wallet/google","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"description":"Too many gift card checks. Try again in a few minutes. — More than 30 checks from one address in 10 minutes (shared with the balance check).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":429,"error":"Too many gift card checks. Try again in a few minutes.","path":"/client/giftcards/wallet/google","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"500":{"$ref":"#/components/responses/ServerError"},"501":{"description":"Google Wallet is not set up for this store — The pass credentials are not configured on the gift card integration.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":501,"error":"Google Wallet is not set up for this store","path":"/client/giftcards/wallet/google","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Gift cards","Client account"]}},"/client/giftcards/me":{"get":{"operationId":"GiftCardClientController_myCards","summary":"My gift cards","description":"The signed-in customer's cards — held, bought, or sent to them — held ones first. A card they gave away shows only its last four. Includes `usableBalance` and the store's top-up product. Never the PIN. The account page and the checkout's \"your gift cards\" picker read this.\n\n#### Signature\n\n```http\nGET /client/giftcards/me () -> The customer's cards\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The customer's cards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A gift card (`sf_gift_card`). The PIN hash is never included.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"serial":{"type":"string","description":"Operator identifier. Every admin endpoint addresses a card by this.","example":"GC-7K2M-9QX4-H1P7"},"code":{"type":"string","description":"Redemption code given to the customer. Distinct from `serial`. Letters exclude 0/O/1/I; separators are ignored on lookup.","example":"YMFB-CDZ2-KDXS-KLM9"},"name":{"type":"string","example":"Holiday gift card"},"type":{"type":"string","enum":["physical","digital","promotional"],"example":"digital","description":"`promotional` cards were never paid for and are not a liability."},"status":{"type":"string","enum":["inactive","active","used","expired","cancelled","suspended"],"example":"active"},"currency":{"type":"string","example":"USD"},"initialAmount":{"type":"number","description":"Value the card was issued with.","example":50},"balance":{"type":"number","description":"Remaining value. Only the ledger moves this.","example":35.5},"batch":{"type":"string","description":"Set when issued as part of a batch.","example":"BATCH-7K2M-9QX4"},"expirationDate":{"type":"string","format":"date-time","description":"Absent means the card never expires — the default for purchased cards."},"purchasedBy":{"type":"string","description":"Buyer email."},"purchaseOrderNumber":{"type":"string","description":"The order that sold it."},"customerId":{"type":"string","description":"The customer whose wallet holds it."},"recipientName":{"type":"string"},"recipientEmail":{"type":"string"},"recipientPhone":{"type":"string","description":"Where the card is texted."},"recipientMessage":{"type":"string"},"messageTemplate":{"type":"string","description":"Email template the card is sent with; its SMS sibling is used for texts. Empty means the platform default (`gift-card-issued`)."},"campaign":{"type":"string","description":"Promotional campaign the card belongs to — reported in GET /storefront/giftcards/insights."},"batchName":{"type":"string","description":"Display name of the batch (POST /storefront/giftcards/batches/{batch}/details)."},"deliverAt":{"type":"string","format":"date-time","description":"When the card email is scheduled to go; absent means no send is scheduled (see POST /storefront/giftcards/{serial}/send)."},"deliveredAt":{"type":"string","format":"date-time"},"restrictions":{"type":"object","description":"Limits on where the card may be spent. Enforced at redemption when the order context is supplied.","properties":{"minPurchase":{"type":"number"},"maxUsePerTransaction":{"type":"number"},"productSkus":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"customerGroups":{"type":"array","items":{"type":"string"}},"excludeDiscountedItems":{"type":"boolean"}}},"uses":{"type":"array","description":"Every movement of value, oldest first.","items":{"type":"object","properties":{"transactionId":{"type":"string","description":"GCT-… reference. A `giftcard` payment is verified by this.","example":"GCT-VB8C-SZ7F-E33V"},"idempotencyKey":{"type":"string","description":"Caller-supplied; a repeat with the same key returns the first result."},"kind":{"type":"string","enum":["redeem","refund","reload","adjust","transfer_in","transfer_out"]},"date":{"type":"string","format":"date-time"},"amount":{"type":"number","description":"Positive takes value off the card, negative puts it on.","example":14.5},"balanceAfter":{"type":"number","example":35.5},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"usedBy":{"type":"string","description":"Email of the redeemer, or `guest`."},"reason":{"type":"string"},"channel":{"type":"string","description":"checkout, pos, invoice, admin, gateway."}}}}}}}}},"total":{"type":"integer"},"usableBalance":{"type":"number"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards","Client account"]}},"/client/giftcards/me/{serial}/share":{"post":{"operationId":"GiftCardClientController_share","summary":"Send part of my card to someone","description":"Moves `amount` from the holder's card onto a new card for someone else (`name`, `email` and/or `phone`, `message`) and sends it to them. Only the card's holder may.\n\n#### Signature\n\n```http\nPOST /client/giftcards/me/{serial}/share () -> The new card and what is left on the holder's\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"serial","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"The new card and what is left on the holder's","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Gift cards","Client account"]}},"/storefront/returns/request":{"post":{"operationId":"ReturnsController_createReturnRequest","summary":"Create a return request","description":"Opens an RMA against an order. The return starts in `requested` and waits for an operator to approve or reject it.\n\nThe order must exist and still be inside its return window — a request against an out-of-window order is refused here rather than at approval, so the customer finds out immediately.\n\nThe customer's identity comes from the signed-in caller. **An anonymous caller is recorded as `guest@example.com`**, which then becomes the only handle on the return, so require sign-in before exposing this.\n\n```\nrequested ──approve──> approved ──ship──> shipped ──receive──> received ──inspect──> inspecting\n    │                                                                  │                     │\n    └──reject──> rejected                                              └────complete─────────┴──> completed\n```\n\nEvery transition checks the exact status before it, so steps cannot be skipped — the one exception is `complete`, which accepts either `received` or `inspecting`. A refund can never exceed the value of the lines accepted at inspection, so completing straight from `received` only allows a refund of 0. `cancel` works from any status except `completed` and `cancelled`.\n\n#### Signature\n\n```http\nPOST /storefront/returns/request (body) -> The created return, with its RMA number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- No check stops a customer requesting a return for more items than they ordered, or requesting twice for the same line — approval is the control point.\n- Anonymous callers are stored as `guest@example.com`, which makes their returns indistinguishable from each other.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORDER_NOT_FOUND | Order <orderNumber> not found | The order number does not resolve in the org. | Check the order number. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/returns/my-returns`\n- `PUT /storefront/returns/{rmaNumber}/approve`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The created return, with its RMA number","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Order <orderNumber> not found — The order number does not resolve in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Order <orderNumber> not found","path":"/storefront/returns/request","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"The order, the reason, and the items coming back.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderNumber","reason","reasonCategory","items"],"properties":{"orderNumber":{"type":"string","description":"Public order number the return is against.","example":"A7K2M9QX4"},"reason":{"type":"string","description":"Free-text reason for the whole request.","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"description":"Structured reason, used for reporting.","example":"damaged_shipping"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"default":"return","description":"What the customer wants — a refund, a swap, a warranty claim or a repair.","example":"return"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}},"description":"The lines being returned, with quantities and condition."},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"description":"The customer's preference. The operator sets the actual method at completion.","example":"original_payment"}}},"examples":{"damaged":{"summary":"Two damaged cans from a four-pack order","value":{"orderNumber":"A7K2M9QX4","reason":"Damaged on arrival","reasonCategory":"damaged_shipping","type":"return","items":[{"sku":"DRK-COLA-330","name":"Cola 330ml","quantity":4,"returnQuantity":2,"price":12,"reason":"Two cans arrived dented","condition":"damaged"}],"refundMethod":"original_payment"}},"exchange":{"summary":"Exchange for the right item","value":{"orderNumber":"A7K2M9QX4","reason":"Received the wrong size","reasonCategory":"wrong_item","type":"exchange","items":[{"sku":"DRK-COLA-500","name":"Cola 500ml","quantity":1,"returnQuantity":1,"price":15,"reason":"Ordered 330ml","condition":"unopened"}],"refundMethod":"exchange"}}}}}}}},"/storefront/returns/my-returns":{"get":{"operationId":"ReturnsController_getMyReturns","summary":"Get the calling customer's returns","description":"Every return request belonging to the signed-in customer, matched on their email. The self-service list for an account page.\n\n#### Signature\n\n```http\nGET /storefront/returns/my-returns () -> The customer's returns\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Matched on the caller's email, so an anonymous caller sees every return recorded against `guest@example.com`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/returns/rma/{rmaNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The customer's returns","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"]}},"/storefront/returns/rma/{rmaNumber}":{"get":{"operationId":"ReturnsController_getByRmaNumber","summary":"Get a return by RMA number","description":"Fetches one return with its items and full timeline — the customer-facing status page for \"where is my return\".\n\nThe RMA number is the only credential: this route does not check the return belongs to the caller. Treat RMA numbers as unguessable.\n\n#### Signature\n\n```http\nGET /storefront/returns/rma/{rmaNumber} (rmaNumber: string) -> The return request\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/rma/{rmaNumber}/ship`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"},{"name":"email","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The return request","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/rma/{rmaNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"]}},"/storefront/returns/rma/{rmaNumber}/ship":{"put":{"operationId":"ReturnsController_markShipped","summary":"Mark a return as shipped","description":"The customer records that they have sent the package back, supplying the carrier and tracking number. The return moves to `shipped`.\n\nIt must be `approved` first — a customer cannot ship a return that has not been authorised, which is the point of the RMA.\n\nWhen the approval did not include a return label, the carrier and tracking sent here become the return's shipping label.\n\n#### Signature\n\n```http\nPUT /storefront/returns/rma/{rmaNumber}/ship (rmaNumber: string, body) -> The shipped return\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/receive`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The shipped return","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/rma/{rmaNumber}/ship","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"How the package was sent back.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["carrier","trackingNumber"],"properties":{"carrier":{"type":"string","example":"ups"},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"}}},"example":{"carrier":"ups","trackingNumber":"1Z999AA10123456784"}}}}}},"/storefront/returns/rma/{rmaNumber}/cancel":{"put":{"operationId":"ReturnsController_cancelByCustomer","summary":"Cancel a return (customer)","description":"The customer withdraws their return request. Available at any point until the return is completed or already cancelled — including after shipping, though at that point the package is already in transit.\n\nThe operator equivalent is `PUT /storefront/returns/{rmaNumber}/cancel`; both behave identically, and this one exists so the customer surface stays under `/rma/`.\n\n#### Signature\n\n```http\nPUT /storefront/returns/rma/{rmaNumber}/cancel (rmaNumber: string, body) -> The cancelled return\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This route does not verify the return belongs to the caller — the RMA number alone is enough to cancel it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The cancelled return","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/rma/{rmaNumber}/cancel","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"Why the customer is cancelling.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Recorded in the timeline.","example":"Decided to keep the item"}}},"example":{"reason":"Decided to keep the item"}}}}}},"/storefront/returns":{"get":{"operationId":"ReturnsController_list","summary":"List returns","description":"Lists return requests across the org with optional filters and paging. The operator queue.\n\n#### Signature\n\n```http\nGET /storefront/returns (status?: string, type?: string, page?: integer, pageSize?: integer) -> A page of returns\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Filter on `status=requested` for the queue of returns awaiting a decision.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/returns/stats`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by lifecycle status.","example":"requested"},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["return","exchange","warranty","repair"]},"example":"return"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of returns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}},"total":{"type":"integer","example":24}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"]}},"/storefront/returns/stats":{"get":{"operationId":"ReturnsController_getStats","summary":"Get return statistics","description":"Aggregate return figures for the org — volume, reasons and refunded value. The read behind a returns dashboard.\n\n#### Signature\n\n```http\nGET /storefront/returns/stats () -> Aggregate return statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Declared before `GET /storefront/returns/{rmaNumber}`-style routes, so `stats` always resolves as this endpoint.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/returns`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Aggregate return statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"]}},"/storefront/returns/order/{orderNumber}":{"get":{"operationId":"ReturnsController_getByOrder","summary":"Get returns for an order","description":"Every return raised against one order. An order can have several — a customer may return different lines at different times.\n\n#### Signature\n\n```http\nGET /storefront/returns/order/{orderNumber} (orderNumber: string) -> The returns raised against that order\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Returns an empty array for an order with no returns, rather than an error.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/returns`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","description":"Public order number.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"The returns raised against that order","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"]}},"/storefront/returns/{rmaNumber}/return-address":{"get":{"operationId":"ReturnsController_returnAddress","summary":"Default return address","description":"The address the Approve step starts with: the return's own, else the address of the location that made the sale, else the first location with a street address. `returnAddress` is null when none has one.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Returns & RMA"]}},"/storefront/returns/{rmaNumber}/refund-options":{"get":{"operationId":"ReturnsController_refundOptions","summary":"Refund options for completing a return","description":"The refunds recorded on the return's order (`refunds`: id, human `reference` such as `1042-R1`, amount, method, the RMA it already settles, `usable`), the order's cash payments with money left to hand back (`cashPayments`), and the accepted value of the return (`approvedValue`). Read-only: nothing is refunded. Complete the return with `transactionId` set to the chosen refund ids (comma-separated).","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Returns & RMA"]}},"/storefront/returns/{rmaNumber}/approve":{"put":{"operationId":"ReturnsController_approve","summary":"Approve a return request","description":"Authorises the return and tells the customer where to send the goods. The return moves to `approved` and `approvedDate` is stamped.\n\n`returnAddress` is required — an approved return with nowhere to ship is not actionable. Include a `shippingLabel` to send the customer a prepaid label; `paidBy` records whether the store or the customer bears the cost. Without one, the customer supplies their own carrier and tracking when they ship.\n\nOnly a return still in `requested` can be approved.\n\n#### Signature\n\n```http\nPUT /storefront/returns/{rmaNumber}/approve (rmaNumber: string, body) -> The approved return\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/reject`\n- `PUT /storefront/returns/rma/{rmaNumber}/ship`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The approved return","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/{rmaNumber}/approve","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"Where to ship the goods, and optionally a prepaid label.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["returnAddress"],"properties":{"returnAddress":{"type":"object","required":["name","street","city","state","postalCode","country"],"properties":{"name":{"type":"string","example":"Acme Returns"},"street":{"type":"string","example":"4 Warehouse Way"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"postalCode":{"type":"string","example":"07102"},"country":{"type":"string","example":"US"}}},"shippingLabel":{"type":"object","description":"A prepaid return label. Omit to have the customer arrange and pay for shipping.","required":["carrier","trackingNumber","paidBy"],"properties":{"carrier":{"type":"string","example":"ups"},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"labelUrl":{"type":"string","description":"Where the customer downloads the label.","example":"https://cdn.appmint.io/labels/rma-4821.pdf"},"cost":{"type":"number","example":8.5},"paidBy":{"type":"string","enum":["customer","store"],"example":"store"}}},"notes":{"type":"string","description":"Recorded in the timeline.","example":"Approved — damaged in transit, our cost"}}},"examples":{"prepaid":{"summary":"Approve with a prepaid label","value":{"returnAddress":{"name":"Acme Returns","street":"4 Warehouse Way","city":"Newark","state":"NJ","postalCode":"07102","country":"US"},"shippingLabel":{"carrier":"ups","trackingNumber":"1Z999AA10123456784","labelUrl":"https://cdn.appmint.io/labels/rma-4821.pdf","cost":8.5,"paidBy":"store"}}},"customerPays":{"summary":"Approve, customer arranges shipping","value":{"returnAddress":{"name":"Acme Returns","street":"4 Warehouse Way","city":"Newark","state":"NJ","postalCode":"07102","country":"US"},"notes":"Customer to return at own cost per policy"}}}}}}}},"/storefront/returns/{rmaNumber}/reject":{"put":{"operationId":"ReturnsController_reject","summary":"Reject a return request","description":"Declines the return. The reason is recorded in the timeline and is what the customer is told.\n\n**Rejection is terminal.** There is no transition back to `requested`, so a rejected return cannot later be approved — the customer must raise a new request.\n\n#### Signature\n\n```http\nPUT /storefront/returns/{rmaNumber}/reject (rmaNumber: string, body) -> The rejected return\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Irreversible — a rejected return has no path back into the lifecycle.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/approve`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The rejected return","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/{rmaNumber}/reject","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"Why the return is being declined.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Shown to the customer and recorded in the timeline.","example":"Outside the 30-day return window"}}},"example":{"reason":"Outside the 30-day return window"}}}}}},"/storefront/returns/{rmaNumber}/receive":{"put":{"operationId":"ReturnsController_markReceived","summary":"Mark a return as received","description":"Records that the package has arrived at the warehouse. The return moves to `received` and `receivedDate` is stamped.\n\nThe return must be `shipped` first, so a package cannot be received before the customer says it was sent. If a customer returns goods without marking them shipped, mark it shipped on their behalf first.\n\n#### Signature\n\n```http\nPUT /storefront/returns/{rmaNumber}/receive (rmaNumber: string, body) -> The received return\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/inspect`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The received return","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/{rmaNumber}/receive","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"Optional receiving notes.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","default":"Package received","description":"Recorded in the timeline.","example":"Box arrived crushed, contents intact"}}},"example":{"notes":"Box arrived crushed, contents intact"}}}}}},"/storefront/returns/{rmaNumber}/inspect":{"put":{"operationId":"ReturnsController_inspect","summary":"Record inspection results","description":"Records what the warehouse actually found: one decision for **every** returned line — accepted for refund or not — and the condition it arrived in. The return moves to `inspecting` and `refundAmount` is set to the value of the accepted lines (price × return quantity), which is the most `complete` will refund.\n\nLines are matched by `sku`; when the same SKU appears on more than one line, identify each with `itemIndex`.\n\n#### Signature\n\n```http\nPUT /storefront/returns/{rmaNumber}/inspect (rmaNumber: string, body) -> The return with inspection results and refundAmount\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/complete`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The return with inspection results and refundAmount","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/{rmaNumber}/inspect","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"Per-line findings.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","description":"Exactly one entry per returned line.","items":{"type":"object","required":["sku","approved","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"itemIndex":{"type":"integer","description":"Position of the line on the return; required when a SKU repeats."},"approved":{"type":"boolean","description":"Accepted for refund.","example":true},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as found.","example":"damaged"},"notes":{"type":"string","example":"Both cans dented, matches the claim"}}}},"overallNotes":{"type":"string","example":"Consistent with shipping damage"}}},"example":{"items":[{"sku":"DRK-COLA-330","approved":true,"condition":"damaged","notes":"Both cans dented, matches the claim"}],"overallNotes":"Consistent with shipping damage"}}}}}},"/storefront/returns/{rmaNumber}/complete":{"put":{"operationId":"ReturnsController_complete","summary":"Complete a return and refund","description":"Closes the return (`completed`, `completedDate`) and records the refund. **The refund can never exceed the value of the lines accepted at inspection** — completing straight from `received` (no inspection) therefore only allows `amount: 0`.\n\n- `store_credit` / `giftcard`: this call moves the money — onto `giftcardSerial` when given, otherwise a new digital card is issued to the customer and emailed. `refundStatus` is `completed`.\n- `original_payment` / `exchange`: the money is moved elsewhere; pass the reference in `transactionId`. Recorded POS cash refund ids (comma-separated) are verified — they must be complete and total the amount — and mark the refund `completed`; any other reference is recorded as-is (`refundStatus: recorded`), unverified.\n\nWhen completed returns now cover every unit sold, the order becomes `returned`.\n\n#### Signature\n\n```http\nPUT /storefront/returns/{rmaNumber}/complete (rmaNumber: string, body) -> The completed return\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Completion is terminal: a completed return cannot be cancelled.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/inspect`\n- `POST /storefront/giftcards/{serial}/refund`\n- `POST /storefront/pos/tab/{id}/refund`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The completed return","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/{rmaNumber}/complete","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"How much to refund, and by what route.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","method"],"properties":{"amount":{"type":"number","description":"Non-negative, at most the accepted value.","example":24},"method":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"store_credit"},"transactionId":{"type":"string","description":"External refund reference, or recorded POS cash refund ids (comma-separated). Required for a non-zero refund not credited to a card.","example":"re_3PabcXYZ"},"giftcardSerial":{"type":"string","description":"Card to credit for giftcard / store_credit. Omit to issue a new card.","example":"GC-4821-9917"}}},"examples":{"credit":{"summary":"Store credit on a new card","value":{"amount":24,"method":"store_credit"}},"giftcard":{"summary":"Back onto an existing gift card","value":{"amount":24,"method":"giftcard","giftcardSerial":"GC-4821-9917"}},"original":{"summary":"Refunded at the gateway, reference recorded","value":{"amount":24,"method":"original_payment","transactionId":"re_3PabcXYZ"}}}}}}}},"/storefront/returns/{rmaNumber}/notes":{"post":{"operationId":"ReturnsController_addNote","summary":"Add a note to a return","description":"Appends an internal note to the return timeline. Available in any status, including after completion, so the record can always be annotated.\n\n#### Signature\n\n```http\nPOST /storefront/returns/{rmaNumber}/notes (rmaNumber: string, body) -> The return with the note appended\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Notes are internal. They sit in the same timeline the customer-facing status page reads, so do not put anything in them you would not show the customer.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/returns/rma/{rmaNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"201":{"description":"The return with the note appended","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/{rmaNumber}/notes","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"The note to add.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string","description":"Appended to the timeline, attributed to the caller.","example":"Customer called to chase — advised 3 working days"}}},"example":{"note":"Customer called to chase — advised 3 working days"}}}}}},"/storefront/returns/{rmaNumber}/cancel":{"put":{"operationId":"ReturnsController_cancel","summary":"Cancel a return (operator)","description":"Cancels a return from the operator side. Works from any status except `completed` and `cancelled`.\n\nIdentical in behaviour to the customer route `PUT /storefront/returns/rma/{rmaNumber}/cancel`; the two exist so the customer surface stays namespaced under `/rma/`.\n\n#### Signature\n\n```http\nPUT /storefront/returns/{rmaNumber}/cancel (rmaNumber: string, body) -> The cancelled return\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RETURN_NOT_FOUND | Return <rmaNumber> not found | No return in the org has that RMA number. | Check the RMA number. Note this is a `400`, not a `404` — the whole service raises 400 for missing records. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/rma/{rmaNumber}/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rmaNumber","required":true,"in":"path","description":"RMA number.","schema":{"type":"string"},"example":"RMA-4821"}],"responses":{"200":{"description":"The cancelled return","content":{"application/json":{"schema":{"type":"object","description":"A return request (`sf_return`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rmaNumber":{"type":"string","description":"Return authorisation number — the identifier for every endpoint here.","example":"RMA-4821"},"orderNumber":{"type":"string","example":"A7K2M9QX4"},"status":{"type":"string","enum":["requested","approved","rejected","shipped","received","inspecting","completed","cancelled"],"example":"approved"},"type":{"type":"string","enum":["return","exchange","warranty","repair"],"example":"return"},"reason":{"type":"string","example":"Damaged on arrival"},"reasonCategory":{"type":"string","enum":["defective","not_as_described","wrong_item","changed_mind","damaged_shipping","other"],"example":"damaged_shipping"},"customerEmail":{"type":"string","example":"ada@example.com"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","required":["sku","name","quantity","returnQuantity","price","reason","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"name":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"How many were originally ordered.","example":4},"returnQuantity":{"type":"number","description":"How many are being returned.","example":2},"price":{"type":"number","description":"Unit price paid.","example":12},"reason":{"type":"string","description":"Per-item reason, which can differ from the request-level one.","example":"Two cans arrived dented"},"condition":{"type":"string","enum":["unopened","opened","damaged","defective","wrong_item"],"description":"Condition as the customer describes it. The inspection step records the real one.","example":"damaged"}}}},"refundMethod":{"type":"string","enum":["original_payment","store_credit","exchange","giftcard"],"example":"original_payment"},"refundAmount":{"type":"number","description":"Set when the return completes.","example":24},"returnAddress":{"type":"object","additionalProperties":true,"description":"Where the customer ships to. Set at approval."},"shippingLabel":{"type":"object","additionalProperties":true,"description":"Return label, from approval or from the customer marking it shipped."},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Append-only history of every transition and note."},"requestedDate":{"type":"string","format":"date-time"},"approvedDate":{"type":"string","format":"date-time"},"shippedDate":{"type":"string","format":"date-time"},"receivedDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Return <rmaNumber> not found — No return in the org has that RMA number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Return <rmaNumber> not found","path":"/storefront/returns/{rmaNumber}/cancel","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Returns"],"requestBody":{"description":"Why the return is being cancelled.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Recorded in the timeline.","example":"Duplicate request — superseded by RMA-4822"}}},"example":{"reason":"Duplicate request — superseded by RMA-4822"}}}}}},"/storefront/inventory/intakes":{"get":{"operationId":"InventoryIntakeController_list","summary":"List vendor stock intakes","description":"Paged, newest first. status / vendorId / locationId filters; q searches number, vendor, reference and SKU over every intake.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"enum":["pending","received","cancelled"],"type":"string"}},{"name":"vendorId","required":true,"in":"query","schema":{"type":"string"}},{"name":"locationId","required":true,"in":"query","schema":{"type":"string"}},{"name":"q","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Inventory"]},"post":{"operationId":"InventoryIntakeController_create","summary":"Record a vendor delivery (pending until received)","description":"{ vendorId | vendorName, locationId, items: [{ sku, quantity, unitCost }], expectedDate?, reference?, notes? }","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Inventory"]}},"/storefront/inventory/intakes/{id}":{"get":{"operationId":"InventoryIntakeController_get","summary":"Get one intake (by id or intake number)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Inventory"]}},"/storefront/inventory/intakes/{id}/receive":{"put":{"operationId":"InventoryIntakeController_receive","summary":"Receive an intake","description":"Adds every line to stock at the weighted-average cost and records one approved inventory bill (Dr Inventory / Cr Accounts payable) owed to the vendor. Safe to repeat.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Inventory"]}},"/storefront/inventory/intakes/{id}/cancel":{"put":{"operationId":"InventoryIntakeController_cancel","summary":"Cancel a pending intake (reason required)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Inventory"]}},"/storefront/inventory/sku/{sku}":{"get":{"operationId":"InventoryController_getInventoryBySku","summary":"Get inventory for a SKU across locations","description":"Every stock level held for one SKU, one entry per location. This is the read for \"where can we ship this from\" — sum `availableQuantity` across the entries for total sellable stock.\n\n#### Signature\n\n```http\nGET /storefront/inventory/sku/{sku} (sku: string) -> Stock levels per location\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A location where the SKU has never been stocked has no record at all, so it is absent rather than reported as zero.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/inventory/sku/{sku}/location/{locationId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"sku","required":true,"in":"path","description":"Product SKU.","schema":{"type":"string"},"example":"DRK-COLA-330"}],"responses":{"200":{"description":"Stock levels per location","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory/sku/{sku}/location/{locationId}":{"get":{"operationId":"InventoryController_getInventory","summary":"Get inventory for a SKU at one location","description":"The stock level for one SKU at one location, with its on-hand, reserved and available quantities.\n\n#### Signature\n\n```http\nGET /storefront/inventory/sku/{sku}/location/{locationId} (sku: string, locationId: string) -> The stock level, or null when the SKU has never been stocked there\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Returns `null` with a `200` when there is no record — the write endpoints raise a `400` for the same condition.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"sku","required":true,"in":"path","description":"Product SKU.","schema":{"type":"string"},"example":"DRK-COLA-330"},{"name":"locationId","required":true,"in":"path","description":"Location id.","schema":{"type":"string"},"example":"loc_downtown"}],"responses":{"200":{"description":"The stock level, or null when the SKU has never been stocked there","content":{"application/json":{"schema":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory/location/{locationId}":{"get":{"operationId":"InventoryController_getInventoryByLocation","summary":"List inventory at a location","description":"Every stock level held at one location, paged. Set `lowStock=true` to narrow it to items at or below their reorder point — the picking list for a restock.\n\n#### Signature\n\n```http\nGET /storefront/inventory/location/{locationId} (locationId: string, lowStock?: boolean, page?: integer, pageSize?: integer) -> A page of stock levels\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/inventory/alerts/low-stock`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"locationId","required":true,"in":"path","description":"Location id.","schema":{"type":"string"},"example":"loc_downtown"},{"name":"lowStock","required":false,"in":"query","description":"Only items below their reorder point. Only the exact string `true` enables it.","schema":{"type":"boolean","default":false},"example":true},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of stock levels","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}},"total":{"type":"integer","example":340}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory/alerts/low-stock":{"get":{"operationId":"InventoryController_getLowStockAlerts","summary":"Get low stock alerts","description":"Every SKU at or below its reorder point, across the org or at one location. The reorder worklist.\n\n#### Signature\n\n```http\nGET /storefront/inventory/alerts/low-stock (locationId?: string) -> Stock levels below their reorder point\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A SKU with no `reorderPoint` set cannot trigger an alert.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/inventory/location/{locationId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"locationId","required":false,"in":"query","description":"Restrict to one location. Omit for the whole org.","schema":{"type":"string"},"example":"loc_downtown"}],"responses":{"200":{"description":"Stock levels below their reorder point","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory/stats":{"get":{"operationId":"InventoryController_getStats","summary":"Get inventory statistics","description":"Aggregate stock figures for the org or one location — totals, value and how many SKUs are below their reorder point.\n\n#### Signature\n\n```http\nGET /storefront/inventory/stats (locationId?: string) -> Aggregate inventory statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/inventory/alerts/low-stock`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"locationId","required":false,"in":"query","description":"Restrict to one location.","schema":{"type":"string"},"example":"loc_downtown"}],"responses":{"200":{"description":"Aggregate inventory statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory/sku/{sku}/transactions":{"get":{"operationId":"InventoryController_getTransactionHistory","summary":"Get transaction history for a SKU","description":"The movement ledger for a SKU — every adjustment, reservation, sale, return, count and transfer, with the quantity before and after and the reference that caused it.\n\nThis is the audit trail: when stock does not match expectations, this is where the discrepancy is found.\n\n#### Signature\n\n```http\nGET /storefront/inventory/sku/{sku}/transactions (sku: string, locationId?: string, page?: integer, pageSize?: integer) -> A page of movements\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A `reserve` movement records `previousQuantity` and `newQuantity` as the same value — reserving moves stock between the reserved and available buckets without changing what is on hand.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory/adjust`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"sku","required":true,"in":"path","description":"Product SKU.","schema":{"type":"string"},"example":"DRK-COLA-330"},{"name":"locationId","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one location.","example":"loc_downtown"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of movements","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"type":{"type":"string","description":"`adjustment`, `reserve`, `release`, `sale`, `return`, `count`, `transfer`.","example":"sale"},"quantity":{"type":"number","description":"Signed — negative for stock leaving.","example":-2},"previousQuantity":{"type":"number","example":122},"newQuantity":{"type":"number","example":120},"referenceType":{"type":"string","example":"order"},"referenceId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"}}}},"total":{"type":"integer","example":412}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory":{"post":{"operationId":"InventoryController_setInventory","summary":"Set inventory for a SKU at a location","description":"Creates or replaces the stock record for one SKU at one location. This is the endpoint that establishes a level in the first place — every other write requires the record to exist already.\n\nIt **sets** rather than adjusts, so it overwrites the current quantity outright. Use `POST /storefront/inventory/adjust` for a relative change with a recorded reason, and `POST /storefront/inventory/count` to reconcile against a physical count.\n\n#### Signature\n\n```http\nPOST /storefront/inventory (body) -> The stock level\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Overwrites rather than accumulates. Calling it twice with the same quantity leaves that quantity, not double.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory/adjust`\n- `POST /storefront/inventory/count`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The stock level","content":{"application/json":{"schema":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"The stock level to set. `sku` and `locationId` identify it.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","locationId"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}},"example":{"sku":"DRK-COLA-330","locationId":"loc_downtown","quantity":120,"reorderPoint":25,"reorderQuantity":200}}}}}},"/storefront/inventory/adjust":{"post":{"operationId":"InventoryController_adjustInventory","summary":"Adjust inventory","description":"Applies a relative change to on-hand stock and records why. Send a positive `adjustment` to add stock and a negative one to remove it.\n\nA `reason` is required — an unexplained stock change is the thing that makes a ledger useless. Attach `referenceType` and `referenceId` to link the movement to whatever caused it.\n\nThe adjustment is refused if it would take stock below zero.\n\n#### Signature\n\n```http\nPOST /storefront/inventory/adjust (body) -> The updated stock level\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Not idempotent: each call applies the change again.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVENTORY_NOT_FOUND | Inventory not found for <sku> at <locationId> | No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero. | Create the level first with `POST /storefront/inventory`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory/count`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The updated stock level","content":{"application/json":{"schema":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}},"400":{"description":"Inventory not found for <sku> at <locationId> — No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Inventory not found for <sku> at <locationId>","path":"/storefront/inventory/adjust","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"The change, and why.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","locationId","adjustment","reason"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","example":"loc_downtown"},"adjustment":{"type":"number","description":"Signed change. Negative removes stock.","example":-3},"reason":{"type":"string","description":"Recorded on the movement.","example":"Damaged in the stockroom"},"referenceType":{"type":"string","description":"What caused it, e.g. `order`, `return`, `stocktake`.","example":"stocktake"},"referenceId":{"type":"string","description":"Identifier of that thing.","example":"ST-2026-08"},"idempotencyKey":{"type":"string","description":"Optional. Sending the same key again (e.g. after a timeout) returns the first result with `alreadyApplied: true` instead of moving stock twice.","example":"adj-7f3c9a"}}},"examples":{"shrinkage":{"summary":"Write off damaged stock","value":{"sku":"DRK-COLA-330","locationId":"loc_downtown","adjustment":-3,"reason":"Damaged in the stockroom"}},"delivery":{"summary":"Book in a delivery","value":{"sku":"DRK-COLA-330","locationId":"loc_downtown","adjustment":200,"reason":"Supplier delivery","referenceType":"purchase_order","referenceId":"PO-9912"}}}}}}}},"/storefront/inventory/reserve":{"post":{"operationId":"InventoryController_reserveInventory","summary":"Reserve inventory for an order","description":"Commits stock to an order without shipping it: `reservedQuantity` goes up and `availableQuantity` comes down by the same amount. **On-hand `quantity` does not change** — the goods are still on the shelf, just no longer sellable to anyone else.\n\nRefused when there is not enough available, and the error reports exactly how much there is.\n\nEvery reservation must eventually be released or fulfilled, or the stock stays committed forever.\n\n#### Signature\n\n```http\nPOST /storefront/inventory/reserve (body) -> The updated stock level\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Not idempotent: a retry reserves the quantity a second time. Nothing links a reservation to its order beyond the ledger entry, so a duplicate cannot be detected automatically.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVENTORY_NOT_FOUND | Inventory not found for <sku> at <locationId> | No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero. | Create the level first with `POST /storefront/inventory`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory/release`\n- `POST /storefront/inventory/fulfill`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The updated stock level","content":{"application/json":{"schema":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}},"400":{"description":"Inventory not found for <sku> at <locationId> — No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Inventory not found for <sku> at <locationId>","path":"/storefront/inventory/reserve","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"What to reserve, and for which order.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","locationId","quantity","orderId"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","example":"loc_downtown"},"quantity":{"type":"number","example":2},"orderId":{"type":"string","description":"Order this movement belongs to. Recorded on the transaction.","example":"66f1a2b3c4d5e6f708192a3b"}}},"example":{"sku":"DRK-COLA-330","locationId":"loc_downtown","quantity":2,"orderId":"66f1a2b3c4d5e6f708192a3b"}}}}}},"/storefront/inventory/release":{"post":{"operationId":"InventoryController_releaseReservation","summary":"Release a reservation","description":"Undoes a reservation when an order is cancelled: `reservedQuantity` comes down and `availableQuantity` goes back up. On-hand quantity is untouched.\n\nCall this whenever a reserved order does not ship, or the stock stays committed and invisible to other customers.\n\n#### Signature\n\n```http\nPOST /storefront/inventory/release (body) -> The updated stock level\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Releasing more than was reserved is not rejected — reserved stock is floored at zero, which silently inflates available stock. Release exactly what you reserved.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVENTORY_NOT_FOUND | Inventory not found for <sku> at <locationId> | No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero. | Create the level first with `POST /storefront/inventory`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory/reserve`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The updated stock level","content":{"application/json":{"schema":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}},"400":{"description":"Inventory not found for <sku> at <locationId> — No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Inventory not found for <sku> at <locationId>","path":"/storefront/inventory/release","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"What to release, and from which order.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","locationId","quantity","orderId"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","example":"loc_downtown"},"quantity":{"type":"number","example":2},"orderId":{"type":"string","description":"Order this movement belongs to. Recorded on the transaction.","example":"66f1a2b3c4d5e6f708192a3b"}}},"example":{"sku":"DRK-COLA-330","locationId":"loc_downtown","quantity":2,"orderId":"66f1a2b3c4d5e6f708192a3b"}}}}}},"/storefront/inventory/fulfill":{"post":{"operationId":"InventoryController_fulfillInventory","summary":"Fulfill inventory after shipment","description":"Takes stock off the shelf once an order ships. On-hand `quantity` comes down by the shipped amount, the matching reservation is cleared, and `availableQuantity` is recomputed.\n\nThis is the step that makes a sale permanent — the movement is recorded as type `sale`.\n\nRefused if it would take on-hand stock below zero. The check runs before anything is written, so a rejected fulfilment leaves the record untouched.\n\n#### Signature\n\n```http\nPOST /storefront/inventory/fulfill (body) -> The updated stock level\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Fulfilling clears the reservation as part of the same call — do not also release it, or available stock will be overstated.\n- Reserved quantity is floored at zero, so fulfilling stock that was never reserved still works and simply reduces on-hand.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVENTORY_NOT_FOUND | Inventory not found for <sku> at <locationId> | No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero. | Create the level first with `POST /storefront/inventory`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory/reserve`\n- `POST /storefront/inventory/return`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The updated stock level","content":{"application/json":{"schema":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}},"400":{"description":"Inventory not found for <sku> at <locationId> — No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Inventory not found for <sku> at <locationId>","path":"/storefront/inventory/fulfill","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"What shipped, and for which order.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","locationId","quantity","orderId"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","example":"loc_downtown"},"quantity":{"type":"number","example":2},"orderId":{"type":"string","description":"Order this movement belongs to. Recorded on the transaction.","example":"66f1a2b3c4d5e6f708192a3b"}}},"example":{"sku":"DRK-COLA-330","locationId":"loc_downtown","quantity":2,"orderId":"66f1a2b3c4d5e6f708192a3b"}}}}}},"/storefront/inventory/return":{"post":{"operationId":"InventoryController_returnToStock","summary":"Return stock from a return","description":"Books returned goods back in. **`condition` decides whether stock actually moves:**\n\n- `restockable` — on-hand and available both go up by `quantity`.\n- `damaged` — **no stock change at all.** The movement is still recorded, so the return is auditable, but the goods are written off rather than made sellable.\n\nThat asymmetry is easy to miss: a `200` on a `damaged` return does not mean anything was added.\n\n#### Signature\n\n```http\nPOST /storefront/inventory/return (body) -> The stock level — unchanged when the condition was `damaged`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVENTORY_NOT_FOUND | Inventory not found for <sku> at <locationId> | No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero. | Create the level first with `POST /storefront/inventory`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/returns/{rmaNumber}/complete`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The stock level — unchanged when the condition was `damaged`","content":{"application/json":{"schema":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}}}}},"400":{"description":"Inventory not found for <sku> at <locationId> — No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Inventory not found for <sku> at <locationId>","path":"/storefront/inventory/return","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"What came back, from which return, and in what state.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","locationId","quantity","returnId","condition"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","example":"loc_downtown"},"quantity":{"type":"number","example":2},"returnId":{"type":"string","description":"RMA the goods came back under.","example":"RMA-4821"},"condition":{"type":"string","enum":["restockable","damaged"],"description":"`damaged` records the movement without changing stock.","example":"restockable"}}},"examples":{"restock":{"summary":"Goods fit to resell","value":{"sku":"DRK-COLA-330","locationId":"loc_downtown","quantity":2,"returnId":"RMA-4821","condition":"restockable"}},"writeOff":{"summary":"Damaged goods","description":"Recorded for audit; stock is not increased.","value":{"sku":"DRK-COLA-330","locationId":"loc_downtown","quantity":2,"returnId":"RMA-4821","condition":"damaged"}}}}}}}},"/storefront/inventory/count":{"post":{"operationId":"InventoryController_performCount","summary":"Record a physical count","description":"Reconciles the system against a physical stocktake. On-hand quantity is **set** to `countedQuantity`, `availableQuantity` is recomputed from it, and `lastCountDate` is stamped.\n\nThe response includes the `variance` — counted minus previous — which is the number a stocktake report actually cares about. A negative variance is shrinkage.\n\nReserved quantity is left alone: a count measures what is on the shelf, not what is promised to orders.\n\n#### Signature\n\n```http\nPOST /storefront/inventory/count (body) -> The reconciled level and the variance\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A count can take available stock negative if more is reserved than was counted — the count is trusted as the truth and is not clamped.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVENTORY_NOT_FOUND | Inventory not found for <sku> at <locationId> | No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero. | Create the level first with `POST /storefront/inventory`. Note this is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/inventory/adjust`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The reconciled level and the variance","content":{"application/json":{"schema":{"type":"object","properties":{"inventory":{"type":"object","description":"An inventory level (`sf_inventory`) for one SKU at one location.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","description":"Warehouse or store this level belongs to.","example":"loc_downtown"},"quantity":{"type":"number","description":"Physically on hand, including units reserved for orders.","example":120},"reservedQuantity":{"type":"number","description":"Committed to orders but not yet shipped.","example":20},"availableQuantity":{"type":"number","description":"`quantity` minus `reservedQuantity` — what can still be sold.","example":100},"reorderPoint":{"type":"number","description":"Level at or below which the SKU appears in low-stock alerts.","example":25},"reorderQuantity":{"type":"number","description":"Suggested restock amount.","example":200},"lastCountDate":{"type":"string","format":"date-time","description":"When a physical count was last recorded."}}}}},"variance":{"type":"number","description":"`countedQuantity` minus the previous on-hand. Negative means stock was missing.","example":-3}}},"example":{"inventory":{"data":{"sku":"DRK-COLA-330","quantity":117,"reservedQuantity":20,"availableQuantity":97}},"variance":-3}}}},"400":{"description":"Inventory not found for <sku> at <locationId> — No inventory record exists for that SKU at that location. A SKU that has never been stocked at a location has no record — it is not treated as zero.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Inventory not found for <sku> at <locationId>","path":"/storefront/inventory/count","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"What was counted.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","locationId","countedQuantity"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"locationId":{"type":"string","example":"loc_downtown"},"countedQuantity":{"type":"number","description":"Units physically present. Becomes the new on-hand quantity.","example":117},"notes":{"type":"string","description":"Recorded on the movement.","example":"Quarterly stocktake"}}},"example":{"sku":"DRK-COLA-330","locationId":"loc_downtown","countedQuantity":117,"notes":"Quarterly stocktake"}}}}}},"/storefront/inventory/transfers":{"post":{"operationId":"InventoryController_createTransfer","summary":"Create an inventory transfer","description":"Opens a transfer of stock between two locations. The transfer starts `pending`.\n\nSource stock is checked up front: if any line exceeds what the source location holds, the whole transfer is refused rather than created partially.\n\n#### Signature\n\n```http\nPOST /storefront/inventory/transfers (body) -> The created transfer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INSUFFICIENT_SOURCE_INVENTORY | Insufficient inventory for <sku> at source location | A line asks for more than the source location holds. | Check source levels first. The whole transfer is refused — no partial transfer is created. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/inventory/transfers/{transferId}/ship`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The created transfer","content":{"application/json":{"schema":{"type":"object","description":"An inventory transfer (`sf_inventory_transfer`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"transferId":{"type":"string","example":"TR-4821"},"status":{"type":"string","enum":["pending","in_transit","completed","cancelled"],"example":"pending"},"fromLocationId":{"type":"string","example":"loc_warehouse"},"fromLocationName":{"type":"string","example":"Central warehouse"},"toLocationId":{"type":"string","example":"loc_downtown"},"toLocationName":{"type":"string","example":"Downtown store"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"productName":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"Quantity sent.","example":48},"receivedQuantity":{"type":"number","description":"Quantity confirmed on receipt. Set at the receiving end.","example":46}}}},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"carrier":{"type":"string","example":"ups"},"notes":{"type":"string"}}}}}}}},"400":{"description":"Insufficient inventory for <sku> at source location — A line asks for more than the source location holds.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Insufficient inventory for <sku> at source location","path":"/storefront/inventory/transfers","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"Where the stock is going, and what.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromLocationId","toLocationId","items"],"properties":{"fromLocationId":{"type":"string","example":"loc_warehouse"},"fromLocationName":{"type":"string","description":"Display name, stored for reporting.","example":"Central warehouse"},"toLocationId":{"type":"string","example":"loc_downtown"},"toLocationName":{"type":"string","example":"Downtown store"},"items":{"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"productName":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":48}}}},"notes":{"type":"string","example":"Weekly replenishment"}}},"example":{"fromLocationId":"loc_warehouse","toLocationId":"loc_downtown","items":[{"sku":"DRK-COLA-330","productName":"Cola 330ml","quantity":48}],"notes":"Weekly replenishment"}}}}},"get":{"operationId":"InventoryController_listTransfers","summary":"List inventory transfers","description":"Lists transfers with optional filters and paging. Filter by `status=in_transit` for stock currently on the road.\n\n#### Signature\n\n```http\nGET /storefront/inventory/transfers (status?: string, fromLocationId?: string, toLocationId?: string, page?: integer, pageSize?: integer) -> A page of transfers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/inventory/transfers/{transferId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","in_transit","completed","cancelled"]},"example":"in_transit"},{"name":"fromLocationId","required":false,"in":"query","schema":{"type":"string"},"example":"loc_warehouse"},{"name":"toLocationId","required":false,"in":"query","schema":{"type":"string"},"example":"loc_downtown"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of transfers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"An inventory transfer (`sf_inventory_transfer`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"transferId":{"type":"string","example":"TR-4821"},"status":{"type":"string","enum":["pending","in_transit","completed","cancelled"],"example":"pending"},"fromLocationId":{"type":"string","example":"loc_warehouse"},"fromLocationName":{"type":"string","example":"Central warehouse"},"toLocationId":{"type":"string","example":"loc_downtown"},"toLocationName":{"type":"string","example":"Downtown store"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"productName":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"Quantity sent.","example":48},"receivedQuantity":{"type":"number","description":"Quantity confirmed on receipt. Set at the receiving end.","example":46}}}},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"carrier":{"type":"string","example":"ups"},"notes":{"type":"string"}}}}}},"total":{"type":"integer","example":8}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory/transfers/{transferId}":{"get":{"operationId":"InventoryController_getTransfer","summary":"Get an inventory transfer","description":"Fetches one transfer with its lines, including the received quantities once it has been receipted.\n\n#### Signature\n\n```http\nGET /storefront/inventory/transfers/{transferId} (transferId: string) -> The transfer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | TRANSFER_NOT_FOUND | Transfer <transferId> not found | No transfer in the org has that id. | Check the id with `GET /storefront/inventory/transfers`. This is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/inventory/transfers`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"transferId","required":true,"in":"path","description":"Transfer id.","schema":{"type":"string"},"example":"TR-4821"}],"responses":{"200":{"description":"The transfer","content":{"application/json":{"schema":{"type":"object","description":"An inventory transfer (`sf_inventory_transfer`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"transferId":{"type":"string","example":"TR-4821"},"status":{"type":"string","enum":["pending","in_transit","completed","cancelled"],"example":"pending"},"fromLocationId":{"type":"string","example":"loc_warehouse"},"fromLocationName":{"type":"string","example":"Central warehouse"},"toLocationId":{"type":"string","example":"loc_downtown"},"toLocationName":{"type":"string","example":"Downtown store"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"productName":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"Quantity sent.","example":48},"receivedQuantity":{"type":"number","description":"Quantity confirmed on receipt. Set at the receiving end.","example":46}}}},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"carrier":{"type":"string","example":"ups"},"notes":{"type":"string"}}}}}}}},"400":{"description":"Transfer <transferId> not found — No transfer in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Transfer <transferId> not found","path":"/storefront/inventory/transfers/{transferId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"]}},"/storefront/inventory/transfers/{transferId}/ship":{"put":{"operationId":"InventoryController_shipTransfer","summary":"Ship an inventory transfer","description":"Marks a pending transfer as dispatched and records the carrier and tracking. The transfer moves to `in_transit` and the stock leaves the source location.\n\nOnly a `pending` transfer can be shipped.\n\n#### Signature\n\n```http\nPUT /storefront/inventory/transfers/{transferId}/ship (transferId: string, body) -> The shipped transfer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | TRANSFER_NOT_FOUND | Transfer <transferId> not found | No transfer in the org has that id. | Check the id with `GET /storefront/inventory/transfers`. This is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/inventory/transfers/{transferId}/receive`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"transferId","required":true,"in":"path","description":"Transfer id.","schema":{"type":"string"},"example":"TR-4821"}],"responses":{"200":{"description":"The shipped transfer","content":{"application/json":{"schema":{"type":"object","description":"An inventory transfer (`sf_inventory_transfer`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"transferId":{"type":"string","example":"TR-4821"},"status":{"type":"string","enum":["pending","in_transit","completed","cancelled"],"example":"pending"},"fromLocationId":{"type":"string","example":"loc_warehouse"},"fromLocationName":{"type":"string","example":"Central warehouse"},"toLocationId":{"type":"string","example":"loc_downtown"},"toLocationName":{"type":"string","example":"Downtown store"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"productName":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"Quantity sent.","example":48},"receivedQuantity":{"type":"number","description":"Quantity confirmed on receipt. Set at the receiving end.","example":46}}}},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"carrier":{"type":"string","example":"ups"},"notes":{"type":"string"}}}}}}}},"400":{"description":"Transfer <transferId> not found — No transfer in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Transfer <transferId> not found","path":"/storefront/inventory/transfers/{transferId}/ship","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"How the stock was dispatched.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["trackingNumber","carrier"],"properties":{"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"carrier":{"type":"string","example":"ups"}}},"example":{"trackingNumber":"1Z999AA10123456784","carrier":"ups"}}}}}},"/storefront/inventory/transfers/{transferId}/receive":{"put":{"operationId":"InventoryController_receiveTransfer","summary":"Receive an inventory transfer","description":"Books a transfer in at the destination. The received quantities are recorded per line and added to the destination's stock, and the transfer moves to `completed`.\n\n**Receive what actually arrived, not what was sent.** `receivedQuantity` can be lower than the shipped quantity, and the difference is the shrinkage in transit — which the transfer record then preserves as evidence.\n\nOnly an `in_transit` transfer can be received.\n\n#### Signature\n\n```http\nPUT /storefront/inventory/transfers/{transferId}/receive (transferId: string, body) -> The completed transfer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A line omitted from `receivedItems` is not booked in — send an entry for every line, using `0` for one that did not arrive.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | TRANSFER_NOT_FOUND | Transfer <transferId> not found | No transfer in the org has that id. | Check the id with `GET /storefront/inventory/transfers`. This is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/inventory/transfers/{transferId}/ship`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"transferId","required":true,"in":"path","description":"Transfer id.","schema":{"type":"string"},"example":"TR-4821"}],"responses":{"200":{"description":"The completed transfer","content":{"application/json":{"schema":{"type":"object","description":"An inventory transfer (`sf_inventory_transfer`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"transferId":{"type":"string","example":"TR-4821"},"status":{"type":"string","enum":["pending","in_transit","completed","cancelled"],"example":"pending"},"fromLocationId":{"type":"string","example":"loc_warehouse"},"fromLocationName":{"type":"string","example":"Central warehouse"},"toLocationId":{"type":"string","example":"loc_downtown"},"toLocationName":{"type":"string","example":"Downtown store"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"productName":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"Quantity sent.","example":48},"receivedQuantity":{"type":"number","description":"Quantity confirmed on receipt. Set at the receiving end.","example":46}}}},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"carrier":{"type":"string","example":"ups"},"notes":{"type":"string"}}}}}}}},"400":{"description":"Transfer <transferId> not found — No transfer in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Transfer <transferId> not found","path":"/storefront/inventory/transfers/{transferId}/receive","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"What actually arrived, per line.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["receivedItems"],"properties":{"receivedItems":{"type":"array","description":"One entry per line, matched by `sku`.","items":{"type":"object","required":["sku","receivedQuantity"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"receivedQuantity":{"type":"number","description":"Units actually received.","example":46}}}}}},"examples":{"full":{"summary":"Everything arrived","value":{"receivedItems":[{"sku":"DRK-COLA-330","receivedQuantity":48}]}},"short":{"summary":"Two units short","description":"The shortfall stays visible on the transfer record.","value":{"receivedItems":[{"sku":"DRK-COLA-330","receivedQuantity":46}]}}}}}}}},"/storefront/inventory/transfers/{transferId}/cancel":{"put":{"operationId":"InventoryController_cancelTransfer","summary":"Cancel an inventory transfer","description":"Cancels a transfer that has not yet shipped, returning the committed stock to the source location.\n\n**Only a `pending` transfer can be cancelled.** Once stock is in transit it physically exists somewhere between two locations, so it must be received — short if necessary — rather than cancelled.\n\n#### Signature\n\n```http\nPUT /storefront/inventory/transfers/{transferId}/cancel (transferId: string, body) -> The cancelled transfer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | TRANSFER_NOT_FOUND | Transfer <transferId> not found | No transfer in the org has that id. | Check the id with `GET /storefront/inventory/transfers`. This is a `400`, not a `404`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/inventory/transfers/{transferId}/receive`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"transferId","required":true,"in":"path","description":"Transfer id.","schema":{"type":"string"},"example":"TR-4821"}],"responses":{"200":{"description":"The cancelled transfer","content":{"application/json":{"schema":{"type":"object","description":"An inventory transfer (`sf_inventory_transfer`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"transferId":{"type":"string","example":"TR-4821"},"status":{"type":"string","enum":["pending","in_transit","completed","cancelled"],"example":"pending"},"fromLocationId":{"type":"string","example":"loc_warehouse"},"fromLocationName":{"type":"string","example":"Central warehouse"},"toLocationId":{"type":"string","example":"loc_downtown"},"toLocationName":{"type":"string","example":"Downtown store"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"productName":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","description":"Quantity sent.","example":48},"receivedQuantity":{"type":"number","description":"Quantity confirmed on receipt. Set at the receiving end.","example":46}}}},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"carrier":{"type":"string","example":"ups"},"notes":{"type":"string"}}}}}}}},"400":{"description":"Transfer <transferId> not found — No transfer in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Transfer <transferId> not found","path":"/storefront/inventory/transfers/{transferId}/cancel","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Inventory"],"requestBody":{"description":"Why the transfer is being cancelled.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Recorded on the transfer.","example":"Store no longer needs the stock"}}},"example":{"reason":"Store no longer needs the stock"}}}}}},"/storefront/products/bulk-editor":{"get":{"operationId":"ProductBulkController_list","summary":"Products for bulk edit","description":"A row per product with its variations, each with price, available, hidden and the stock at a location, plus the record version and the values of any `fields` asked for. Searched, filtered and paged on the server.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"locationId","required":false,"in":"query","description":"Business location (its name) whose stock is shown","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"category","required":false,"in":"query","schema":{"type":"string"}},{"name":"brand","required":false,"in":"query","schema":{"type":"string"}},{"name":"lowStock","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"fields","required":false,"in":"query","description":"Comma-separated product fields (paths inside data, e.g. cost,shipping.weight) whose values each row carries in `values`","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"tags":["Storefront Products"]}},"/storefront/products/bulk-update":{"post":{"operationId":"ProductBulkController_bulkUpdate","summary":"Save bulk edits","description":"Price, available and hidden patched on products and variations; stock set at the location through a count movement. One result per change; a failed row does not fail the others.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront Products"]}},"/storefront/products/variations":{"post":{"operationId":"ProductBulkController_variations","summary":"Generate variants","description":"Every combination of the options picked on the product's attributes, as the product stands in the form (saved or not). Each variant's SKU is the product's SKU plus its option values; a combination it already had keeps its price, stock, images and typed SKU. Returns the product SKU (made from the name when blank) and the variants. Nothing is saved.","parameters":[{"name":"orgid","in":"header","description":"Organization ID","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Storefront Products"]}},"/storefront/products/stock-units":{"get":{"operationId":"ProductBulkController_units","summary":"Stock-keeping units","description":"Products and each of their variations (\"Product — Size / Colour\"), searched and paged, for purchase-order and intake pickers.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"sku","required":false,"in":"query","description":"One exact SKU (a product or a variation)","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"tags":["Storefront Products"]}},"/storefront/discounts/validate":{"post":{"operationId":"DiscountController_validate","summary":"Validate a discount code","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Whether the code applies, and why not when it does not","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"reason":{"type":"string","nullable":true,"enum":["not_found","inactive","not_started","expired","usage_limit","customer_group","customer_group_excluded","customer_not_allowed","customer_excluded","email_required","first_order_only","min_cart_value","min_cart_items","required_products"],"description":"Machine-readable rejection code. Absent when `valid` is true."},"message":{"type":"string","description":"Shopper-facing explanation. Display this; do not parse it.","example":"Minimum cart value of $50 required"},"discount":{"type":"object","description":"The matched discount, when valid.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}},"examples":{"valid":{"summary":"Code applies","value":{"valid":true,"discount":{"data":{"code":"SUMMER20","type":"percent","value":20}}}},"rejected":{"summary":"Below the minimum","value":{"valid":false,"reason":"min_cart_value","message":"Minimum cart value of $50 required"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Checks whether a code can be used by the calling customer for a given cart, and says precisely why not when it cannot.\n\n**A rejection is a `200`, not an error.** The response carries `valid: false` with a machine-readable `reason` and a message written for the shopper. Branch on `reason`; the `message` text is for display and may change.\n\n| `reason` | Meaning |\n| --- | --- |\n| `not_found` | No discount in the org has that code. |\n| `inactive` | The discount exists but its status is not active. |\n| `not_started` | The discount's start date is in the future. |\n| `expired` | The discount's end date has passed. |\n| `usage_limit` | The discount has been redeemed as many times as it allows. |\n| `customer_group` | The customer is not in a group the discount targets. |\n| `customer_group_excluded` | The customer is in a group the discount excludes. |\n| `customer_not_allowed` | The discount names specific customers and this is not one of them. |\n| `customer_excluded` | The discount excludes this specific customer. |\n| `email_required` | The discount needs an email to evaluate and none was available. |\n| `first_order_only` | The discount is for first-time customers and this one has ordered before. |\n| `min_cart_value` | The cart subtotal is below the discount's minimum. |\n| `min_cart_items` | The cart has fewer items than the discount requires. |\n| `required_products` | The cart does not contain the products the discount requires. |\n\nThe email used for first-order and email-gated checks comes from the signed-in customer when there is one, falling back to the `email` in the body.\n\nThis validates only — it records no usage and changes nothing.\n\n#### Signature\n\n```http\nPOST /storefront/discounts/validate (body) -> Whether the code applies, and why not when it does not\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The four `customer_*` reasons all share the message \"Discount not available for your account\" — they are only distinguishable by `reason`.\n- Validation does not reserve or record anything. A code valid here can still be exhausted by someone else before checkout.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/discounts/apply`\n- `POST /storefront/discounts/{identifier}/usage`","requestBody":{"description":"The code and the cart to test it against.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The code to validate.","example":"SUMMER20"},"subtotal":{"type":"number","description":"Cart subtotal, for the minimum-value check.","example":129.99},"productItems":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}},"description":"Ordinary product lines."},"rentalItems":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Rental lines."},"shippingAddress":{"type":"object","additionalProperties":true,"description":"Used where a discount depends on destination."},"email":{"type":"string","description":"Used only when no customer is signed in.","example":"ada@example.com"},"cartId":{"type":"string","description":"Cart the code is being tested for."}}},"examples":{"simple":{"summary":"Check a code against a subtotal","value":{"code":"SUMMER20","subtotal":129.99}},"withCart":{"summary":"Check against real lines","description":"Needed for the item-count and required-product rules.","value":{"code":"SUMMER20","productItems":[{"sku":"DRK-COLA-330","quantity":2,"price":12}]}}}}}}}},"/storefront/discounts/promotions/active":{"get":{"operationId":"DiscountController_getActivePromotions","summary":"List active promotions for display","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Active coded promotions, projected for display","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","example":"percent"},"value":{"type":"number","example":20},"minCartValue":{"type":"number","example":50},"endDate":{"type":"string","format":"date-time","example":"2026-08-31T23:59:59.000Z"}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"A shopper-safe list of the active, **code-based** promotions — the \"current offers\" strip on a storefront.\n\nThe response is deliberately a projection, not the discount records: only `code`, `name`, `description`, `type`, `value`, `minCartValue` and `endDate` are exposed, so targeting rules, usage limits and customer restrictions are never leaked to the browser.\n\nAuto-apply discounts are excluded — they have no code to advertise.\n\n#### Signature\n\n```http\nGET /storefront/discounts/promotions/active () -> Active coded promotions, projected for display\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Listing a promotion here does not mean a given shopper can use it — group and customer targeting still apply. Validate before promising it.\n- Unpaged: every active coded promotion is returned.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/discounts/validate`"}},"/storefront/discounts/automatic":{"post":{"operationId":"DiscountController_getAutomaticDiscounts","summary":"Get automatic discounts for a cart","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The automatic discounts that qualify","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Returns the code-less discounts that would apply to this cart for the calling customer, without pricing the cart. Use it to show \"you are getting 10% off\" before the shopper reaches checkout.\n\n#### Signature\n\n```http\nPOST /storefront/discounts/automatic (body) -> The automatic discounts that qualify\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only discounts with `autoApply: true` are considered. Coded promotions never appear here.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/discounts/promotions/active`","requestBody":{"description":"The cart to evaluate.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subtotal":{"type":"number","example":129.99},"productItems":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}},"description":"Ordinary product lines."},"rentalItems":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Rental lines."},"shippingAddress":{"type":"object","additionalProperties":true,"description":"Used where a discount depends on destination."}}},"example":{"subtotal":129.99,"productItems":[{"sku":"DRK-COLA-330","quantity":2,"price":12}]}}}}}},"/storefront/discounts/apply":{"post":{"operationId":"DiscountController_applyCoupon","summary":"Apply a coupon and price the cart","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The priced cart, with applied discounts and any coupon rejection reason","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Prices a cart with a coupon applied, together with every automatic discount that qualifies. This is the call a checkout page makes when the shopper enters a code.\n\nThe code may be sent as either `couponCode` or `code` — `couponCode` wins when both are present.\n\nAn invalid code does not fail the request: the cart is priced without it and the reason is reported in the response, so the page can show the total *and* explain why the code did not take.\n\n#### Signature\n\n```http\nPOST /storefront/discounts/apply (body) -> The priced cart, with applied discounts and any coupon rejection reason\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Pricing only — nothing is redeemed. Record the redemption at order time with `POST /storefront/discounts/{identifier}/usage`.\n- Identical to `POST /storefront/discounts/calculate` except that this one accepts the `code` alias.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/discounts/calculate`\n- `POST /storefront/discounts/validate`","requestBody":{"description":"The cart and the coupon.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"couponCode":{"type":"string","description":"The code to apply. Takes precedence over `code`.","example":"SUMMER20"},"code":{"type":"string","description":"Alias for `couponCode`, accepted for older clients."},"productItems":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}},"description":"Ordinary product lines."},"rentalItems":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Rental lines."},"shippingAddress":{"type":"object","additionalProperties":true,"description":"Used where a discount depends on destination."}}},"example":{"couponCode":"SUMMER20","productItems":[{"sku":"DRK-COLA-330","quantity":2,"price":12}]}}}}}},"/storefront/discounts/calculate":{"post":{"operationId":"DiscountController_calculateCart","summary":"Calculate a cart with all discounts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The priced cart with all discounts resolved","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Prices a cart with every applicable discount — automatic ones always, plus `couponCode` when supplied.\n\nThis is the same calculation `POST /storefront/pricing/calculate-cart` performs; that endpoint delegates here so cart discounting has one implementation. The only difference from `apply` is that this one does not accept the legacy `code` alias.\n\n#### Signature\n\n```http\nPOST /storefront/discounts/calculate (body) -> The priced cart with all discounts resolved\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/discounts/apply`\n- `POST /storefront/pricing/calculate-cart`","requestBody":{"description":"The cart to price.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"couponCode":{"type":"string","example":"SUMMER20"},"productItems":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","example":2},"price":{"type":"number","description":"Unit price.","example":12}}},"description":"Ordinary product lines."},"rentalItems":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Rental lines."},"shippingAddress":{"type":"object","additionalProperties":true,"description":"Used where a discount depends on destination."}}},"example":{"productItems":[{"sku":"DRK-COLA-330","quantity":2,"price":12}],"couponCode":"SUMMER20"}}}}}},"/storefront/discounts":{"post":{"operationId":"DiscountController_create","summary":"Create a discount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created discount","content":{"application/json":{"schema":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}}},"400":{"description":"Discount code <code> already exists — Another discount in the org already uses that code.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount code <code> already exists","path":"/storefront/discounts","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Creates a discount or an automatic promotion. Omit `code` and set `autoApply` for one that applies without the shopper typing anything.\n\nCodes are unique: creating one that already exists is rejected.\n\n#### Signature\n\n```http\nPOST /storefront/discounts (body) -> The created discount\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CODE_EXISTS | Discount code <code> already exists | Another discount in the org already uses that code. | Choose a different code, or update the existing discount instead. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/discounts/{identifier}`\n- `GET /storefront/discounts`","requestBody":{"description":"The discount to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}},"examples":{"percentCode":{"summary":"A 20% coupon with limits","value":{"code":"SUMMER20","name":"Summer sale","type":"percent","value":20,"status":"active","minCartValue":50,"usageLimit":500,"endDate":"2026-08-31T23:59:59.000Z"}},"automatic":{"summary":"An automatic discount, no code","value":{"name":"Bulk discount","type":"percent","value":10,"status":"active","autoApply":true,"minCartItems":12}}}}}}},"get":{"operationId":"DiscountController_list","summary":"List discounts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by status, e.g. `active`.","example":"active"},{"name":"hasCode","required":false,"in":"query","description":"`true` for code-based discounts, `false` for auto-apply. Omit for both.","schema":{"type":"string","enum":["true","false"]},"example":"true"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50},{"name":"search","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of discounts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}},"total":{"type":"integer","example":12}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Lists discounts with optional filtering and paging.\n\n**Mind the `hasCode` inversion.** `hasCode=true` returns code-based discounts and `hasCode=false` returns automatic ones — the parameter is translated to the internal `autoApply` flag, inverted. Omitting it returns both. Any value other than the exact strings `true` and `false` is treated as omitted.\n\n#### Signature\n\n```http\nGET /storefront/discounts (status?: string, hasCode?: string, page?: integer, pageSize?: integer) -> A page of discounts\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Unlike the promotions endpoint, this returns full records including targeting and usage — it is an operator read, not a shopper one.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/discounts/promotions/active`"}},"/storefront/discounts/stats":{"get":{"operationId":"DiscountController_getStats","summary":"Get discount statistics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Aggregate discount statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Aggregate usage across the org's discounts — how many exist, how many are active, and how much has been redeemed. The operator overview.\n\n#### Signature\n\n```http\nGET /storefront/discounts/stats () -> Aggregate discount statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Declared before `GET /storefront/discounts/{identifier}` on the controller, so `stats` resolves as the statistics route and can never be read as a discount named \"stats\".\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/discounts`"}},"/storefront/discounts/{identifier}":{"get":{"operationId":"DiscountController_getByIdentifier","summary":"Get a discount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"identifier","required":true,"in":"path","schema":{"type":"string"},"description":"Discount `code` **or** record id — both resolve.","example":"SUMMER20"}],"responses":{"200":{"description":"The discount","content":{"application/json":{"schema":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}}},"400":{"description":"Discount <identifier> not found — No discount matches that code or id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount <identifier> not found","path":"/storefront/discounts/{identifier}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Fetches one discount by its code or its record id — both resolve through the same lookup.\n\n#### Signature\n\n```http\nGET /storefront/discounts/{identifier} (identifier: string) -> The discount\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DISCOUNT_NOT_FOUND | Discount <identifier> not found | No discount matches that code or id. | List discounts with `GET /storefront/discounts`. Note this is a `400`, not a `404` — do not branch on the status alone. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/discounts/{identifier}`"},"put":{"operationId":"DiscountController_update","summary":"Update a discount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"identifier","required":true,"in":"path","schema":{"type":"string"},"description":"Discount `code` **or** record id — both resolve.","example":"SUMMER20"}],"responses":{"200":{"description":"The updated discount","content":{"application/json":{"schema":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}}},"400":{"description":"Discount <identifier> not found — No discount matches that code or id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount <identifier> not found","path":"/storefront/discounts/{identifier}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Merges the body into an existing discount. Fields you omit keep their current values; arrays you send replace their counterparts entirely.\n\n#### Signature\n\n```http\nPUT /storefront/discounts/{identifier} (identifier: string, body) -> The updated discount\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Changing `value` or `type` affects only future redemptions — orders already discounted keep what they were given.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DISCOUNT_NOT_FOUND | Discount <identifier> not found | No discount matches that code or id. | List discounts with `GET /storefront/discounts`. Note this is a `400`, not a `404` — do not branch on the status alone. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/discounts/{identifier}/activate`","requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}},"examples":{"extend":{"summary":"Extend the end date","value":{"endDate":"2026-09-30T23:59:59.000Z"}},"raiseLimit":{"summary":"Raise the usage limit","value":{"usageLimit":1000}}}}}}},"delete":{"operationId":"DiscountController_delete","summary":"Delete a discount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"identifier","required":true,"in":"path","schema":{"type":"string"},"description":"Discount `code` **or** record id — both resolve.","example":"SUMMER20"}],"responses":{"200":{"description":"Confirmation of the delete","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"400":{"description":"Discount <identifier> not found — No discount matches that code or id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount <identifier> not found","path":"/storefront/discounts/{identifier}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Deletes a discount that has never been redeemed.\n\n**A used discount cannot be deleted** — the redemption history is evidence of what customers were charged, and removing the discount would orphan it. Deactivate instead.\n\n#### Signature\n\n```http\nDELETE /storefront/discounts/{identifier} (identifier: string) -> Confirmation of the delete\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DISCOUNT_NOT_FOUND | Discount <identifier> not found | No discount matches that code or id. | List discounts with `GET /storefront/discounts`. Note this is a `400`, not a `404` — do not branch on the status alone. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/discounts/{identifier}/deactivate`"}},"/storefront/discounts/{identifier}/activate":{"put":{"operationId":"DiscountController_activate","summary":"Activate a discount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"identifier","required":true,"in":"path","schema":{"type":"string"},"description":"Discount `code` **or** record id — both resolve.","example":"SUMMER20"}],"responses":{"200":{"description":"The activated discount","content":{"application/json":{"schema":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}}},"400":{"description":"Discount <identifier> not found — No discount matches that code or id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount <identifier> not found","path":"/storefront/discounts/{identifier}/activate","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Sets the discount status to active so it validates and applies. Start and end dates still gate it — activating a discount whose window has passed does not make it usable.\n\n#### Signature\n\n```http\nPUT /storefront/discounts/{identifier}/activate (identifier: string) -> The activated discount\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DISCOUNT_NOT_FOUND | Discount <identifier> not found | No discount matches that code or id. | List discounts with `GET /storefront/discounts`. Note this is a `400`, not a `404` — do not branch on the status alone. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/discounts/{identifier}/deactivate`"}},"/storefront/discounts/{identifier}/deactivate":{"put":{"operationId":"DiscountController_deactivate","summary":"Deactivate a discount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"identifier","required":true,"in":"path","schema":{"type":"string"},"description":"Discount `code` **or** record id — both resolve.","example":"SUMMER20"}],"responses":{"200":{"description":"The deactivated discount","content":{"application/json":{"schema":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}}},"400":{"description":"Discount <identifier> not found — No discount matches that code or id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount <identifier> not found","path":"/storefront/discounts/{identifier}/deactivate","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Takes a discount out of service. It stops validating immediately, with `reason: \"inactive\"`.\n\nThis is the reversible way to stop a promotion — prefer it to deleting, which also loses the usage history.\n\n#### Signature\n\n```http\nPUT /storefront/discounts/{identifier}/deactivate (identifier: string) -> The deactivated discount\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DISCOUNT_NOT_FOUND | Discount <identifier> not found | No discount matches that code or id. | List discounts with `GET /storefront/discounts`. Note this is a `400`, not a `404` — do not branch on the status alone. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/discounts/{identifier}/activate`\n- `DELETE /storefront/discounts/{identifier}`"}},"/storefront/discounts/{identifier}/usage":{"post":{"operationId":"DiscountController_recordUsage","summary":"Record a discount redemption","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"identifier","required":true,"in":"path","schema":{"type":"string"},"description":"Discount `code` **or** record id — both resolve.","example":"SUMMER20"}],"responses":{"201":{"description":"The updated discount, with its incremented usage","content":{"application/json":{"schema":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}}},"400":{"description":"Discount <identifier> not found — No discount matches that code or id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount <identifier> not found","path":"/storefront/discounts/{identifier}/usage","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Records that a discount was actually used on an order, incrementing its usage count towards `usageLimit`.\n\nValidation and cart pricing never do this — a code can be validated any number of times without consuming it. Call this once the order is created, or the usage limit will never be reached.\n\nIt is **not idempotent**: calling it twice for one order counts two redemptions.\n\n#### Signature\n\n```http\nPOST /storefront/discounts/{identifier}/usage (identifier: string, body) -> The updated discount, with its incremented usage\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Not idempotent. Guard against double submission, or reverse the surplus with the reverse endpoint.\n- Omitting `customerEmail` leaves the first-order-only rule unable to recognise this customer later.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DISCOUNT_NOT_FOUND | Discount <identifier> not found | No discount matches that code or id. | List discounts with `GET /storefront/discounts`. Note this is a `400`, not a `404` — do not branch on the status alone. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/discounts/{identifier}/reverse`","requestBody":{"description":"The order the discount was used on.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","orderNumber","discountAmount"],"properties":{"orderId":{"type":"string","description":"Order record id.","example":"66f1a2b3c4d5e6f708192a3b"},"orderNumber":{"type":"string","description":"Public order number.","example":"A7K2M9QX4"},"discountAmount":{"type":"number","description":"How much was actually discounted.","example":26},"customerEmail":{"type":"string","description":"Who redeemed it. Used by the first-order-only rule.","example":"ada@example.com"}}},"example":{"orderId":"66f1a2b3c4d5e6f708192a3b","orderNumber":"A7K2M9QX4","discountAmount":26,"customerEmail":"ada@example.com"}}}}}},"/storefront/discounts/{identifier}/reverse":{"post":{"operationId":"DiscountController_reverseUsage","summary":"Reverse a discount redemption","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"identifier","required":true,"in":"path","schema":{"type":"string"},"description":"Discount `code` **or** record id — both resolve.","example":"SUMMER20"}],"responses":{"201":{"description":"The updated discount","content":{"application/json":{"schema":{"type":"object","description":"A discount (`sf_discount`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"Redemption code. Absent on an auto-apply discount.","example":"SUMMER20"},"name":{"type":"string","example":"Summer sale"},"description":{"type":"string","example":"20% off everything through August"},"type":{"type":"string","description":"How `value` is interpreted — `percent`, `fixed`, `free_shipping`.","example":"percent"},"value":{"type":"number","example":20},"status":{"type":"string","description":"Only `active` discounts validate.","example":"active"},"autoApply":{"type":"boolean","description":"True for a discount with no code, applied automatically when the cart qualifies.","example":false},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"usageLimit":{"type":"number","description":"Total redemptions allowed across all customers.","example":500},"usageCount":{"type":"number","description":"Redemptions recorded so far.","example":37},"minCartValue":{"type":"number","example":50},"minCartItems":{"type":"number","example":2},"firstOrderOnly":{"type":"boolean","example":false},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the discount is limited to."},"excludedCustomerGroups":{"type":"array","items":{"type":"string"}},"requiredProducts":{"type":"array","items":{"type":"string"},"description":"SKUs that must be in the cart."}}}}}}}},"400":{"description":"Discount <identifier> not found — No discount matches that code or id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Discount <identifier> not found","path":"/storefront/discounts/{identifier}/reverse","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Discounts"],"description":"Undoes a recorded redemption for one order, decrementing the usage count. Use it when an order is cancelled or refunded so the code becomes available again.\n\n#### Signature\n\n```http\nPOST /storefront/discounts/{identifier}/reverse (identifier: string, body) -> The updated discount\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DISCOUNT_NOT_FOUND | Discount <identifier> not found | No discount matches that code or id. | List discounts with `GET /storefront/discounts`. Note this is a `400`, not a `404` — do not branch on the status alone. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/discounts/{identifier}/usage`","requestBody":{"description":"The order whose redemption is being reversed.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId"],"properties":{"orderId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"}}},"example":{"orderId":"66f1a2b3c4d5e6f708192a3b"}}}}}},"/shipping/rates":{"post":{"operationId":"ShippingController_getShippingRates","summary":"Get shipping rates","description":"Quotes rates from the configured carriers for a set of parcels travelling between two addresses. This is the first step of the direct flow: quote, choose, then buy a label.\n\nPass the chosen rate object back to `POST /shipping/create` unchanged — carriers key their label purchase on the rate id, so a reconstructed object will not work.\n\n#### Signature\n\n```http\nPOST /shipping/rates (body) -> Available rates across configured carriers\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Rates expire. Buy the label promptly, or re-quote before purchasing.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PROVIDER_NOT_CONFIGURED | Shipping integration not configured. Please configure EasyPost or another shipping provider. | Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\". | Configure a carrier integration — `GET /shipping/admin/providers` lists what is supported. Using the platform's shared carrier needs the org to accept its service agreement (a `402` otherwise). |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/create`\n- `POST /shipping/order/rates`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What is being shipped, and between where.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}},"description":"One entry per package."},"items":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines being shipped, when parcels should be derived from them."}}},"example":{"fromAddress":{"name":"Acme","street1":"4 Warehouse Way","city":"Newark","state":"NJ","zip":"07102","country":"US"},"toAddress":{"name":"Ada Lovelace","street1":"12 Ada Way","city":"Boston","state":"MA","zip":"02108","country":"US"},"parcels":[{"length":12,"width":9,"height":4,"weight":2.5}]}}}},"responses":{"201":{"description":"Available rates across configured carriers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A quoted rate from a carrier. Pass the whole object back when creating a label.","additionalProperties":true,"properties":{"id":{"type":"string","example":"rate_abc123"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"rate":{"type":"string","example":"8.45"},"currency":{"type":"string","example":"USD"},"delivery_days":{"type":"number","example":2}}}}}}},"400":{"description":"Shipping integration not configured. Please configure EasyPost or another shipping provider. — Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\".","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Shipping integration not configured. Please configure EasyPost or another shipping provider.","path":"/shipping/rates","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/create":{"post":{"operationId":"ShippingController_createShipping","summary":"Create a shipping label","description":"Buys the label for a chosen rate and creates the shipping record. **This spends money** — the carrier charges for the label at this point.\n\nNot idempotent: a retried request buys a second label. If a response is lost, look the shipment up with `GET /shipping/list` before trying again.\n\n#### Signature\n\n```http\nPOST /shipping/create (body) -> The shipping record, including the label and tracking number\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Buys a real label and incurs a real charge. Treat it as non-repeatable.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PROVIDER_NOT_CONFIGURED | Shipping integration not configured. Please configure EasyPost or another shipping provider. | Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\". | Configure a carrier integration — `GET /shipping/admin/providers` lists what is supported. Using the platform's shared carrier needs the org to accept its service agreement (a `402` otherwise). |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/rates`\n- `POST /shipping/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The chosen rate and the shipment details.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rate":{"type":"object","description":"The rate object returned by `POST /shipping/rates`, passed back unchanged.","additionalProperties":true,"properties":{"id":{"type":"string","example":"rate_abc123"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"rate":{"type":"string","example":"8.45"},"currency":{"type":"string","example":"USD"},"delivery_days":{"type":"number","example":2}}},"orderNumber":{"type":"string","description":"Order to associate the shipment with.","example":"A7K2M9QX4"},"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}}}}},"example":{"orderNumber":"A7K2M9QX4","rate":{"id":"rate_abc123","carrier":"USPS","service":"Priority","rate":"8.45"}}}}},"responses":{"201":{"description":"The shipping record, including the label and tracking number","content":{"application/json":{"schema":{"type":"object","description":"A shipping record (`sf_shipping`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"trackingUrl":{"type":"string"},"status":{"type":"string","description":"Carrier status as last seen.","example":"in_transit"},"labelUrl":{"type":"string","description":"Where the purchased label can be downloaded."},"cost":{"type":"string","example":"8.45"},"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}}},"products":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines included in this shipment."}}}}}}}},"400":{"description":"Shipping integration not configured. Please configure EasyPost or another shipping provider. — Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\".","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Shipping integration not configured. Please configure EasyPost or another shipping provider.","path":"/shipping/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/refresh-tracking":{"post":{"operationId":"ShippingController_refreshTracking","summary":"Refresh tracking and apply any change","description":"Asks the carrier where a parcel is right now, then applies **the same rules as the webhook**: the order is updated and the customer emailed only when the carrier status differs from the one already processed.\n\nThat makes it safe to click repeatedly — an unchanged status costs one carrier lookup and does nothing else. No duplicate emails, no redundant writes.\n\nPass `orderNumber` to check every shipment on an order, or `trackingNumber` for one. Set `apply: false` to preview without writing anything, or `notify: false` to update the order without emailing the customer.\n\n#### Signature\n\n```http\nPOST /shipping/refresh-tracking (body) -> What changed, per shipment\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Idempotent by design — repeated calls with an unchanged carrier status have no side effects.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CARRIER_ERROR | The carrier rejected the request. | The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials. | The carrier message is passed through. Verify the address first with `POST /shipping/verify-address`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/tracking-webhook`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"trackingNumber","required":true,"in":"path","description":"Tracking number","schema":{}}],"requestBody":{"description":"What to check, and what to do about it.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderNumber":{"type":"string","description":"Check every shipment on this order.","example":"A7K2M9QX4"},"trackingNumber":{"type":"string","description":"Check a single tracking number.","example":"9400111899223197428490"},"apply":{"type":"boolean","default":true,"description":"`false` previews the outcome and writes nothing.","example":true},"notify":{"type":"boolean","default":true,"description":"`false` updates the order without emailing the customer.","example":true}}},"examples":{"wholeOrder":{"summary":"Refresh every shipment on an order","value":{"orderNumber":"A7K2M9QX4"}},"preview":{"summary":"Preview without writing","value":{"orderNumber":"A7K2M9QX4","apply":false}},"silent":{"summary":"Update without emailing the customer","value":{"trackingNumber":"9400111899223197428490","notify":false}}}}}},"responses":{"201":{"description":"What changed, per shipment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The carrier rejected the request. — The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The carrier rejected the request.","path":"/shipping/refresh-tracking","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/tracking-webhook":{"get":{"operationId":"ShippingController_getTrackingWebhookSetup","summary":"Read saved automatic tracking setup without contacting the provider","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Shipping"]},"post":{"operationId":"ShippingController_ensureTrackingWebhook","summary":"Register the tracking webhook","description":"Points the carrier integration at this org's webhook so carrier scans arrive automatically and shipping status updates without anyone polling.\n\n**Idempotent** — registrations are matched on URL, so calling it repeatedly is safe.\n\nWhen the provider is not configured it returns `{ ready: false, url }` rather than throwing, so setup flows can check readiness without handling an error.\n\n#### Signature\n\n```http\nPOST /shipping/tracking-webhook () -> Whether the webhook is registered, and at what URL\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Never throws for a missing provider — check `ready` in the response.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/refresh-tracking`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Whether the webhook is registered, and at what URL","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"boolean","example":true},"url":{"type":"string","example":"https://api.appmint.io/shipping/webhook/acme-retail"}}},"example":{"ready":true,"url":"https://api.appmint.io/shipping/webhook/acme-retail"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/track/{trackingNumber}":{"get":{"operationId":"ShippingController_trackShipment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"trackingNumber","required":true,"in":"path","schema":{"type":"string"},"description":"Carrier tracking number.","example":"9400111899223197428490"}],"responses":{"200":{"description":"Tracking information from the carrier","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The carrier rejected the request. — The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The carrier rejected the request.","path":"/shipping/track/{trackingNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Shipping record not found — No shipping record matches the id, tracking number or order number given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping record not found","path":"/shipping/track/{trackingNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"],"summary":"Track a shipment","description":"Returns the carrier's current tracking information for a tracking number. A read-only lookup — it does not update the order or notify anyone.\n\nUse `POST /shipping/refresh-tracking` when you want a status change to actually propagate.\n\n#### Signature\n\n```http\nGET /shipping/track/{trackingNumber} (trackingNumber: string) -> Tracking information from the carrier\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SHIPPING_NOT_FOUND | Shipping record not found | No shipping record matches the id, tracking number or order number given. | List records with `GET /shipping/list`. |\n| `400` | CARRIER_ERROR | The carrier rejected the request. | The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials. | The carrier message is passed through. Verify the address first with `POST /shipping/verify-address`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/refresh-tracking`"}},"/shipping/google-keys":{"get":{"operationId":"ShippingController_getGoogleKeys","summary":"Get the Google Maps key for this org","description":"Returns the Maps API key a client should use, and says where it came from.\n\nWhen the org has configured its own Google provider with a `mapsApiKey`, that key is returned with `source: \"org\"` and `billable: false` — they pay Google directly and nothing is metered here.\n\nOtherwise the shared platform key is returned with `source: \"shared\"` and `billable: true`, and the org's agreement and balance are checked **before** the key is handed over. An org without an agreement or in arrears does not get a key.\n\n#### Signature\n\n```http\nGET /shipping/google-keys () -> The key and its billing provenance\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A `billable: true` response means the org is being charged for Maps usage — surface that in any UI that spends it heavily.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/address-autocomplete`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"required":true,"description":"Autocomplete request","content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","description":"User input text (minimum 3 characters)"},"sessiontoken":{"type":"string","description":"Session token for billing optimization (optional)"},"components":{"type":"string","description":"Country filter e.g. \"country:us|country:ca\" (default: US & CA)"}}}}}},"responses":{"200":{"description":"The key and its billing provenance","content":{"application/json":{"schema":{"type":"object","properties":{"mapsApiKey":{"type":"string","description":"Key to use client-side."},"source":{"type":"string","enum":["org","shared"],"description":"`org` means the org pays Google directly.","example":"shared"},"billable":{"type":"boolean","description":"Whether usage is metered and charged by the platform.","example":true}}},"example":{"mapsApiKey":"AIza...","source":"shared","billable":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/address-autocomplete":{"post":{"operationId":"ShippingController_getAddressAutocomplete","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Address predictions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"],"summary":"Autocomplete an address","description":"Returns address predictions as the customer types, backed by Google Places. Defaults to US and Canada; pass `components` to widen or narrow that.\n\nSend a `sessiontoken` and keep it constant across the keystrokes of one lookup, then reuse it for the matching `place-details` call — Google bills an autocomplete session as a unit, and omitting the token makes every keystroke a separate billable request.\n\n#### Signature\n\n```http\nPOST /shipping/address-autocomplete (body) -> Address predictions\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- May be billed against the shared platform Google key — see `GET /shipping/google-keys`.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /shipping/place-details/{placeId}`\n- `GET /shipping/google-keys`","requestBody":{"description":"What the customer has typed so far.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","description":"The typed text. At least 3 characters.","example":"12 Ada W"},"sessiontoken":{"type":"string","description":"Groups the keystrokes of one lookup into a single billable session. Reuse it for `place-details`.","example":"b1f2c3d4-e5f6"},"components":{"type":"string","default":"country:us|country:ca","description":"Country filter.","example":"country:us|country:ca"}}},"example":{"input":"12 Ada W","sessiontoken":"b1f2c3d4-e5f6","components":"country:us|country:ca"}}}}}},"/shipping/place-details/{placeId}":{"get":{"operationId":"ShippingController_getPlaceDetails","summary":"Get address details for a place","description":"Expands a place id from autocomplete into a full structured address ready to use as a shipping address.\n\n#### Signature\n\n```http\nGET /shipping/place-details/{placeId} (placeId: string) -> The structured address\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/address-autocomplete`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"placeId","required":true,"in":"path","description":"Google Place ID from an autocomplete prediction.","schema":{"type":"string"},"example":"ChIJd8BlQ2BZwokRAFUEcm_qrcA"}],"responses":{"200":{"description":"The structured address","content":{"application/json":{"schema":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/verify-address":{"post":{"operationId":"ShippingController_verifyShippingAddress","summary":"Verify a shipping address","description":"Validates and normalises an address with the carrier, correcting formatting and flagging anything undeliverable. Worth calling before buying a label — a bad address is the most common cause of a rejected shipment.\n\n#### Signature\n\n```http\nPOST /shipping/verify-address (body) -> The verified and normalised address\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CARRIER_ERROR | The carrier rejected the request. | The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials. | The carrier message is passed through. Verify the address first with `POST /shipping/verify-address`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/address-autocomplete`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The address to verify.","required":true,"content":{"application/json":{"schema":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"example":{"name":"Ada Lovelace","street1":"12 Ada Way","city":"Boston","state":"MA","zip":"02108","country":"US"}}}},"responses":{"201":{"description":"The verified and normalised address","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The carrier rejected the request. — The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The carrier rejected the request.","path":"/shipping/verify-address","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/methods":{"get":{"operationId":"ShippingController_getShippingMethods","summary":"Get shipping methods","description":"The shipping methods and carriers available to this org. Use it to build a delivery-option selector rather than hard-coding carriers.\n\n#### Signature\n\n```http\nGET /shipping/methods () -> Available methods and carriers\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /shipping/admin/configs`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Available methods and carriers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/list":{"get":{"operationId":"ShippingController_listShippings","summary":"List shipping records","description":"Lists shipments with optional filters and paging.\n\n#### Signature\n\n```http\nGET /shipping/list (orderNumber?: string, status?: string, author?: string, page?: integer, pageSize?: integer) -> A page of shipping records\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /shipping/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orderNumber","required":false,"in":"query","schema":{"type":"string"},"example":"A7K2M9QX4"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"example":"in_transit"},{"name":"author","required":false,"in":"query","description":"Filter by the customer or operator on the record.","schema":{"type":"string"},"example":"ada@example.com"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of shipping records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A shipping record (`sf_shipping`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"trackingUrl":{"type":"string"},"status":{"type":"string","description":"Carrier status as last seen.","example":"in_transit"},"labelUrl":{"type":"string","description":"Where the purchased label can be downloaded."},"cost":{"type":"string","example":"8.45"},"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}}},"products":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines included in this shipment."}}}}}},"total":{"type":"integer","example":32}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/cancel":{"post":{"operationId":"ShippingController_cancelShipping","summary":"Cancel a shipment","description":"Cancels a shipment and requests a refund for the label from the carrier. Identify it by shipping id, tracking number or order number.\n\nCarriers only refund labels that have not entered their network, and refunds are typically processed on their own schedule rather than immediately.\n\n#### Signature\n\n```http\nPOST /shipping/cancel (body) -> The cancellation result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- A successful cancellation is a refund *request*. Whether the carrier honours it is their decision.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SHIPPING_NOT_FOUND | Shipping record not found | No shipping record matches the id, tracking number or order number given. | List records with `GET /shipping/list`. |\n| `400` | CARRIER_ERROR | The carrier rejected the request. | The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials. | The carrier message is passed through. Verify the address first with `POST /shipping/verify-address`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which shipment to cancel. Send at least one identifier.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shippingId":{"type":"string","description":"Shipping record id."},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"orderNumber":{"type":"string","example":"A7K2M9QX4"}}},"example":{"shippingId":"66f1a2b3c4d5e6f708192a3b"}}}},"responses":{"201":{"description":"The cancellation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The carrier rejected the request. — The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The carrier rejected the request.","path":"/shipping/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Shipping record not found — No shipping record matches the id, tracking number or order number given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping record not found","path":"/shipping/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/update-address":{"post":{"operationId":"ShippingController_updateShippingAddress","summary":"Update a delivery address","description":"Changes the delivery address on a shipment. **Only possible before the label is purchased** — once a carrier has the shipment, the address is fixed and the shipment must be cancelled and recreated.\n\n#### Signature\n\n```http\nPOST /shipping/update-address (body) -> The updated shipping record\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Cancel and recreate the shipment if the label has already been bought.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SHIPPING_NOT_FOUND | Shipping record not found | No shipping record matches the id, tracking number or order number given. | List records with `GET /shipping/list`. |\n| `400` | CARRIER_ERROR | The carrier rejected the request. | The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials. | The carrier message is passed through. Verify the address first with `POST /shipping/verify-address`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The shipment and its new address.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["shippingId","address"],"properties":{"shippingId":{"type":"string","example":"66f1a2b3c4d5e6f708192a3b"},"address":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}}}},"example":{"shippingId":"66f1a2b3c4d5e6f708192a3b","address":{"name":"Ada Lovelace","street1":"12 Ada Way","city":"Boston","state":"MA","zip":"02108","country":"US"}}}}},"responses":{"201":{"description":"The updated shipping record","content":{"application/json":{"schema":{"type":"object","description":"A shipping record (`sf_shipping`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"trackingUrl":{"type":"string"},"status":{"type":"string","description":"Carrier status as last seen.","example":"in_transit"},"labelUrl":{"type":"string","description":"Where the purchased label can be downloaded."},"cost":{"type":"string","example":"8.45"},"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}}},"products":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines included in this shipment."}}}}}}}},"400":{"description":"The carrier rejected the request. — The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The carrier rejected the request.","path":"/shipping/update-address","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Shipping record not found — No shipping record matches the id, tracking number or order number given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping record not found","path":"/shipping/update-address","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/estimated-delivery":{"post":{"operationId":"ShippingController_getEstimatedDelivery","summary":"Get estimated delivery times","description":"Returns estimated transit times per carrier and service for a route, without quoting prices or creating anything. Use it to show \"arrives Tuesday\" on a delivery-option selector.\n\nNarrow the result with `carrier` or `service` when you only care about one option.\n\n#### Signature\n\n```http\nPOST /shipping/estimated-delivery (body) -> Transit-time estimates per carrier and service\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Estimates are the carrier's, not a guarantee, and exclude your own handling time before dispatch.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PROVIDER_NOT_CONFIGURED | Shipping integration not configured. Please configure EasyPost or another shipping provider. | Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\". | Configure a carrier integration — `GET /shipping/admin/providers` lists what is supported. Using the platform's shared carrier needs the org to accept its service agreement (a `402` otherwise). |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/rates`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The route and parcels to estimate for.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromAddress","toAddress","parcels"],"properties":{"fromAddress":{"type":"object","description":"Origin address.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"Destination address.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}},"description":"Package dimensions and weight."},"carrier":{"type":"string","description":"Restrict to one carrier.","example":"USPS"},"service":{"type":"string","description":"Restrict to one service level.","example":"Priority"}}},"example":{"fromAddress":{"name":"Acme","street1":"4 Warehouse Way","city":"Newark","state":"NJ","zip":"07102","country":"US"},"toAddress":{"name":"Ada Lovelace","street1":"12 Ada Way","city":"Boston","state":"MA","zip":"02108","country":"US"},"parcels":[{"length":12,"width":9,"height":4,"weight":2.5}]}}}},"responses":{"201":{"description":"Transit-time estimates per carrier and service","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"deliveryDays":{"type":"number","description":"Estimated transit days.","example":2},"estimatedDeliveryDate":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Shipping integration not configured. Please configure EasyPost or another shipping provider. — Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\".","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Shipping integration not configured. Please configure EasyPost or another shipping provider.","path":"/shipping/estimated-delivery","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/label/{shippingId}/{format}":{"get":{"operationId":"ShippingController_getShippingLabelById","summary":"Get a shipping label by id","description":"The URL form of the label retrieval, convenient for linking to directly from an operator UI.\n\n#### Signature\n\n```http\nGET /shipping/label/{shippingId}/{format} (shippingId: string, format: string) -> The label\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SHIPPING_NOT_FOUND | Shipping record not found | No shipping record matches the id, tracking number or order number given. | List records with `GET /shipping/list`. |\n| `400` | CARRIER_ERROR | The carrier rejected the request. | The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials. | The carrier message is passed through. Verify the address first with `POST /shipping/verify-address`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/label`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"shippingId","required":true,"in":"path","description":"Shipping record id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"format","required":false,"in":"query","description":"Label format","schema":{"enum":["PDF","PNG","ZPL","EPL2"],"type":"string"}},{"name":"format","in":"path","required":true,"description":"Label format — one of `PDF`, `PNG`, `ZPL`, `EPL2`. Defaults to PDF.","schema":{"type":"string"},"example":"PDF"}],"responses":{"200":{"description":"The label","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The carrier rejected the request. — The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The carrier rejected the request.","path":"/shipping/label/{shippingId}/{format}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Shipping record not found — No shipping record matches the id, tracking number or order number given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping record not found","path":"/shipping/label/{shippingId}/{format}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/label":{"post":{"operationId":"ShippingController_getShippingLabel","summary":"Get a shipping label","description":"Retrieves the label for an existing shipment in a chosen format. Identify it by shipping record id, provider shipment id, or tracking number.\n\n#### Signature\n\n```http\nPOST /shipping/label (body) -> The label\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SHIPPING_NOT_FOUND | Shipping record not found | No shipping record matches the id, tracking number or order number given. | List records with `GET /shipping/list`. |\n| `400` | CARRIER_ERROR | The carrier rejected the request. | The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials. | The carrier message is passed through. Verify the address first with `POST /shipping/verify-address`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /shipping/label/{shippingId}/{format}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which shipment, and in what format.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shippingId":{"type":"string","description":"Shipping record id."},"shipmentId":{"type":"string","description":"Provider shipment id."},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"format":{"type":"string","enum":["PDF","PNG","ZPL","EPL2"],"default":"PDF","description":"`ZPL` and `EPL2` are for thermal label printers.","example":"PDF"}}},"examples":{"pdf":{"summary":"PDF for a normal printer","value":{"shippingId":"66f1a2b3c4d5e6f708192a3b","format":"PDF"}},"thermal":{"summary":"ZPL for a thermal printer","value":{"trackingNumber":"9400111899223197428490","format":"ZPL"}}}}}},"responses":{"201":{"description":"The label","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The carrier rejected the request. — The carrier API returned an error — an undeliverable address, a parcel outside its limits, or missing credentials.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The carrier rejected the request.","path":"/shipping/label","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Shipping record not found — No shipping record matches the id, tracking number or order number given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping record not found","path":"/shipping/label","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/{id}":{"get":{"operationId":"ShippingController_getShipping","summary":"Get a shipping record","description":"Fetches one shipment by record id **or** order number.\n\nThis route is declared last among the single-segment GETs, so `/shipping/list` and `/shipping/methods` resolve as their own endpoints rather than being read as ids.\n\n#### Signature\n\n```http\nGET /shipping/{id} (id: string) -> The shipping record\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SHIPPING_NOT_FOUND | Shipping record not found | No shipping record matches the id, tracking number or order number given. | List records with `GET /shipping/list`. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /shipping/order/shipments/{orderNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Shipping record id or order number.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"The shipping record","content":{"application/json":{"schema":{"type":"object","description":"A shipping record (`sf_shipping`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"trackingUrl":{"type":"string"},"status":{"type":"string","description":"Carrier status as last seen.","example":"in_transit"},"labelUrl":{"type":"string","description":"Where the purchased label can be downloaded."},"cost":{"type":"string","example":"8.45"},"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}}},"products":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines included in this shipment."}}}}}}}},"404":{"description":"Shipping record not found — No shipping record matches the id, tracking number or order number given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping record not found","path":"/shipping/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/locations/available":{"get":{"operationId":"ShippingController_getAvailableLocations","summary":"Get available ship-from locations","description":"Locations that can be used as an origin address. Where an org has exactly one, the order endpoints select it automatically and `fromLocationId` can be omitted.\n\n#### Signature\n\n```http\nGET /shipping/locations/available () -> Locations usable as a shipping origin\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/order/rates`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Locations usable as a shipping origin","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/order/shipments/{orderNumber}":{"get":{"operationId":"ShippingController_getShipmentsForOrder","summary":"Get shipments for an order","description":"Every shipment raised against an order. An order shipped in parts has several, one per parcel or per fulfilment run.\n\n#### Signature\n\n```http\nGET /shipping/order/shipments/{orderNumber} (orderNumber: string) -> The order's shipments\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /shipping/order/status/{orderNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","description":"Public order number.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"The order's shipments","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A shipping record (`sf_shipping`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"trackingUrl":{"type":"string"},"status":{"type":"string","description":"Carrier status as last seen.","example":"in_transit"},"labelUrl":{"type":"string","description":"Where the purchased label can be downloaded."},"cost":{"type":"string","example":"8.45"},"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}}},"products":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines included in this shipment."}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/order/status/{orderNumber}":{"get":{"operationId":"ShippingController_getOrderShippingStatus","summary":"Get shipping status for an order","description":"The fulfilment picture for an order: which lines have shipped and which are still outstanding.\n\nThis is the read that makes partial shipments manageable — it answers \"what is left to send\" without reconciling shipments against order lines yourself.\n\n#### Signature\n\n```http\nGET /shipping/order/status/{orderNumber} (orderNumber: string) -> Shipped and pending lines for the order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/order/rates`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orderNumber","required":true,"in":"path","description":"Public order number.","schema":{"type":"string"},"example":"A7K2M9QX4"},{"name":"email","required":false,"in":"query","description":"Guest: the email on the order (signed-in customers are matched on their own email)","schema":{"type":"string"}}],"responses":{"200":{"description":"Shipped and pending lines for the order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"shipped":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines already dispatched."},"pending":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines still to ship."}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/order/rates":{"post":{"operationId":"ShippingController_getShippingRatesForOrder","summary":"Get shipping rates for an order","description":"Quotes rates for an order, pulling the destination and the items from the order itself.\n\nFor a partial shipment, name the lines in `productSkus`; omit it to quote for everything outstanding. `fromLocationId` can be omitted when the org has only one location.\n\n#### Signature\n\n```http\nPOST /shipping/order/rates (body) -> Available rates for the order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PROVIDER_NOT_CONFIGURED | Shipping integration not configured. Please configure EasyPost or another shipping provider. | Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\". | Configure a carrier integration — `GET /shipping/admin/providers` lists what is supported. Using the platform's shared carrier needs the org to accept its service agreement (a `402` otherwise). |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/order/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The order, and optionally which lines to ship.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderNumber"],"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"productSkus":{"type":"array","items":{"type":"string"},"description":"Lines to ship. Omit for everything.","example":["DRK-COLA-330"]},"fromLocationId":{"type":"string","description":"Origin. Auto-selected when the org has one location.","example":"loc_warehouse"}}},"examples":{"whole":{"summary":"Quote for the whole order","value":{"orderNumber":"A7K2M9QX4"}},"partial":{"summary":"Quote for two lines only","value":{"orderNumber":"A7K2M9QX4","productSkus":["DRK-COLA-330","DRK-COLA-500"],"fromLocationId":"loc_warehouse"}}}}}},"responses":{"201":{"description":"Available rates for the order","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A quoted rate from a carrier. Pass the whole object back when creating a label.","additionalProperties":true,"properties":{"id":{"type":"string","example":"rate_abc123"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"rate":{"type":"string","example":"8.45"},"currency":{"type":"string","example":"USD"},"delivery_days":{"type":"number","example":2}}}}}}},"400":{"description":"Shipping integration not configured. Please configure EasyPost or another shipping provider. — Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\".","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Shipping integration not configured. Please configure EasyPost or another shipping provider.","path":"/shipping/order/rates","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/order/ship":{"post":{"operationId":"ShippingController_shipOrder","summary":"Create shipment for order","description":"Create a shipment for an order. Supports partial shipments by specifying specific products.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Shipment creation request","content":{"application/json":{"schema":{"type":"object","required":["orderNumber","rate"],"properties":{"orderNumber":{"type":"string","description":"Order number"},"productSkus":{"type":"array","items":{"type":"string"},"description":"Specific product SKUs to ship (optional, ships all if not specified)"},"rate":{"type":"object","description":"Selected rate from getShippingRatesForOrder"},"fromLocationId":{"type":"string","description":"Ship-from location ID (optional, auto-selects if only one location)"}}}}}},"responses":{"200":{"description":"Returns created shipment with label"}},"tags":["Shipping"]}},"/shipping/order/create":{"post":{"operationId":"ShippingController_createShippingForOrder","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created shipment with its label","content":{"application/json":{"schema":{"type":"object","description":"A shipping record (`sf_shipping`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"trackingNumber":{"type":"string","example":"9400111899223197428490"},"trackingUrl":{"type":"string"},"status":{"type":"string","description":"Carrier status as last seen.","example":"in_transit"},"labelUrl":{"type":"string","description":"Where the purchased label can be downloaded."},"cost":{"type":"string","example":"8.45"},"fromAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"parcels":{"type":"array","items":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}}},"products":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Lines included in this shipment."}}}}}}}},"400":{"description":"Shipping integration not configured. Please configure EasyPost or another shipping provider. — Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\".","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Shipping integration not configured. Please configure EasyPost or another shipping provider.","path":"/shipping/order/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"],"summary":"Create a shipment for an order","description":"Buys a label for an order and records the shipment against it. **This spends money.**\n\nSupports partial shipments through `productSkus` — ship what is in stock now and the rest later, and the order accumulates one shipment per dispatch.\n\nPass the `rate` object from `POST /shipping/order/rates` unchanged.\n\n#### Signature\n\n```http\nPOST /shipping/order/create (body) -> The created shipment with its label\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Buys a real label. Not idempotent — check `GET /shipping/order/shipments/{orderNumber}` before retrying.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PROVIDER_NOT_CONFIGURED | Shipping integration not configured. Please configure EasyPost or another shipping provider. | Neither the org nor the shared org has an active config whose `useCases` include `Shipping`. When the shared org is reached but has none either, the response is instead a `404` \"Integration with useCase Shipping not found in org <shared org>\". | Configure a carrier integration — `GET /shipping/admin/providers` lists what is supported. Using the platform's shared carrier needs the org to accept its service agreement (a `402` otherwise). |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/order/rates`\n- `POST /shipping/order/manual`","requestBody":{"description":"The order, the chosen rate, and optionally which lines.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderNumber","rate"],"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"rate":{"type":"object","description":"The rate object from the order rates call, unchanged.","additionalProperties":true,"properties":{"id":{"type":"string","example":"rate_abc123"},"carrier":{"type":"string","example":"USPS"},"service":{"type":"string","example":"Priority"},"rate":{"type":"string","example":"8.45"},"currency":{"type":"string","example":"USD"},"delivery_days":{"type":"number","example":2}}},"productSkus":{"type":"array","items":{"type":"string"},"description":"Lines in this shipment. Omit for everything outstanding.","example":["DRK-COLA-330"]},"fromLocationId":{"type":"string","example":"loc_warehouse"}}},"example":{"orderNumber":"A7K2M9QX4","rate":{"id":"rate_abc123","carrier":"USPS","service":"Priority","rate":"8.45"},"productSkus":["DRK-COLA-330"]}}}}}},"/shipping/order/manual":{"post":{"operationId":"ShippingController_addManualShipping","summary":"Add manual shipping info to an order","description":"Records shipping details for a parcel sent **outside** the carrier integration — a label bought at a post office counter, a courier booked directly, a local delivery driver. No carrier account is involved and no label is purchased.\n\nA tracking URL is generated automatically for carriers the platform recognises; pass `trackingUrl` for anything else.\n\nThe customer is emailed unless you pass `sendNotification: false`.\n\n#### Signature\n\n```http\nPOST /shipping/order/manual (body) -> The updated order with its shipping info\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- No carrier integration is needed, so this works even when no provider is configured.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/order/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The order and the shipping details to record.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderNumber","shippingInfo"],"properties":{"orderNumber":{"type":"string","example":"A7K2M9QX4"},"shippingInfo":{"type":"object","properties":{"carrier":{"type":"string","description":"Carrier name, or a description like `Local Delivery`.","example":"FedEx"},"tracker":{"type":"string","description":"Tracking number.","example":"794644790134"},"trackingUrl":{"type":"string","description":"Auto-generated for known carriers when omitted.","example":"https://www.fedex.com/fedextrack/?trknbr=794644790134"},"rate":{"type":"string","description":"Service name.","example":"Ground"},"cost":{"type":"string","example":"11.20"},"parcel":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}},"products":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"}}},"description":"Lines in this shipment."}}},"sendNotification":{"type":"boolean","default":true,"description":"`false` records the shipment without emailing the customer.","example":true}}},"examples":{"courier":{"summary":"Label bought at the counter","value":{"orderNumber":"A7K2M9QX4","shippingInfo":{"carrier":"FedEx","tracker":"794644790134","rate":"Ground","cost":"11.20"}}},"localDelivery":{"summary":"Local delivery, no tracking","value":{"orderNumber":"A7K2M9QX4","shippingInfo":{"carrier":"Local Delivery","rate":"Same day"},"sendNotification":true}}}}}},"responses":{"201":{"description":"The updated order with its shipping info","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/calculate":{"post":{"operationId":"ShippingController_calculateCartShipping","summary":"Calculate cart shipping cost","description":"Computes shipping for a cart from the org's shipping configuration — flat, weight-banded, zone-based or live carrier rates, whichever the config specifies — including any free-shipping threshold.\n\n#### Signature\n\n```http\nPOST /shipping/calculate (body) -> The calculated shipping cost\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Pass `orderTotal` or a free-shipping threshold cannot be evaluated and the customer will be charged.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/product-cost`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The cart and destination.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Cart lines."},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"orderTotal":{"type":"number","description":"Used to evaluate the free-shipping threshold.","example":129.99}}},"example":{"items":[{"sku":"DRK-COLA-330","quantity":2}],"toAddress":{"city":"Boston","state":"MA","zip":"02108","country":"US"},"orderTotal":129.99}}}},"responses":{"201":{"description":"The calculated shipping cost","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/options":{"post":{"operationId":"ShippingController_getShippingOptions","summary":"Shipping options for a cart and destination","description":"Every way this cart can be shipped to this address, cheapest first, following the shipping rules: a configuration scoped to the destination (country / state / postcode) beats an unscoped one, specificity then priority break ties, and per-product rules come first. Carrier configurations return one option per service.\n\nWhen items need different configurations the cart is split: each option's `amount` is the whole order's shipping and `groups` says how every part ships. Products priced \"free\" or \"flat\" on the product itself are folded in (`breakdown.forced`).\n\n`served: false` means no configuration ships there — `problems` and `message` say why; the answer is honest, not a guessed rate. A free-shipping promotion (automatic, or via `discountCode`) is applied after pricing: it frees the cheapest option, or every option when the promotion is set to `any`, marking them `freeShipping` with a `freeReason`. How to present the list is the client's call.\n\n#### Signature\n\n```http\nPOST /shipping/options (body) -> { served, options[], currency, problems?, message? }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Nothing configured at all returns `served: false` with \"Shipping has not been set up yet — add a shipping configuration to quote rates\".\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/calculate`\n- `POST /shipping/product-cost`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items","toAddress"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"sku":{"type":"string"},"quantity":{"type":"number"}}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"fromAddress":{"type":"object","description":"Origin. Optional — the configuration's origin or the org location otherwise.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"orderTotal":{"type":"number","description":"For free-over thresholds. Computed from the items when omitted."},"discountCode":{"type":"string","description":"Optional coupon; automatic promotions apply without one."}}},"example":{"items":[{"sku":"DRK-COLA-330","quantity":2}],"toAddress":{"street1":"1 Main St","city":"Boston","state":"MA","zip":"02108","country":"US"},"orderTotal":42}}}},"responses":{"201":{"description":"{ served, options[], currency, problems?, message? }","content":{"application/json":{"schema":{"type":"object","properties":{"served":{"type":"boolean"},"currency":{"type":"string","example":"USD"},"message":{"type":"string"},"problems":{"type":"array","items":{"type":"object","properties":{"config":{"type":"string"},"reason":{"type":"string"}}}},"options":{"type":"array","items":{"type":"object","properties":{"config":{"type":"string"},"label":{"type":"string","example":"Standard"},"method":{"type":"string","enum":["free","flat","weight","carrier","pickup"]},"provider":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"freeReason":{"type":"string"},"etaDays":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"text":{"type":"string"}}},"breakdown":{"type":"object","properties":{"base":{"type":"number"},"handling":{"type":"number"},"markup":{"type":"number"},"forced":{"type":"number"}}},"dimensionsEstimated":{"type":"boolean"},"pickup":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"string"}},"instructions":{"type":"string"},"readyInHours":{"type":"number"}}},"groups":{"type":"array","items":{"type":"object","properties":{"config":{"type":"string"},"label":{"type":"string"},"method":{"type":"string"},"amount":{"type":"number"},"items":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/product-cost":{"post":{"operationId":"ShippingController_getProductShippingCost","summary":"Get shipping cost for one product","description":"Shipping cost for a single product, for display on a product page (\"+ $4.99 shipping\"). Falls back to a US destination and the org's own location when addresses are omitted, so it can be called before a customer has entered anything.\n\n#### Signature\n\n```http\nPOST /shipping/product-cost (body) -> The product's shipping cost\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- The default destination makes the figure indicative only — recompute at checkout with the real address.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /shipping/calculate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The product and, optionally, where it is going.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","default":1,"example":1},"toAddress":{"type":"object","description":"Destination. Defaults to a US address when omitted.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}},"fromAddress":{"type":"object","description":"Origin. Defaults to the org location.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}}}},"example":{"sku":"DRK-COLA-330","quantity":1}}}},"responses":{"201":{"description":"The product's shipping cost","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping"]}},"/shipping/admin/providers":{"get":{"operationId":"ShippingController_getShippingProviderTypes","summary":"List supported shipping providers","description":"The carrier provider types the platform supports — EasyPost, Shippo, FedEx and so on — each with a description and setup help. This is a platform-level list and takes no org.\n\n#### Signature\n\n```http\nGET /shipping/admin/providers () -> Supported provider types\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The only endpoint here that does not read the `orgid` header — the list is the same for every org.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /shipping/admin/integrations`","parameters":[],"responses":{"200":{"description":"Supported provider types","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/integrations":{"get":{"operationId":"ShippingController_getShippingIntegrations","summary":"Get configured shipping integrations","description":"The carrier integrations this org has configured, alongside the providers still available to add.\n\n#### Signature\n\n```http\nGET /shipping/admin/integrations () -> Configured integrations and available providers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /shipping/admin/providers`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Configured integrations and available providers","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/configs":{"get":{"operationId":"ShippingController_listShippingConfigs","summary":"List shipping configurations","description":"All shipping rate configurations for the org. One is the site default; the rest are selected per product or per config name.\n\n#### Signature\n\n```http\nGET /shipping/admin/configs () -> The org's shipping configurations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/configs`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The org's shipping configurations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]},"post":{"operationId":"ShippingController_createShippingConfig","summary":"Create a shipping configuration","description":"Creates a rate configuration. `method` picks the pricing model and decides which of the other blocks matter:\n\n- `free` — no charge.\n- `flat` — a fixed rate, optionally per item. Uses `flatRate`.\n- `weight` — banded by weight. Uses the weight tiers and `defaultRate`.\n- `zone` — banded by destination.\n- `carrier` — live rates from the configured carrier. Uses `carrier` and `origin`.\n\n`freeShipping` and `handling` apply on top of any method.\n\n#### Signature\n\n```http\nPOST /shipping/admin/configs (body) -> The created configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `name` is the identifier for every other config endpoint, so pick it carefully — there is no rename.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/configs/{name}`\n- `POST /shipping/admin/preview-rate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The configuration to create.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","method"],"properties":{"name":{"type":"string","description":"Unique slug. This is the identifier used by the other config endpoints.","example":"standard-flat"},"title":{"type":"string","example":"Standard shipping"},"method":{"type":"string","enum":["free","flat","weight","zone","carrier"],"example":"flat"},"isDefault":{"type":"boolean","description":"Make this the site default.","example":true},"currency":{"type":"string","default":"USD","example":"USD"},"flatRate":{"type":"object","properties":{"rate":{"type":"number","example":4.99},"perItem":{"type":"boolean","description":"Charge the rate per item instead of per order.","example":false}}},"weight":{"type":"object","description":"Weight-banded rates. Used when `method` is `weight`.","properties":{"weightUnit":{"type":"string","example":"lb"},"dimensionUnit":{"type":"string","example":"in"},"tiers":{"type":"array","items":{"type":"object","additionalProperties":true}},"defaultRate":{"type":"number","example":9.99}}},"freeShipping":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"threshold":{"type":"number","description":"Order total at which shipping becomes free.","example":75}}},"handling":{"type":"object","properties":{"feePerOrder":{"type":"number","example":1.5},"feePerItem":{"type":"number","example":0.25}}},"origin":{"type":"object","additionalProperties":true,"description":"Ship-from address for rate calculation."},"carrier":{"type":"object","additionalProperties":true,"description":"Carrier settings, used when `method` is `carrier`."},"restrictions":{"type":"object","additionalProperties":true,"description":"Where this configuration may be used."}}},"examples":{"flat":{"summary":"Flat rate with free shipping over $75","value":{"name":"standard-flat","title":"Standard shipping","method":"flat","isDefault":true,"currency":"USD","flatRate":{"rate":4.99,"perItem":false},"freeShipping":{"enabled":true,"threshold":75}}},"carrier":{"summary":"Live carrier rates","value":{"name":"live-rates","title":"Carrier rates","method":"carrier","currency":"USD","handling":{"feePerOrder":1.5}}}}}}},"responses":{"201":{"description":"The created configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/configs/{name}":{"get":{"operationId":"ShippingController_getShippingConfig","summary":"Get a shipping configuration","description":"Fetches one shipping configuration by name, including its rate rules, free-shipping threshold and handling fees.\n\n#### Signature\n\n```http\nGET /shipping/admin/configs/{name} (name: string) -> The shipping configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CONFIG_NOT_FOUND | Shipping configuration not found | No config in the org has that name. | List them with `GET /shipping/admin/configs`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/configs/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Shipping config name (slug).","schema":{"type":"string"},"example":"standard-flat"}],"responses":{"200":{"description":"The shipping configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Shipping configuration not found — No config in the org has that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping configuration not found","path":"/shipping/admin/configs/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]},"post":{"operationId":"ShippingController_updateShippingConfig","summary":"Update a shipping configuration","description":"Updates an existing configuration. Note this is a `POST`, not a `PUT` — the whole config admin surface uses `POST` for writes, including delete.\n\n#### Signature\n\n```http\nPOST /shipping/admin/configs/{name} (name: string, body) -> The updated configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Test a change with `POST /shipping/admin/preview-rate` before making it the default.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CONFIG_NOT_FOUND | Shipping configuration not found | No config has that name. | Check the name with `GET /shipping/admin/configs`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/preview-rate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Shipping config name (slug).","schema":{"type":"string"},"example":"standard-flat"}],"requestBody":{"description":"The fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"flatRate":{"rate":5.99,"perItem":false},"freeShipping":{"enabled":true,"threshold":100}}}}},"responses":{"201":{"description":"The updated configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Shipping configuration not found — No config has that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping configuration not found","path":"/shipping/admin/configs/{name}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/configs/delete/{name}":{"post":{"operationId":"ShippingController_deleteShippingConfig","summary":"Delete a shipping configuration","description":"Deletes a shipping configuration.\n\nNote the unusual shape: deletion is a `POST` to `/delete/{name}` rather than a `DELETE`. Products still pointing at the deleted config fall back to the site default.\n\n#### Signature\n\n```http\nPOST /shipping/admin/configs/delete/{name} (name: string) -> Confirmation of the delete\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Check which products reference the config before deleting — they silently fall back to the default.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CONFIG_NOT_FOUND | Shipping configuration not found | No config has that name. | Check the name first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/configs/set-default/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Shipping config name (slug).","schema":{"type":"string"},"example":"standard-flat"}],"responses":{"201":{"description":"Confirmation of the delete","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Shipping configuration not found — No config has that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping configuration not found","path":"/shipping/admin/configs/delete/{name}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/configs/set-default/{name}":{"post":{"operationId":"ShippingController_setDefaultShippingConfig","summary":"Set the default shipping configuration","description":"Makes one configuration the site default — what applies to any product that does not name its own. Setting a new default clears the flag on the previous one.\n\n#### Signature\n\n```http\nPOST /shipping/admin/configs/set-default/{name} (name: string) -> Confirmation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CONFIG_NOT_FOUND | Shipping configuration not found | No config has that name. | Check the name first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /shipping/admin/configs`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Shipping config name (slug).","schema":{"type":"string"},"example":"standard-flat"}],"responses":{"201":{"description":"Confirmation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Shipping configuration not found — No config has that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Shipping configuration not found","path":"/shipping/admin/configs/set-default/{name}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/product/shipping":{"post":{"operationId":"ShippingController_updateProductShipping","summary":"Update shipping settings for a product","description":"Sets a product's shipping settings — its dimensions, weight, and which shipping config applies to it.\n\n#### Signature\n\n```http\nPOST /shipping/admin/product/shipping (body) -> Confirmation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Weight and dimensions matter for `weight`-method configs and for live carrier rates — a product without them will be quoted badly.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/products/shipping`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The product and its shipping settings.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","description":"Product id or SKU.","example":"DRK-COLA-330"},"shipping":{"type":"object","additionalProperties":true,"properties":{"config":{"type":"string","description":"Shipping config name to use for this product.","example":"standard-flat"},"weight":{"type":"number","example":0.8},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}}}}},"example":{"productId":"DRK-COLA-330","shipping":{"config":"standard-flat","weight":0.8,"length":3,"width":3,"height":5}}}}},"responses":{"201":{"description":"Confirmation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/products/shipping":{"post":{"operationId":"ShippingController_bulkUpdateProductShipping","summary":"Bulk update product shipping settings","description":"Applies the same shipping settings to many products at once — the practical way to move a whole category onto a new shipping config.\n\n#### Signature\n\n```http\nPOST /shipping/admin/products/shipping (body) -> Confirmation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The same settings go to every product — send dimensions only when they genuinely apply to all of them.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/product/shipping`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The products and the settings to apply to all of them.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["productIds","shipping"],"properties":{"productIds":{"type":"array","items":{"type":"string"},"description":"Product ids or SKUs.","example":["DRK-COLA-330","DRK-COLA-500"]},"shipping":{"type":"object","additionalProperties":true,"properties":{"config":{"type":"string","description":"Shipping config name.","example":"standard-flat"}}}}},"example":{"productIds":["DRK-COLA-330","DRK-COLA-500"],"shipping":{"config":"standard-flat"}}}}},"responses":{"201":{"description":"Confirmation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/preview-rate":{"post":{"operationId":"ShippingController_previewShippingRate","summary":"Preview a rate calculation","description":"Runs a shipping configuration against a test parcel and returns what it would charge, without creating any record or contacting a carrier for a real quote.\n\nThis is how a rate change gets verified before it reaches customers. Omit `configName` to test the default, and pass `productPrice` so any free-shipping threshold is exercised too.\n\n#### Signature\n\n```http\nPOST /shipping/admin/preview-rate (body) -> The rate the configuration would charge\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Writes nothing and buys nothing — safe to call as often as you like.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/configs/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The configuration and the test parcel.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configName":{"type":"string","description":"Config to test. Omit for the default.","example":"standard-flat"},"productPrice":{"type":"number","description":"Order value, so the free-shipping threshold is evaluated.","example":80},"parcel":{"type":"object","description":"A physical package. Units follow the org's shipping configuration.","properties":{"length":{"type":"number","example":12},"width":{"type":"number","example":9},"height":{"type":"number","example":4},"weight":{"type":"number","example":2.5}}},"toAddress":{"type":"object","description":"A shipping address in the carrier's field naming.","properties":{"name":{"type":"string","example":"Ada Lovelace"},"company":{"type":"string"},"street1":{"type":"string","example":"12 Ada Way"},"street2":{"type":"string"},"city":{"type":"string","example":"Newark"},"state":{"type":"string","example":"NJ"},"zip":{"type":"string","example":"07102"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"phone":{"type":"string","example":"+15551234567"},"email":{"type":"string","example":"ada@example.com"}}}}},"examples":{"belowThreshold":{"summary":"Below the free-shipping threshold","value":{"configName":"standard-flat","productPrice":40,"parcel":{"length":12,"width":9,"height":4,"weight":2.5}}},"aboveThreshold":{"summary":"Above the threshold — expect zero","value":{"configName":"standard-flat","productPrice":120,"parcel":{"length":12,"width":9,"height":4,"weight":2.5}}}}}}},"responses":{"201":{"description":"The rate the configuration would charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/calculate-packing":{"post":{"operationId":"ShippingController_calculatePacking","summary":"Preview how items would be packed","description":"Shows how items would be distributed into boxes without creating a shipment — which box sizes get used and what goes in each.\n\nPass an `orderNumber` to pack the order's items, or supply `items` inline to test a hypothetical basket. Useful for checking box sizes are configured sensibly before a rate quote surprises you.\n\n#### Signature\n\n```http\nPOST /shipping/admin/calculate-packing (body) -> The packing breakdown, with box assignments\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /shipping/admin/preview-rate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to pack. Send an order number or items, not both.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderNumber":{"type":"string","description":"Pull the items from this order.","example":"A7K2M9QX4"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"sku":{"type":"string"},"quantity":{"type":"number"}}},"description":"Inline items, as an alternative to `orderNumber`."}}},"examples":{"fromOrder":{"summary":"Pack an order","value":{"orderNumber":"A7K2M9QX4"}},"inline":{"summary":"Pack a hypothetical basket","value":{"items":[{"sku":"DRK-COLA-330","quantity":24}]}}}}}},"responses":{"201":{"description":"The packing breakdown, with box assignments","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/stats":{"get":{"operationId":"ShippingController_getShippingStats","summary":"Get shipping statistics","description":"Aggregate shipping figures for the org — volume, spend and carrier mix.\n\n#### Signature\n\n```http\nGET /shipping/admin/stats () -> Aggregate shipping statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /shipping/list`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Aggregate shipping statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/shipments":{"get":{"operationId":"ShippingController_listShipments","summary":"Shipments list","description":"One page of shipments, searched, filtered and sorted on the server. Query: `search` (tracking, order number, shipment id, reference, recipient name or email), `period` (7d, 30d, 90d, 12m, ytd, all) or `from`/`to`, `carrier` (as shown, comma-separated), `service`, `status` (shipped, in_transit, out_for_delivery, delivered, returned, exception, refund_pending, refunded, cancelled), `sort` (date, cost, status, carrier, to, tracking), `dir` (asc|desc), `page`, `pageSize` (max 200).\n\nEach row: id, date, to, status / statusLabel / statusTone, carrier / carrierName, service, tracking, trackingUrl, cost (what the org paid — see `costBasis`), refundStatus, orderNumber, transitDays, canCancel.\n\n#### Signature\n\n```http\nGET /shipping/admin/shipments () -> { rows[], total, page, pageSize, statuses[], costBasis }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /shipping/admin/analytics`\n- `GET /shipping/admin/shipments/export`\n- `POST /shipping/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"{ rows[], total, page, pageSize, statuses[], costBasis }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/shipments/export":{"get":{"operationId":"ShippingController_exportShipments","summary":"Export shipments as CSV","description":"The same filters as the Shipments list, written to a CSV by a background `export` job. Returns the job; the download link arrives by email and platform notice.\n\n#### Signature\n\n```http\nGET /shipping/admin/shipments/export () -> The background job record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /shipping/admin/shipments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The background job record","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/shipping/admin/analytics":{"get":{"operationId":"ShippingController_getShippingAnalytics","summary":"Shipping analytics","description":"Query: `period` (7d, 30d, 90d, 12m, ytd, all; default 30d) or `from`/`to`, `carrier`, `service`, `groupBy` (date, week, month, year; chosen from the span when omitted). Buckets use the `x-client-timezone` header.\n\nReturns `tiles` {totalSpend, labels, costPerPackage, avgTransitDays}, `series` [{bucket, label, spend, labels, costPerPackage}], `carrierSplit` [{carrier, spend, labels, costPerPackage, share}], `serviceSplit` [{carrier, service, spend, costPerPackage, labels}], `totals`, `refunded` {labels, amount}, `filters` (carriers and services in the period) and `spendBasis`.\n\nSpend is what the org paid: the amount charged to its balance for labels on the platform carrier account, the carrier rate for labels on its own account. Refunded labels are excluded.\n\n#### Signature\n\n```http\nGET /shipping/admin/analytics () -> Shipping analytics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /shipping/admin/shipments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-timezone","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Shipping analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Shipping · Admin"]}},"/storefront/pricing/calculate":{"post":{"operationId":"PricingController_calculatePrice","summary":"Calculate a product price","description":"Resolves what one product costs for the calling customer at a given quantity.\n\nPricing runs as an ordered pipeline, and the first stage that produces a price stops the search for a base:\n\n1. The product's base price, or the absolute price of a matched variation.\n2. Product-level **tiered** pricing, when the quantity qualifies.\n3. Product-level **group** pricing, when the customer is in a qualifying group.\n4. **Price lists**, used only as a fallback when none of the above applied.\n5. **Group benefits** — a further discount from the customer's group.\n6. **Auto-apply discounts**.\n\nPer-option surcharges are deliberately added *after* the pipeline, not folded into the base: tier and price-list prices are themselves base prices, so adding the surcharge first would let a tier overwrite it.\n\nThe customer is taken from the authenticated caller, not the body — an anonymous request gets anonymous pricing. Use `preview-as-customer` to price as someone else.\n\n#### Signature\n\n```http\nPOST /storefront/pricing/calculate (body) -> The resolved price, with everything that contributed\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The price depends on who is calling. Do not cache a result across customers.\n- `quantity` changes the *unit* price when a tier applies — it is not just a multiplier.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRODUCT_NOT_FOUND | The requested resource was not found | The `sku` does not resolve to a product in the org. | Check the SKU with `GET /storefront/products`. The server knows which one was missing but does not tell you: the underlying error is a plain `Error`, and the global filter rewrites its message to the generic text for anything that is not an `HttpException`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pricing/calculate-cart`\n- `POST /storefront/pricing/preview-as-customer`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The resolved price, with everything that contributed","content":{"application/json":{"schema":{"type":"object","properties":{"originalPrice":{"type":"number","description":"Base price before the pipeline ran.","example":12},"finalPrice":{"type":"number","description":"Unit price after every rule.","example":9.6},"unitPrice":{"type":"number","description":"Same as `finalPrice`. Kept for clients that read this name.","example":9.6},"totalPrice":{"type":"number","description":"`finalPrice × quantity`.","example":19.2},"discount":{"type":"number","description":"Absolute amount taken off the unit price.","example":2.4},"discountPercent":{"type":"number","example":20},"quantity":{"type":"number","example":2},"currency":{"type":"string","description":"From the product, defaulting to `USD`.","example":"USD"},"appliedDiscounts":{"type":"array","description":"Every rule that contributed, in the order it applied.","items":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"summer-sale"},"amount":{"type":"number","example":2.4}}}},"appliedRule":{"type":"object","additionalProperties":true,"description":"The winning price rule, when one won."}}},"example":{"originalPrice":12,"finalPrice":9.6,"unitPrice":9.6,"totalPrice":115.2,"discount":2.4,"discountPercent":20,"quantity":12,"currency":"USD","appliedDiscounts":[{"name":"bulk-12","amount":2.4}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource was not found — The `sku` does not resolve to a product in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"The requested resource was not found","path":"/storefront/pricing/calculate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"requestBody":{"description":"The product and quantity to price.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku"],"properties":{"sku":{"type":"string","description":"Product SKU.","example":"DRK-COLA-330"},"quantity":{"type":"number","default":1,"description":"Quantity. Drives tier selection, so it changes the unit price.","example":12}}},"examples":{"single":{"summary":"One unit","value":{"sku":"DRK-COLA-330"}},"tierQuantity":{"summary":"A quantity that may hit a tier","value":{"sku":"DRK-COLA-330","quantity":12}}}}}}}},"/storefront/pricing/calculate-cart":{"post":{"operationId":"PricingController_calculateCartPrices","summary":"Calculate cart prices","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The priced cart with totals and applied discounts","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Prices a whole cart in one pass, including coupon application and any automatic discounts.\n\nThis is handled by the discount service rather than the pricing service, deliberately: cart-level discounting is a single source of truth, so a coupon and an auto-apply rule cannot both claim the same basket through different code paths.\n\nProducts and rentals are priced together but on their own terms — pass each in its own array.\n\n**Render `total` as given.** It already includes tax and shipping. A client that computes `subtotal + shipping - discount` drops tax entirely — and agrees with the server on tax-free destinations, which is exactly why that bug survives review.\n\n#### Signature\n\n```http\nPOST /storefront/pricing/calculate-cart (body) -> The priced cart with totals and applied discounts\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- An invalid coupon does not fail the request — inspect the response to find out whether it applied.\n- A product's `data.calculatedPrice` is an OBJECT — `{ finalPrice, originalPrice, discount, discountPercent, appliedDiscounts }` — not a number. Read `.finalPrice`; rendering the object yields `[object Object]`.\n- Checkbox-style options contribute the SUM of every checked option's price. Quantity multiplies the line and is not a delta.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/discounts/apply`\n- `POST /storefront/pricing/calculate`","requestBody":{"description":"The cart to price.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productItems":{"type":"array","description":"Ordinary product lines.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","example":2},"options":{"type":"array","description":"Chosen configurable-product options. A price delta is counted ONLY when it arrives here, with a numeric `price`. Choices recorded in a freeform `attributes` object are displayed but never charged.","items":{"type":"object","properties":{"name":{"type":"string","example":"color"},"label":{"type":"string","example":"Colour"},"value":{"type":"string","example":"Oak"},"price":{"type":"number","example":12}}}}}}},"rentalItems":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Rental lines, priced on their own rules."},"couponCode":{"type":"string","description":"Promo code to validate and apply. An invalid code is reported in the response rather than thrown.","example":"SUMMER20"},"shippingAddress":{"type":"object","additionalProperties":true,"description":"Used where a discount or price depends on destination."}}},"examples":{"products":{"summary":"A product-only cart","value":{"productItems":[{"sku":"DRK-COLA-330","quantity":2}]}},"withCoupon":{"summary":"With a coupon","value":{"productItems":[{"sku":"DRK-COLA-330","quantity":2}],"couponCode":"SUMMER20"}}}}}}}},"/storefront/pricing/product/{sku}":{"get":{"operationId":"PricingController_getProductPricingInfo","summary":"Get pricing variations for a product","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"DRK-COLA-330"}],"responses":{"200":{"description":"The pricing variations available to this customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource was not found — The `sku` does not resolve to a product in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"The requested resource was not found","path":"/storefront/pricing/product/{sku}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Returns every price this product can take for the calling customer — the tiers, the group prices and the price-list entries that could apply — rather than resolving a single one.\n\nUse it to render a \"buy 12 for $9 each\" table, where the customer needs to see the ladder rather than just the price at their current quantity.\n\n#### Signature\n\n```http\nGET /storefront/pricing/product/{sku} (sku: string) -> The pricing variations available to this customer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRODUCT_NOT_FOUND | The requested resource was not found | The `sku` does not resolve to a product in the org. | Check the SKU with `GET /storefront/products`. The server knows which one was missing but does not tell you: the underlying error is a plain `Error`, and the global filter rewrites its message to the generic text for anything that is not an `HttpException`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pricing/calculate`"}},"/storefront/pricing/preview/{sku}":{"get":{"operationId":"PricingController_previewPricing","summary":"Preview unit prices at several quantities (admin pricing screen)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"sku","required":true,"in":"path","schema":{"type":"string"}},{"name":"quantities","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Pricing"]}},"/storefront/pricing/customer-price-lists":{"get":{"operationId":"PricingController_getCustomerPriceLists","summary":"Get the calling customer's price lists","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The customer's applicable price lists and groups","content":{"application/json":{"schema":{"type":"object","properties":{"priceLists":{"type":"array","items":{"type":"object","description":"A price list (`sf_price_list`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Unique name. Doubles as the identifier in the path and **cannot be changed** by an update.","example":"wholesale"},"title":{"type":"string","example":"Wholesale pricing"},"status":{"type":"string","description":"Only `active` lists are considered when resolving a customer's pricing.","example":"active"},"priority":{"type":"number","description":"Higher wins when several lists target the same customer. Lists are resolved in descending priority.","example":10},"currency":{"type":"string","example":"USD"},"prices":{"type":"array","description":"The prices this list sets.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","example":9},"minQuantity":{"type":"number","description":"Quantity at which this price starts applying.","example":12}}}},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups this list targets.","example":["wholesale"]},"customerEmails":{"type":"array","items":{"type":"string"},"description":"Individual customers this list targets."}}}}},"description":"Active, targeting this customer, highest priority first."},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups the customer belongs to.","example":["wholesale"]}}},"example":{"priceLists":[],"customerGroups":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Returns the active price lists that target the signed-in customer, ordered by descending priority, together with the groups they belong to.\n\nAn anonymous caller gets empty arrays rather than an error, so a storefront can call this before sign-in without special-casing.\n\n#### Signature\n\n```http\nGET /storefront/pricing/customer-price-lists () -> The customer's applicable price lists and groups\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Anonymous callers receive `{ priceLists: [], customerGroups: [] }` with a `200`.\n- Only lists with `status: \"active\"` are considered — a draft list never appears here.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pricing/price-lists`"}},"/storefront/pricing/price-lists":{"get":{"operationId":"PricingController_listPriceLists","summary":"List price lists","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"All price lists","content":{"application/json":{"schema":{"type":"object","properties":{"priceLists":{"type":"array","items":{"type":"object","description":"A price list (`sf_price_list`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Unique name. Doubles as the identifier in the path and **cannot be changed** by an update.","example":"wholesale"},"title":{"type":"string","example":"Wholesale pricing"},"status":{"type":"string","description":"Only `active` lists are considered when resolving a customer's pricing.","example":"active"},"priority":{"type":"number","description":"Higher wins when several lists target the same customer. Lists are resolved in descending priority.","example":10},"currency":{"type":"string","example":"USD"},"prices":{"type":"array","description":"The prices this list sets.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","example":9},"minQuantity":{"type":"number","description":"Quantity at which this price starts applying.","example":12}}}},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups this list targets.","example":["wholesale"]},"customerEmails":{"type":"array","items":{"type":"string"},"description":"Individual customers this list targets."}}}}}},"total":{"type":"integer","example":3}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Returns every price list in the org, regardless of status, with a total. Unpaged.\n\n#### Signature\n\n```http\nGET /storefront/pricing/price-lists () -> All price lists\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Includes inactive and draft lists — filter on `data.status` if you only want the live ones.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pricing/price-lists`"},"post":{"operationId":"PricingController_createPriceList","summary":"Create a price list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created price list","content":{"application/json":{"schema":{"type":"object","description":"A price list (`sf_price_list`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Unique name. Doubles as the identifier in the path and **cannot be changed** by an update.","example":"wholesale"},"title":{"type":"string","example":"Wholesale pricing"},"status":{"type":"string","description":"Only `active` lists are considered when resolving a customer's pricing.","example":"active"},"priority":{"type":"number","description":"Higher wins when several lists target the same customer. Lists are resolved in descending priority.","example":10},"currency":{"type":"string","example":"USD"},"prices":{"type":"array","description":"The prices this list sets.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","example":9},"minQuantity":{"type":"number","description":"Quantity at which this price starts applying.","example":12}}}},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups this list targets.","example":["wholesale"]},"customerEmails":{"type":"array","items":{"type":"string"},"description":"Individual customers this list targets."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Creates a price list from the body as given.\n\n**Nothing is validated and nothing is de-duplicated.** There is no uniqueness check on `name`, so creating a list with an existing name succeeds and leaves two lists sharing it — after which `GET`, `PUT` and `DELETE` by that name all act on whichever the lookup returns first. Check the name is free before creating.\n\nThe record is authored as `system` rather than the calling user.\n\n#### Signature\n\n```http\nPOST /storefront/pricing/price-lists (body) -> The created price list\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Duplicate names are accepted. The name is the identifier used by every other endpoint here, so a duplicate makes those endpoints ambiguous.\n- Only `status: \"active\"` lists take part in pricing.\n- Records are authored as `system`, so the audit trail does not name the operator who created it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/pricing/price-lists/{name}`\n- `GET /storefront/pricing/price-lists`","requestBody":{"description":"The price list to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Unique name. Doubles as the identifier in the path and **cannot be changed** by an update.","example":"wholesale"},"title":{"type":"string","example":"Wholesale pricing"},"status":{"type":"string","description":"Only `active` lists are considered when resolving a customer's pricing.","example":"active"},"priority":{"type":"number","description":"Higher wins when several lists target the same customer. Lists are resolved in descending priority.","example":10},"currency":{"type":"string","example":"USD"},"prices":{"type":"array","description":"The prices this list sets.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","example":9},"minQuantity":{"type":"number","description":"Quantity at which this price starts applying.","example":12}}}},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups this list targets.","example":["wholesale"]},"customerEmails":{"type":"array","items":{"type":"string"},"description":"Individual customers this list targets."}}},"example":{"name":"wholesale","title":"Wholesale pricing","status":"active","priority":10,"currency":"USD","customerGroups":["wholesale"],"prices":[{"sku":"DRK-COLA-330","price":9,"minQuantity":12}]}}}}}},"/storefront/pricing/price-lists/{name}":{"get":{"operationId":"PricingController_getPriceList","summary":"Get a price list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Price list `name`, not its `sk`.","example":"wholesale"}],"responses":{"200":{"description":"The price list, or `null` when no list has that name","content":{"application/json":{"schema":{"type":"object","description":"A price list (`sf_price_list`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Unique name. Doubles as the identifier in the path and **cannot be changed** by an update.","example":"wholesale"},"title":{"type":"string","example":"Wholesale pricing"},"status":{"type":"string","description":"Only `active` lists are considered when resolving a customer's pricing.","example":"active"},"priority":{"type":"number","description":"Higher wins when several lists target the same customer. Lists are resolved in descending priority.","example":10},"currency":{"type":"string","example":"USD"},"prices":{"type":"array","description":"The prices this list sets.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","example":9},"minQuantity":{"type":"number","description":"Quantity at which this price starts applying.","example":12}}}},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups this list targets.","example":["wholesale"]},"customerEmails":{"type":"array","items":{"type":"string"},"description":"Individual customers this list targets."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Fetches one price list by name.\n\nA name that does not exist returns **`null` with a `200`**, not a `404` — this read does not throw. Check for a null body.\n\n#### Signature\n\n```http\nGET /storefront/pricing/price-lists/{name} (name: string) -> The price list, or `null` when no list has that name\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Unlike update and delete, a missing list is `null` + `200` here rather than a `404`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/pricing/price-lists/{name}`"},"put":{"operationId":"PricingController_updatePriceList","summary":"Update a price list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Price list `name`, not its `sk`.","example":"wholesale"}],"responses":{"200":{"description":"The updated price list","content":{"application/json":{"schema":{"type":"object","description":"A price list (`sf_price_list`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Unique name. Doubles as the identifier in the path and **cannot be changed** by an update.","example":"wholesale"},"title":{"type":"string","example":"Wholesale pricing"},"status":{"type":"string","description":"Only `active` lists are considered when resolving a customer's pricing.","example":"active"},"priority":{"type":"number","description":"Higher wins when several lists target the same customer. Lists are resolved in descending priority.","example":10},"currency":{"type":"string","example":"USD"},"prices":{"type":"array","description":"The prices this list sets.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","example":9},"minQuantity":{"type":"number","description":"Quantity at which this price starts applying.","example":12}}}},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups this list targets.","example":["wholesale"]},"customerEmails":{"type":"array","items":{"type":"string"},"description":"Individual customers this list targets."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource was not found — No price list in the org has that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"The requested resource was not found","path":"/storefront/pricing/price-lists/{name}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Merges the body into the existing list — fields you omit keep their current values.\n\n**`name` cannot be changed.** It is re-applied from the path after the merge, so sending a different `name` in the body is silently ignored rather than rejected. To rename a list, create a new one and delete the old.\n\nNote the merge is shallow: sending `prices` replaces the whole array rather than merging entries into it.\n\n#### Signature\n\n```http\nPUT /storefront/pricing/price-lists/{name} (name: string, body) -> The updated price list\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A `name` in the body is discarded — the path wins.\n- `prices` and other arrays are replaced, not merged.\n- Updates are authored as `system`, not the calling user.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRICE_LIST_NOT_FOUND | The requested resource was not found | No price list in the org has that name. | List them with `GET /storefront/pricing/price-lists`. The server knows which one was missing but does not tell you: the underlying error is a plain `Error`, and the global filter rewrites its message to the generic text for anything that is not an `HttpException`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/pricing/price-lists/{name}`\n- `DELETE /storefront/pricing/price-lists/{name}`","requestBody":{"description":"Fields to change. Omitted fields are left as they are.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Unique name. Doubles as the identifier in the path and **cannot be changed** by an update.","example":"wholesale"},"title":{"type":"string","example":"Wholesale pricing"},"status":{"type":"string","description":"Only `active` lists are considered when resolving a customer's pricing.","example":"active"},"priority":{"type":"number","description":"Higher wins when several lists target the same customer. Lists are resolved in descending priority.","example":10},"currency":{"type":"string","example":"USD"},"prices":{"type":"array","description":"The prices this list sets.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","example":9},"minQuantity":{"type":"number","description":"Quantity at which this price starts applying.","example":12}}}},"customerGroups":{"type":"array","items":{"type":"string"},"description":"Groups this list targets.","example":["wholesale"]},"customerEmails":{"type":"array","items":{"type":"string"},"description":"Individual customers this list targets."}}},"examples":{"deactivate":{"summary":"Take a list out of service","value":{"status":"inactive"}},"replacePrices":{"summary":"Replace the price table","description":"`prices` is replaced wholesale — send every entry you want to keep.","value":{"prices":[{"sku":"DRK-COLA-330","price":8.5,"minQuantity":12},{"sku":"DRK-COLA-500","price":11,"minQuantity":12}]}}}}}}},"delete":{"operationId":"PricingController_deletePriceList","summary":"Delete a price list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Price list `name`, not its `sk`.","example":"wholesale"}],"responses":{"200":{"description":"Confirmation of the delete","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource was not found — No price list in the org has that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"The requested resource was not found","path":"/storefront/pricing/price-lists/{name}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Permanently deletes a price list. This is a hard delete, not a soft one — the record is removed rather than flagged, so there is nothing to restore.\n\nCustomers currently priced by this list fall back to whatever the pipeline resolves next: another targeting list, or the product's own price. Deactivate the list first (`status: \"inactive\"`) if you want to see that effect before it becomes irreversible.\n\n#### Signature\n\n```http\nDELETE /storefront/pricing/price-lists/{name} (name: string) -> Confirmation of the delete\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Hard delete — the record is gone, not archived.\n- Prefer setting `status: \"inactive\"` to take a list out of service reversibly.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRICE_LIST_NOT_FOUND | The requested resource was not found | No price list in the org has that name. | List them with `GET /storefront/pricing/price-lists`. The server knows which one was missing but does not tell you: the underlying error is a plain `Error`, and the global filter rewrites its message to the generic text for anything that is not an `HttpException`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /storefront/pricing/price-lists/{name}`"}},"/storefront/pricing/preview-as-customer":{"post":{"operationId":"PricingController_previewAsCustomer","summary":"Preview a price as another customer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The price as that customer would see it","content":{"application/json":{"schema":{"type":"object","properties":{"originalPrice":{"type":"number","description":"Base price before the pipeline ran.","example":12},"finalPrice":{"type":"number","description":"Unit price after every rule.","example":9.6},"unitPrice":{"type":"number","description":"Same as `finalPrice`. Kept for clients that read this name.","example":9.6},"totalPrice":{"type":"number","description":"`finalPrice × quantity`.","example":19.2},"discount":{"type":"number","description":"Absolute amount taken off the unit price.","example":2.4},"discountPercent":{"type":"number","example":20},"quantity":{"type":"number","example":2},"currency":{"type":"string","description":"From the product, defaulting to `USD`.","example":"USD"},"appliedDiscounts":{"type":"array","description":"Every rule that contributed, in the order it applied.","items":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"summer-sale"},"amount":{"type":"number","example":2.4}}}},"appliedRule":{"type":"object","additionalProperties":true,"description":"The winning price rule, when one won."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource was not found — The `sku` does not resolve to a product in the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"The requested resource was not found","path":"/storefront/pricing/preview-as-customer","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Pricing"],"description":"Prices a product as a specified customer rather than the caller — the operator tool for answering \"what does this cost for that wholesale account?\" without signing in as them.\n\nOmitting `customerId` prices it anonymously, which is the useful way to see the public price.\n\n#### Signature\n\n```http\nPOST /storefront/pricing/preview-as-customer (body) -> The price as that customer would see it\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This exposes another customer's negotiated pricing — treat it as an operator endpoint and do not proxy it to a storefront.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PRODUCT_NOT_FOUND | The requested resource was not found | The `sku` does not resolve to a product in the org. | Check the SKU with `GET /storefront/products`. The server knows which one was missing but does not tell you: the underlying error is a plain `Error`, and the global filter rewrites its message to the generic text for anything that is not an `HttpException`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/pricing/calculate`","requestBody":{"description":"What to price, and as whom.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku"],"properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"quantity":{"type":"number","default":1,"example":12},"customerId":{"type":"string","description":"Customer to price as. Omit for anonymous pricing.","example":"cus_4821"}}},"examples":{"asCustomer":{"summary":"Price as a wholesale account","value":{"sku":"DRK-COLA-330","quantity":12,"customerId":"cus_4821"}},"anonymous":{"summary":"Price as an anonymous visitor","value":{"sku":"DRK-COLA-330","quantity":1}}}}}}}},"/storefront/tax/calculate":{"post":{"operationId":"TaxController_calculateCartTax","summary":"Calculate tax for a cart","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The cart to price tax for.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Cart lines. Used to derive `taxableAmount` when `subtotal` is absent.","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"price":{"type":"number","description":"Unit price. Defaults to `0` when missing.","example":12},"quantity":{"type":"number","description":"Defaults to `1` when missing.","example":2}}}},"shippingAddress":{"type":"object","description":"Destination address. Rates are resolved by country → state → county / city → zip prefix.","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"state":{"type":"string","example":"TX"},"county":{"type":"string","example":"Dallas County"},"city":{"type":"string","example":"Dallas"},"zip":{"type":"string","description":"`postalCode` is accepted as an alias.","example":"75201"},"street1":{"type":"string"},"street2":{"type":"string"}}},"shippingCost":{"type":"number","description":"Taxed by `shipping` / `all` rates when an address is supplied.","example":4.99},"subtotal":{"type":"number","description":"When present, used as `taxableAmount` directly instead of summing `items`.","example":129.99},"businessLocationId":{"type":"string","description":"Venue slug. Enables venue-restricted rates and the flat venue fallback.","example":"downtown"},"customerId":{"type":"string","description":"Checked for a tax exemption.","example":"cus_4821"},"currency":{"type":"string","description":"Echoed back. Default `USD`.","example":"USD"},"date":{"type":"string","format":"date","description":"Order date the rates must be effective on. Default today."}}},"examples":{"shipped":{"summary":"Ship to Dallas, TX","value":{"subtotal":129.99,"shippingCost":4.99,"shippingAddress":{"country":"US","state":"TX","city":"Dallas","zip":"75201"}}},"inStore":{"summary":"In-person at a venue","value":{"items":[{"sku":"DRK-COLA-330","price":12,"quantity":2}],"businessLocationId":"downtown"}}}}}},"responses":{"201":{"description":"The tax result","content":{"application/json":{"schema":{"type":"object","properties":{"taxAmount":{"type":"number","description":"Tax due, including any shipping tax.","example":10.72},"taxRate":{"type":"number","description":"Effective rate on the goods base as a **fraction** (0.0825 = 8.25%).","example":0.0825},"taxableAmount":{"type":"number","description":"The goods/services base tax was computed against.","example":129.99},"taxName":{"type":"string","description":"Receipt label for the whole stack.","example":"TX State + Dallas City"},"breakdown":{"type":"array","description":"One line per applied rate, in application order. Amounts add up to `taxAmount`.","items":{"type":"object","properties":{"name":{"type":"string","description":"Receipt label (`taxName`).","example":"TX State"},"rate":{"type":"number","description":"Percent.","example":6.25},"amount":{"type":"number","example":8.12},"compound":{"type":"boolean","description":"Present and `true` when the line was computed on base + prior tax."}}}},"source":{"type":"string","enum":["jurisdiction","location","exempt","none"],"description":"`jurisdiction` = `sf_tax_rate` rows matched; `location` = venue flat rate; `exempt` = customer is tax exempt; `none` = nothing configured."},"exempt":{"type":"boolean","example":false},"currency":{"type":"string","description":"Echo of the request `currency`, default `USD`.","example":"USD"},"configured":{"type":"boolean","description":"`false` when tax is `0` only because nothing is configured for the input."},"shippingTax":{"type":"number","description":"Tax on `shippingCost`, already included in `taxAmount`.","example":0.41}}},"example":{"taxAmount":11.13,"taxRate":0.0825,"taxableAmount":129.99,"shippingTax":0.41,"taxName":"TX State + Dallas City","breakdown":[{"name":"TX State","rate":6.25,"amount":8.12},{"name":"Dallas City","rate":2,"amount":2.6},{"name":"TX State (shipping)","rate":6.25,"amount":0.31},{"name":"Dallas City (shipping)","rate":2,"amount":0.1}],"source":"jurisdiction","exempt":false,"currency":"USD","configured":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Tax"],"description":"Tax due on a cart from its lines and destination. `taxableAmount` is `subtotal`, or `price × quantity` summed across `items` when `subtotal` is absent. When `shippingAddress` is present and jurisdiction rows match it, the cart is taxed by destination; otherwise by the venue named in `businessLocationId`. `shippingCost` is taxed separately by the rows whose `appliesTo` is `shipping` or `all`, and that tax is included in `taxAmount` (also reported as `shippingTax`). A tax-exempt `customerId` yields `0`.\n\n**How a rate is chosen.** Active `sf_tax_rate` rows effective on the order date are kept when every jurisdiction field the row specifies equals the address field (case-insensitive; `zipPrefix` is a prefix match on `zip`) and, if the row has a `businessLocationId`, it equals the order's venue. Matches are applied in `priority` order: a non-compound rate taxes the taxable base, a compound rate taxes base + tax already applied. Every line is rounded to the cent and the tax is the sum of the lines. When no row matches, the venue's `location.taxRate` is used; when there is no venue rate either, tax is `0` and `configured` is `false`.\n\n#### Signature\n\n```http\nPOST /storefront/tax/calculate (body) -> The tax result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- `taxRate` is a fraction (0.0825) for backwards compatibility; `breakdown[].rate` and `POST /storefront/tax/rate` use percent.\n- With neither a matching address nor a venue rate the result is `taxAmount: 0, configured: false` — check `configured` before treating `0` as \"no tax due\".\n- Rates are records: create / edit them with the repository API on `datatype: \"sf_tax_rate\"`.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/tax/rate`\n- `GET /storefront/tax/rates/resolve`\n- `POST /storefront/checkout-cart`"}},"/storefront/tax/rate":{"post":{"operationId":"TaxController_getTaxRateForLocation","summary":"Get the tax rate stack for an address","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The address to resolve.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["country"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"state":{"type":"string","example":"TX"},"county":{"type":"string"},"city":{"type":"string","example":"Dallas"},"zip":{"type":"string","example":"75201"},"businessLocationId":{"type":"string","description":"Include rates restricted to this venue."},"date":{"type":"string","format":"date","description":"Default today."},"appliesTo":{"type":"string","enum":["goods","services","shipping","all"],"description":"Filter to rates for this charge type. Default: everything except shipping-only rates."}}},"example":{"country":"US","state":"TX","city":"Dallas","zip":"75201"}}}},"responses":{"201":{"description":"The resolved stack","content":{"application/json":{"schema":{"type":"object","properties":{"rate":{"type":"number","description":"Combined effective **percent** of the stack (compounding included).","example":8.25},"taxName":{"type":"string","example":"TX State + Dallas City"},"jurisdiction":{"type":"string","description":"The address you sent, joined.","example":"Dallas, TX, US"},"rates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"`sf_tax_rate` record `sk`."},"name":{"type":"string","example":"Texas State Sales Tax"},"taxName":{"type":"string","example":"TX State"},"rate":{"type":"number","description":"Percent.","example":6.25},"compound":{"type":"boolean","example":false},"priority":{"type":"number","example":1},"appliesTo":{"type":"string","enum":["goods","services","shipping","all"]},"jurisdictionType":{"type":"string","enum":["country","state","county","city","zip","custom"]},"jurisdiction":{"type":"string","description":"The row's jurisdiction fields joined, e.g. `US / TX / Dallas`."},"businessLocationId":{"type":"string","description":"Present when the row is restricted to one venue."}}},"description":"Matched rows in application order."},"businessLocationId":{"type":"string"},"date":{"type":"string","format":"date","description":"The date the rows had to be effective on."},"configured":{"type":"boolean","description":"`true` when at least one row matched."}}},"example":{"rate":8.25,"taxName":"TX State + Dallas City","jurisdiction":"Dallas, TX, US","rates":[{"id":"a1b2","name":"Texas State Sales Tax","taxName":"TX State","rate":6.25,"compound":false,"priority":1,"appliesTo":"all","jurisdictionType":"state","jurisdiction":"US / TX"},{"id":"c3d4","name":"Dallas City Sales Tax","taxName":"Dallas City","rate":2,"compound":false,"priority":2,"appliesTo":"all","jurisdictionType":"city","jurisdiction":"US / TX / Dallas"}],"date":"2026-09-02","configured":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Tax"],"description":"Resolves the `sf_tax_rate` rows that apply to an address and returns them in application order with the combined percent. Same result as `GET /storefront/tax/rates/resolve`, as a POST body.\n\n**How a rate is chosen.** Active `sf_tax_rate` rows effective on the order date are kept when every jurisdiction field the row specifies equals the address field (case-insensitive; `zipPrefix` is a prefix match on `zip`) and, if the row has a `businessLocationId`, it equals the order's venue. Matches are applied in `priority` order: a non-compound rate taxes the taxable base, a compound rate taxes base + tax already applied. Every line is rounded to the cent and the tax is the sum of the lines. When no row matches, the venue's `location.taxRate` is used; when there is no venue rate either, tax is `0` and `configured` is `false`.\n\n#### Signature\n\n```http\nPOST /storefront/tax/rate (body) -> The resolved stack\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- `rate` here is a **percent**; `POST /storefront/tax/calculate` returns `taxRate` as a fraction.\n- An address with no matching row returns `rate: 0, rates: [], configured: false`.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/tax/rates/resolve`\n- `POST /storefront/tax/calculate`"}},"/storefront/tax/rates/resolve":{"get":{"operationId":"TaxController_resolveRates","summary":"Check which tax rates apply to an address","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"country","required":false,"in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2.","example":"US"},{"name":"state","required":false,"in":"query","schema":{"type":"string"},"example":"TX"},{"name":"county","required":false,"in":"query","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","schema":{"type":"string"},"example":"Dallas"},{"name":"zip","required":false,"in":"query","schema":{"type":"string"},"example":"75201"},{"name":"businessLocationId","required":false,"in":"query","description":"Venue slug; includes rates restricted to it.","schema":{"type":"string"}},{"name":"date","required":false,"in":"query","description":"YYYY-MM-DD the rows must be effective on. Default today.","schema":{"type":"string"}},{"name":"appliesTo","required":false,"in":"query","schema":{"type":"string"},"description":"`goods` | `services` | `shipping` | `all`."}],"responses":{"200":{"description":"The resolved stack","content":{"application/json":{"schema":{"type":"object","properties":{"rate":{"type":"number","description":"Combined effective **percent** of the stack (compounding included).","example":8.25},"taxName":{"type":"string","example":"TX State + Dallas City"},"jurisdiction":{"type":"string","description":"The address you sent, joined.","example":"Dallas, TX, US"},"rates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"`sf_tax_rate` record `sk`."},"name":{"type":"string","example":"Texas State Sales Tax"},"taxName":{"type":"string","example":"TX State"},"rate":{"type":"number","description":"Percent.","example":6.25},"compound":{"type":"boolean","example":false},"priority":{"type":"number","example":1},"appliesTo":{"type":"string","enum":["goods","services","shipping","all"]},"jurisdictionType":{"type":"string","enum":["country","state","county","city","zip","custom"]},"jurisdiction":{"type":"string","description":"The row's jurisdiction fields joined, e.g. `US / TX / Dallas`."},"businessLocationId":{"type":"string","description":"Present when the row is restricted to one venue."}}},"description":"Matched rows in application order."},"businessLocationId":{"type":"string"},"date":{"type":"string","format":"date","description":"The date the rows had to be effective on."},"configured":{"type":"boolean","description":"`true` when at least one row matched."}}},"example":{"rate":8.25,"taxName":"TX State + Dallas City","jurisdiction":"Dallas, TX, US","rates":[{"id":"a1b2","name":"Texas State Sales Tax","taxName":"TX State","rate":6.25,"compound":false,"priority":1,"appliesTo":"all","jurisdictionType":"state","jurisdiction":"US / TX"},{"id":"c3d4","name":"Dallas City Sales Tax","taxName":"Dallas City","rate":2,"compound":false,"priority":2,"appliesTo":"all","jurisdictionType":"city","jurisdiction":"US / TX / Dallas"}],"date":"2026-09-02","configured":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Tax"],"description":"Operator configuration check: the `sf_tax_rate` rows that would be applied to an order shipped to (or taken at) the given address / venue on the given date, in application order, with the combined percent. Use it after creating or editing rate records to confirm they match the way you expect.\n\n**How a rate is chosen.** Active `sf_tax_rate` rows effective on the order date are kept when every jurisdiction field the row specifies equals the address field (case-insensitive; `zipPrefix` is a prefix match on `zip`) and, if the row has a `businessLocationId`, it equals the order's venue. Matches are applied in `priority` order: a non-compound rate taxes the taxable base, a compound rate taxes base + tax already applied. Every line is rounded to the cent and the tax is the sum of the lines. When no row matches, the venue's `location.taxRate` is used; when there is no venue rate either, tax is `0` and `configured` is `false`.\n\n#### Signature\n\n```http\nGET /storefront/tax/rates/resolve (country?: string, state?: string, county?: string, city?: string, zip?: string, businessLocationId?: string, date?: string, appliesTo?: string) -> The resolved stack\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Every query parameter is optional; with none, only rows that specify no jurisdiction (custom rates) can match.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/tax/rate`"}},"/storefront/tax/product":{"post":{"operationId":"TaxController_calculateProductTax","summary":"Calculate tax for one product","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The tax result","content":{"application/json":{"schema":{"type":"object","properties":{"taxAmount":{"type":"number","description":"Tax due, including any shipping tax.","example":10.72},"taxRate":{"type":"number","description":"Effective rate on the goods base as a **fraction** (0.0825 = 8.25%).","example":0.0825},"taxableAmount":{"type":"number","description":"The goods/services base tax was computed against.","example":129.99},"taxName":{"type":"string","description":"Receipt label for the whole stack.","example":"TX State + Dallas City"},"breakdown":{"type":"array","description":"One line per applied rate, in application order. Amounts add up to `taxAmount`.","items":{"type":"object","properties":{"name":{"type":"string","description":"Receipt label (`taxName`).","example":"TX State"},"rate":{"type":"number","description":"Percent.","example":6.25},"amount":{"type":"number","example":8.12},"compound":{"type":"boolean","description":"Present and `true` when the line was computed on base + prior tax."}}}},"source":{"type":"string","enum":["jurisdiction","location","exempt","none"],"description":"`jurisdiction` = `sf_tax_rate` rows matched; `location` = venue flat rate; `exempt` = customer is tax exempt; `none` = nothing configured."},"exempt":{"type":"boolean","example":false},"currency":{"type":"string","description":"Echo of the request `currency`, default `USD`.","example":"USD"},"configured":{"type":"boolean","description":"`false` when tax is `0` only because nothing is configured for the input."}}},"example":{"taxAmount":1.5,"taxRate":0.0625,"taxableAmount":24,"taxName":"TX State","breakdown":[{"name":"TX State","rate":6.25,"amount":1.5}],"source":"jurisdiction","exempt":false,"currency":"USD","configured":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Tax"],"description":"The single-line counterpart to the cart calculation: `price × quantity` (default `1`) is the taxable base, resolved by `shippingAddress` when rows match it, else by the venue in `businessLocationId`. `productId` / `sku` are informational — the product is not looked up, so `price` must be supplied.\n\n**How a rate is chosen.** Active `sf_tax_rate` rows effective on the order date are kept when every jurisdiction field the row specifies equals the address field (case-insensitive; `zipPrefix` is a prefix match on `zip`) and, if the row has a `businessLocationId`, it equals the order's venue. Matches are applied in `priority` order: a non-compound rate taxes the taxable base, a compound rate taxes base + tax already applied. Every line is rounded to the cent and the tax is the sum of the lines. When no row matches, the venue's `location.taxRate` is used; when there is no venue rate either, tax is `0` and `configured` is `false`.\n\n#### Signature\n\n```http\nPOST /storefront/tax/product (body) -> The tax result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Passing `sku` without `price` taxes a base of `0` — the SKU is not resolved to a price.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/tax/calculate`","requestBody":{"description":"The product line to price tax for.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["price"],"properties":{"price":{"type":"number","description":"Unit price. Required — the product is not looked up to find it.","example":12},"quantity":{"type":"number","default":1,"example":2},"productId":{"type":"string","description":"Informational."},"sku":{"type":"string","description":"Informational.","example":"DRK-COLA-330"},"shippingAddress":{"type":"object","description":"Destination address. Rates are resolved by country → state → county / city → zip prefix.","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"US"},"state":{"type":"string","example":"TX"},"county":{"type":"string","example":"Dallas County"},"city":{"type":"string","example":"Dallas"},"zip":{"type":"string","description":"`postalCode` is accepted as an alias.","example":"75201"},"street1":{"type":"string"},"street2":{"type":"string"}}},"businessLocationId":{"type":"string","example":"downtown"},"customerId":{"type":"string","description":"Checked for a tax exemption."},"currency":{"type":"string","example":"USD"},"date":{"type":"string","format":"date"}}},"example":{"sku":"DRK-COLA-330","price":12,"quantity":2,"shippingAddress":{"country":"US","state":"TX","city":"Austin"}}}}}}},"/storefront/tax/check-exempt":{"post":{"operationId":"TaxController_checkTaxExempt","summary":"Check tax exemption status","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The exemption state","content":{"application/json":{"schema":{"type":"object","properties":{"exempt":{"type":"boolean"},"reason":{"type":"string","nullable":true,"example":"Reseller"},"certificate":{"type":"string","nullable":true,"example":"EX-99182"},"customerId":{"type":"string","nullable":true,"example":"cus_4821"},"configured":{"type":"boolean","description":"`false` when no customer matched."}}},"example":{"exempt":true,"reason":"Reseller","certificate":"EX-99182","customerId":"cus_4821","configured":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Tax"],"description":"Reads the customer record's `taxExempt` flag (with `taxExemptReason` and `taxExemptCertificate`). Looks the customer up by `customerId`, falling back to `email`. `configured: false` means no customer was found for the input — not that the customer is taxable.\n\n#### Signature\n\n```http\nPOST /storefront/tax/check-exempt (body) -> The exemption state\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/tax/apply-exemption`\n- `POST /storefront/tax/remove-exemption`","requestBody":{"description":"Who to check.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"Customer `sk`. Either this or `email`.","example":"cus_4821"},"email":{"type":"string","description":"Customer email, used when `customerId` is absent.","example":"ada@example.com"},"exemptionNumber":{"type":"string","description":"Informational."}}},"example":{"customerId":"cus_4821"}}}}}},"/storefront/tax/apply-exemption":{"post":{"operationId":"TaxController_applyTaxExemption","summary":"Apply a tax exemption to a customer","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The stored exemption state","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"exempt":{"type":"boolean"},"reason":{"type":"string","nullable":true,"example":"Reseller"},"certificate":{"type":"string","nullable":true,"example":"EX-99182"},"customerId":{"type":"string","nullable":true,"example":"cus_4821"}}},"example":{"success":true,"customerId":"cus_4821","exempt":true,"reason":"Reseller","certificate":"EX-99182"}}}},"400":{"description":"customerId or email is required — Neither `customerId` nor `email` is supplied.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"customerId or email is required","path":"/storefront/tax/apply-exemption","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Customer \"…\" not found — No customer matches `customerId` (any id) or `email`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Customer \"…\" not found","path":"/storefront/tax/apply-exemption","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Tax"],"description":"Sets `taxExempt: true` on the customer record and stores the reason and certificate number. From then on `computeOrderTax` / `calculate` / `product` charge this customer no tax (`source: \"exempt\"`).\n\n#### Signature\n\n```http\nPOST /storefront/tax/apply-exemption (body) -> The stored exemption state\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | — | customerId or email is required | Neither `customerId` nor `email` is supplied. | Send one of them. |\n| `404` | — | Customer \"…\" not found | No customer matches `customerId` (any id) or `email`. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/tax/check-exempt`\n- `POST /storefront/tax/remove-exemption`","requestBody":{"description":"The exemption to record.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"Customer `sk`. Either this or `email`.","example":"cus_4821"},"email":{"type":"string","description":"Customer email, used when `customerId` is absent.","example":"ada@example.com"},"exemptionNumber":{"type":"string","description":"Certificate / permit number. Alias of `certificate`.","example":"EX-99182"},"certificate":{"type":"string","description":"Certificate / permit number."},"reason":{"type":"string","description":"Why the customer is exempt.","example":"Reseller"},"state":{"type":"string","description":"Used to build a default reason when `reason` is absent.","example":"TX"}}},"example":{"customerId":"cus_4821","exemptionNumber":"EX-99182","reason":"Reseller"}}}}}},"/storefront/tax/remove-exemption":{"post":{"operationId":"TaxController_removeTaxExemption","summary":"Remove a tax exemption from a customer","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The cleared exemption state","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"exempt":{"type":"boolean"},"reason":{"type":"string","nullable":true,"example":"Reseller"},"certificate":{"type":"string","nullable":true,"example":"EX-99182"},"customerId":{"type":"string","nullable":true,"example":"cus_4821"}}},"example":{"success":true,"customerId":"cus_4821","exempt":false,"reason":null,"certificate":null}}}},"400":{"description":"customerId or email is required — Neither `customerId` nor `email` is supplied.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"customerId or email is required","path":"/storefront/tax/remove-exemption","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Customer \"…\" not found — No customer matches `customerId` (any id) or `email`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Customer \"…\" not found","path":"/storefront/tax/remove-exemption","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Tax"],"description":"Clears `taxExempt`, `taxExemptReason` and `taxExemptCertificate` on the customer record.\n\n#### Signature\n\n```http\nPOST /storefront/tax/remove-exemption (body) -> The cleared exemption state\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | — | customerId or email is required | Neither `customerId` nor `email` is supplied. | Send one of them. |\n| `404` | — | Customer \"…\" not found | No customer matches `customerId` (any id) or `email`. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/tax/apply-exemption`","requestBody":{"description":"Which customer.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"Customer `sk`. Either this or `email`.","example":"cus_4821"},"email":{"type":"string","description":"Customer email, used when `customerId` is absent.","example":"ada@example.com"},"exemptionId":{"type":"string","description":"Informational."}}},"example":{"customerId":"cus_4821"}}}}}},"/storefront/rental/config":{"get":{"operationId":"RentalController_getConfig","summary":"Get rental configuration","description":"Returns the org's rental settings — periods, fees and defaults. Omit `name` for the default configuration.\n\n#### Signature\n\n```http\nGET /storefront/rental/config (name?: string) -> The rental configuration\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/items`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":false,"in":"query","description":"Named configuration. Omit for the default.","schema":{"type":"string"},"example":"default"}],"responses":{"200":{"description":"The rental configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/config","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/items":{"get":{"operationId":"RentalController_listRentalItems","summary":"List rental items","description":"Lists the items available to rent, with optional status filtering and paging. Items in `maintenance` are not rentable but still listed.\n\n#### Signature\n\n```http\nGET /storefront/rental/items (status?: string, page?: integer, pageSize?: integer) -> A page of rental items\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/items/{sku}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["active","inactive","maintenance"]},"example":"active"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of rental items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A rentable item (`sf_rental_item`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}},"total":{"type":"integer","example":24}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/items","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/items/{sku}":{"get":{"operationId":"RentalController_getRentalItem","summary":"Get a rental item","description":"Fetches one rentable item by SKU, including its rates, deposit and any customer restrictions.\n\n#### Signature\n\n```http\nGET /storefront/rental/items/{sku} (sku: string) -> The rental item\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_ITEM_NOT_FOUND | Rental item not found | The SKU does not resolve to a rental item. | List rentable items with `GET /storefront/rental/items`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/items/{sku}/availability`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"sku","required":true,"in":"path","description":"Rental item SKU.","schema":{"type":"string"},"example":"CAM-RED-KOMODO"}],"responses":{"200":{"description":"The rental item","content":{"application/json":{"schema":{"type":"object","description":"A rentable item (`sf_rental_item`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental item not found — The SKU does not resolve to a rental item.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental item not found","path":"/storefront/rental/items/{sku}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/items/{sku}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/items/{sku}/availability":{"get":{"operationId":"RentalController_checkAvailability","summary":"Check rental availability","description":"Reports whether an item is free for a date range, accounting for existing bookings.\n\nAvailability is checked again when the rental is created, so a positive answer here is not a reservation — another customer can still book the window first.\n\n#### Signature\n\n```http\nGET /storefront/rental/items/{sku}/availability (sku: string, startDate?: string, endDate?: string, quantity?: integer) -> Availability for the window\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Not a hold. The authoritative check happens at `POST /storefront/rental`, which returns `409` if the window has gone.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_ITEM_NOT_FOUND | Rental item not found | The SKU does not resolve to a rental item. | List rentable items with `GET /storefront/rental/items`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /storefront/rental/items/{sku}/price`\n- `POST /storefront/rental`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"sku","required":true,"in":"path","description":"Rental item SKU.","schema":{"type":"string"},"example":"CAM-RED-KOMODO"},{"name":"startDate","required":true,"in":"query","description":"Start of the window, ISO 8601.","schema":{"type":"string"},"example":"2026-09-01T09:00:00.000Z"},{"name":"endDate","required":true,"in":"query","description":"End of the window, ISO 8601.","schema":{"type":"string"},"example":"2026-09-04T17:00:00.000Z"},{"name":"quantity","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1}],"responses":{"200":{"description":"Availability for the window","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental item not found — The SKU does not resolve to a rental item.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental item not found","path":"/storefront/rental/items/{sku}/availability","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/items/{sku}/availability","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/items/{sku}/price":{"post":{"operationId":"RentalController_calculatePrice","summary":"Calculate a rental price","description":"Prices a rental for a date range, including any optional fees the customer selects — insurance, cleaning, delivery. The rate band is chosen from the length of the window, so a week may cost less than seven days.\n\n#### Signature\n\n```http\nPOST /storefront/rental/items/{sku}/price (sku: string, body) -> The priced rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_ITEM_NOT_FOUND | Rental item not found | The SKU does not resolve to a rental item. | List rentable items with `GET /storefront/rental/items`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /storefront/rental`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"sku","required":true,"in":"path","description":"Rental item SKU.","schema":{"type":"string"},"example":"CAM-RED-KOMODO"}],"responses":{"201":{"description":"The priced rental","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental item not found — The SKU does not resolve to a rental item.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental item not found","path":"/storefront/rental/items/{sku}/price","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/items/{sku}/price","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"The window and options to price.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["startDate","endDate"],"properties":{"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"quantity":{"type":"number","default":1,"example":1},"optionalFees":{"type":"array","items":{"type":"string"},"description":"Codes of the optional fees to include.","example":["insurance"]}}},"example":{"startDate":"2026-09-01T09:00:00.000Z","endDate":"2026-09-04T17:00:00.000Z","quantity":1,"optionalFees":["insurance"]}}}}}},"/storefront/rental":{"post":{"operationId":"RentalController_createRental","summary":"Create a rental booking","description":"Books an item for a date range. The rental starts `pending`.\n\nThree checks run in order, and each has its own failure: the item must exist, it must be free for the window, and the customer must satisfy the item's restrictions. **Availability is re-checked here**, so a window that was free when you queried it can still be lost to another booking — a `409` means exactly that.\n\nFulfilment and return are described separately, so an item can be delivered and collected, picked up and dropped off, or any combination.\n\n#### Signature\n\n```http\nPOST /storefront/rental (body) -> The created rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The `403` body carries an `errors` array naming each failed restriction, rather than the standard error envelope.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_ITEM_NOT_FOUND | Rental item not found | The SKU does not resolve to a rental item. | List rentable items with `GET /storefront/rental/items`. |\n| `409` | NOT_AVAILABLE | Item not available for selected dates | The item is already booked for some part of the window. | Re-check with the availability endpoint and offer the customer another window. Availability is not held between checking and booking. |\n| `403` | RESTRICTIONS_NOT_MET | Customer restrictions not met | The customer fails one of the item's restrictions — age or location, typically. | Validate first with `POST /storefront/rental/items/{sku}/validate-restrictions`, which reports every failure at once. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/items/{sku}/availability`\n- `PUT /storefront/rental/{rentalId}/confirm`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The created rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Customer restrictions not met — The customer fails one of the item's restrictions — age or location, typically.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"message":"Customer restrictions not met","errors":[{"type":"age","message":"Must be 21 or older"}]}}}},"404":{"description":"Rental item not found — The SKU does not resolve to a rental item.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental item not found","path":"/storefront/rental","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Item not available for selected dates — The item is already booked for some part of the window.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Item not available for selected dates","path":"/storefront/rental","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"The item, window, customer and logistics.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","customer","startDate","endDate"],"properties":{"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","default":1,"example":1},"customer":{"type":"object","required":["firstName","lastName","email","phone"],"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the window is expressed in.","example":"America/New_York"},"fulfillment":{"type":"object","description":"How the customer gets the item.","properties":{"type":{"type":"string","enum":["pickup","delivery"],"example":"delivery"},"address":{"type":"object","additionalProperties":true,"description":"Postal address."},"instructions":{"type":"string","example":"Leave with the doorman"}}},"return":{"type":"object","description":"How the item comes back. Independent of `fulfillment`.","properties":{"type":{"type":"string","enum":["dropoff","pickup"],"example":"dropoff"},"address":{"type":"object","additionalProperties":true,"description":"Postal address."},"instructions":{"type":"string"}}},"optionalFees":{"type":"array","items":{"type":"string"},"example":["insurance"]},"customerNotes":{"type":"string","example":"Shooting outdoors, may need the rain cover"}}},"examples":{"pickup":{"summary":"Customer collects and returns in person","value":{"sku":"CAM-RED-KOMODO","customer":{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","phone":"+15551234567"},"startDate":"2026-09-01T09:00:00.000Z","endDate":"2026-09-04T17:00:00.000Z","fulfillment":{"type":"pickup"},"return":{"type":"dropoff"}}},"delivered":{"summary":"Delivered out, collected back","value":{"sku":"CAM-RED-KOMODO","quantity":1,"customer":{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","phone":"+15551234567"},"startDate":"2026-09-01T09:00:00.000Z","endDate":"2026-09-04T17:00:00.000Z","fulfillment":{"type":"delivery","address":{"line1":"12 Ada Way","city":"London"},"instructions":"Leave with the doorman"},"return":{"type":"pickup"},"optionalFees":["insurance"]}}}}}}},"get":{"operationId":"RentalController_listRentals","summary":"List rentals","description":"Lists rental bookings with filters and paging. Filter by customer, item, status or start-date range.\n\n#### Signature\n\n```http\nGET /storefront/rental (status?: string, customerEmail?: string, sku?: string, startDateFrom?: string, startDateTo?: string, page?: integer, pageSize?: integer) -> A page of rentals\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/status/overdue`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"]},"example":"active"},{"name":"customerEmail","required":false,"in":"query","schema":{"type":"string"},"example":"ada@example.com"},{"name":"sku","required":false,"in":"query","schema":{"type":"string"},"example":"CAM-RED-KOMODO"},{"name":"startDateFrom","required":false,"in":"query","schema":{"type":"string"},"description":"Lower bound on start date.","example":"2026-09-01"},{"name":"startDateTo","required":false,"in":"query","schema":{"type":"string"},"description":"Upper bound on start date.","example":"2026-09-30"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of rentals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}},"total":{"type":"integer","example":18}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}":{"get":{"operationId":"RentalController_getRental","summary":"Get a rental","description":"Fetches one rental with its window, customer, deposit state and both condition records.\n\n#### Signature\n\n```http\nGET /storefront/rental/{rentalId} (rentalId: string) -> The rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/status/overdue":{"get":{"operationId":"RentalController_getOverdueRentals","summary":"Get overdue rentals","description":"Every active rental past its end date and not yet returned. The chase list.\n\n#### Signature\n\n```http\nGET /storefront/rental/status/overdue () -> Overdue rentals\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Derived from the end date at request time. Marking a rental `overdue` with the status endpoint is a separate, manual flag.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/status/due-today`\n- `PUT /storefront/rental/{rentalId}/overdue`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Overdue rentals","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/status/overdue","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/status/due-today":{"get":{"operationId":"RentalController_getRentalsDueToday","summary":"Get rentals due today","description":"Rentals whose window ends today — what a counter expects back before closing.\n\n#### Signature\n\n```http\nGET /storefront/rental/status/due-today () -> Rentals ending today\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/status/overdue`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Rentals ending today","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/status/due-today","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/confirm":{"put":{"operationId":"RentalController_confirmRental","summary":"Confirm a rental","description":"Moves a pending rental to `confirmed`, committing the booking. This is the point the customer is told the item is theirs for the window.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/confirm (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/ready`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/confirm","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/confirm","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/checkout":{"put":{"operationId":"RentalController_checkOut","summary":"Record check-out condition","description":"Records the item's condition as it leaves, with optional photographs and the name of whoever inspected it.\n\nThis is the **before** half of the evidence a deposit deduction rests on. Without it there is nothing to compare the returned condition against, and a damage claim comes down to one party's word.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/checkout (rentalId: string, body) -> The rental with its check-out record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/checkin`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The rental with its check-out record","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/checkout","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/checkout","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"Condition at the point the item leaves.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["condition","checkedBy"],"properties":{"condition":{"type":"string","enum":["excellent","good","fair","poor"],"example":"excellent"},"notes":{"type":"string","example":"Body and lens both clean, no marks"},"photos":{"type":"array","items":{"type":"string"},"description":"URLs of condition photographs.","example":["https://cdn.appmint.io/rentals/rnt-4821-out-1.jpg"]},"checkedBy":{"type":"string","description":"Who inspected it.","example":"counter@venue.com"}}},"example":{"condition":"excellent","notes":"Body and lens both clean, no marks","photos":["https://cdn.appmint.io/rentals/rnt-4821-out-1.jpg"],"checkedBy":"counter@venue.com"}}}}}},"/storefront/rental/{rentalId}/checkin":{"put":{"operationId":"RentalController_checkIn","summary":"Record check-in condition","description":"Records the item's condition on return, including any damage found. The **after** half of the evidence.\n\nRecording `damages` here does not itself charge anything — add a deposit deduction to do that, and refund the remainder.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/checkin (rentalId: string, body) -> The rental with its check-in record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `damages` is descriptive only. Charge for it with `POST /storefront/rental/{rentalId}/deposit/deduction`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /storefront/rental/{rentalId}/deposit/deduction`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The rental with its check-in record","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/checkin","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/checkin","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"Condition at the point the item comes back.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["condition","checkedBy"],"properties":{"condition":{"type":"string","enum":["excellent","good","fair","poor"],"example":"good"},"notes":{"type":"string","example":"Light scuffing on the base plate"},"photos":{"type":"array","items":{"type":"string"},"example":["https://cdn.appmint.io/rentals/rnt-4821-in-1.jpg"]},"damages":{"type":"string","description":"Description of damage found. Recording it does not charge for it.","example":"Scratched lens housing"},"checkedBy":{"type":"string","example":"counter@venue.com"}}},"example":{"condition":"fair","notes":"Scratched lens housing","damages":"Scratched lens housing","photos":["https://cdn.appmint.io/rentals/rnt-4821-in-1.jpg"],"checkedBy":"counter@venue.com"}}}}}},"/storefront/rental/{rentalId}/complete":{"put":{"operationId":"RentalController_completeRental","summary":"Complete a rental","description":"Closes the rental. Settle the deposit first — refund what is owed and record any deductions — because completion is the end of the lifecycle.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/complete (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/deposit/refund`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/complete","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/complete","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/cancel":{"put":{"operationId":"RentalController_cancelRental","summary":"Cancel a rental","description":"Cancels a rental, recording the reason. Any deposit that was held must be refunded separately — cancelling does not release it.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/cancel (rentalId: string, body) -> The cancelled rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Does not refund the deposit or any payment — issue those explicitly.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/deposit/refund`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The cancelled rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/cancel","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/cancel","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"Why the rental is being cancelled.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Recorded on the rental.","example":"Customer cancelled — shoot postponed"}}},"example":{"reason":"Customer cancelled — shoot postponed"}}}}}},"/storefront/rental/{rentalId}/payment/refund":{"put":{"operationId":"RentalController_refundRentalPayment","summary":"Refund rental payment","description":"Record a refund of the rental payment (money given back by hand). Does not cancel the rental.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"rentalId","required":true,"in":"path","description":"Rental ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Rental"]}},"/storefront/rental/{rentalId}/ready":{"put":{"operationId":"RentalController_markReady","summary":"Mark a rental ready","description":"Marks the item prepared and waiting for collection or dispatch. The signal to a counter that it can be handed over.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/ready (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/picked-up`\n- `PUT /storefront/rental/{rentalId}/delivered`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/ready","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/ready","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/picked-up":{"put":{"operationId":"RentalController_markPickedUp","summary":"Mark a rental picked up","description":"Records that the customer collected the item in person, and notifies them. Use `delivered` instead when the item was sent out.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/picked-up (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/checkout`\n- `PUT /storefront/rental/{rentalId}/delivered`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/picked-up","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/picked-up","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/delivered":{"put":{"operationId":"RentalController_markDelivered","summary":"Mark a rental delivered","description":"Records that the item was delivered to the customer, and notifies them. The delivery counterpart to `picked-up`.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/delivered (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/picked-up`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/delivered","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/delivered","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/active":{"put":{"operationId":"RentalController_markActive","summary":"Mark a rental active","description":"Marks the item as in use by the customer — the state a rental sits in for the body of its window.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/active (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/overdue`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/active","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/active","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/overdue":{"put":{"operationId":"RentalController_markOverdue","summary":"Mark a rental overdue","description":"Flags a rental as overdue. This is a **manual** status change; `GET /storefront/rental/status/overdue` derives its list from dates instead and does not depend on this flag being set.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/overdue (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/status/overdue`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/overdue","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/overdue","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/dropped-off":{"put":{"operationId":"RentalController_markDroppedOff","summary":"Mark a rental dropped off","description":"Records that the customer returned the item, and notifies them. The item is back but not yet inspected — record the condition with `checkin`.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/dropped-off (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/checkin`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/dropped-off","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/dropped-off","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"]}},"/storefront/rental/{rentalId}/returned":{"put":{"operationId":"RentalController_markReturned","summary":"Mark a rental returned","description":"> **Deprecated.** Superseded by `PUT /storefront/rental/{rentalId}/dropped-off`, which it delegates to.\n\nAlias for `dropped-off`, kept for older clients. Prefer `PUT /storefront/rental/{rentalId}/dropped-off` in new work.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/returned (rentalId: string) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/dropped-off`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/returned","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/returned","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"deprecated":true}},"/storefront/rental/{rentalId}/notes":{"put":{"operationId":"RentalController_updateNotes","summary":"Update internal notes","description":"Replaces the rental's internal notes. The status is left unchanged.\n\n**A missing rental is reported oddly here:** the handler returns `{ \"error\": \"Rental not found\" }` with a `200`, rather than the `404` every other rental endpoint raises. Check the body, not the status.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/notes (rentalId: string, body) -> The updated rental, or an error object when the rental does not exist\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Replaces the notes rather than appending — read them first if you want to add to them.\n- Inconsistent with the rest of the controller: no `404` is raised for a missing rental.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /storefront/rental/{rentalId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The updated rental, or an error object when the rental does not exist","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"ok":{"summary":"Updated","value":{"data":{"rentalId":"RNT-4821","internalNotes":"Customer is a regular"}}},"missing":{"summary":"Rental not found — still a 200","value":{"error":"Rental not found"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/notes","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"The notes to store.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["notes"],"properties":{"notes":{"type":"string","description":"Replaces the existing internal notes.","example":"Customer is a regular — waive the late fee if under an hour"}}},"example":{"notes":"Customer is a regular — waive the late fee if under an hour"}}}}}},"/storefront/rental/{rentalId}/payment":{"post":{"operationId":"RentalController_recordPayment","summary":"Record a rental payment","description":"Records a payment against the rental. This books the tender; it does not charge a card — take the payment through a gateway first and record its reference here.\n\n#### Signature\n\n```http\nPOST /storefront/rental/{rentalId}/payment (rentalId: string, body) -> The updated rental\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Not idempotent — a retry records a second payment.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/deposit/hold`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"201":{"description":"The updated rental","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/payment","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/payment","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"The payment to record.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","method"],"properties":{"amount":{"type":"number","example":495},"method":{"type":"string","description":"How it was paid.","example":"card"},"transactionId":{"type":"string","description":"Gateway reference.","example":"pi_3PabcXYZ"}}},"example":{"amount":495,"method":"card","transactionId":"pi_3PabcXYZ"}}}}}},"/storefront/rental/{rentalId}/deposit/hold":{"put":{"operationId":"RentalController_holdDeposit","summary":"Record a deposit hold","description":"Records that a deposit has been held, capturing the gateway references needed to refund it later.\n\n**`transactionId` is what a later refund is issued against.** Without it the refund has no gateway reference to reverse and can only be recorded as a manual adjustment, so capture it at hold time rather than trying to reconstruct it at the end of the rental.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/deposit/hold (rentalId: string, body) -> The rental with its deposit hold recorded\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/deposit/refund`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The rental with its deposit hold recorded","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/deposit/hold","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/deposit/hold","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"The gateway references for the held deposit.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactionId"],"properties":{"transactionId":{"type":"string","description":"Reference the refund will be issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string","description":"Gateway charge id, where the provider distinguishes it.","example":"ch_3PabcXYZ"},"paymentGateway":{"type":"string","description":"Which gateway holds it.","example":"stripe"}}},"example":{"transactionId":"pi_3PabcXYZ","chargeId":"ch_3PabcXYZ","paymentGateway":"stripe"}}}}}},"/storefront/rental/{rentalId}/books":{"put":{"operationId":"RentalController_postRentalToBooks","summary":"Post rental to Books","description":"Book the money on this rental that Books does not have yet (fee, late fee, deposit held / refunded / kept), with payment records. Idempotent; for rentals paid before rentals were booked.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"rentalId","required":true,"in":"path","description":"Rental ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Rental"]}},"/storefront/rental/{rentalId}/deposit/refund":{"put":{"operationId":"RentalController_refundDeposit","summary":"Refund the deposit","description":"Returns deposit money to the customer through the **original payment gateway**, using the references captured when the deposit was held.\n\nSet `skipPaymentGateway` when the money has already been returned by other means — cash at the counter, or a refund issued directly in the provider's dashboard. That records the refund without attempting to move money a second time.\n\n#### Signature\n\n```http\nPUT /storefront/rental/{rentalId}/deposit/refund (rentalId: string, body) -> The rental with the refund recorded\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Needs the references stored by `deposit/hold`. Without them, use `skipPaymentGateway` and settle outside the platform.\n- The amount is not derived from the deductions — calculate it yourself, or you may refund more than is owed.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/deposit/hold`\n- `POST /storefront/rental/{rentalId}/deposit/deduction`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"200":{"description":"The rental with the refund recorded","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/deposit/refund","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/deposit/refund","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"How much to return, and whether to involve the gateway.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"Amount to refund — typically the deposit minus any deductions.","example":175},"skipPaymentGateway":{"type":"boolean","default":false,"description":"Record the refund without calling the gateway, for money already returned another way.","example":false},"reason":{"type":"string","example":"Deposit returned less damage deduction"}}},"examples":{"gateway":{"summary":"Refund through the gateway","value":{"amount":175,"reason":"Deposit returned less damage deduction"}},"manual":{"summary":"Record a refund paid in cash","value":{"amount":250,"skipPaymentGateway":true,"reason":"Returned in cash at the counter"}}}}}}}},"/storefront/rental/{rentalId}/deposit/deduction":{"post":{"operationId":"RentalController_addDepositDeduction","summary":"Deduct from the deposit","description":"Records a deduction against the deposit for damage, late return, cleaning, or anything else the customer is liable for. Each deduction carries its own reason, so the customer can be shown an itemised account.\n\nDeductions reduce what will be refunded; they do not move money on their own. Refund the remainder explicitly once the total is settled.\n\n#### Signature\n\n```http\nPOST /storefront/rental/{rentalId}/deposit/deduction (rentalId: string, body) -> The rental with the deduction recorded\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Call once per distinct charge — several deductions produce an itemised list rather than one opaque total.\n- Nothing checks the total of deductions against the deposit, so it is possible to record more than was held.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | RENTAL_NOT_FOUND | Rental not found | No rental in the org has that id. | Check the id with `GET /storefront/rental`. |\n| `500` | INTERNAL | The underlying error message, passed through verbatim. | An unexpected failure inside the rental service. | Unlike most of the platform, this surfaces the raw internal message rather than a generic one. Treat the text as a debugging aid, not a stable contract. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /storefront/rental/{rentalId}/checkin`\n- `PUT /storefront/rental/{rentalId}/deposit/refund`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"rentalId","required":true,"in":"path","description":"Rental id.","schema":{"type":"string"},"example":"RNT-4821"}],"responses":{"201":{"description":"The rental with the deduction recorded","content":{"application/json":{"schema":{"type":"object","description":"A rental booking (`sf_rental`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"rentalId":{"type":"string","example":"RNT-4821"},"sku":{"type":"string","example":"CAM-RED-KOMODO"},"quantity":{"type":"number","example":1},"status":{"type":"string","enum":["pending","confirmed","ready","picked_up","delivered","active","overdue","dropped_off","returned","completed","cancelled"],"example":"active"},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"}}},"startDate":{"type":"string","format":"date-time","example":"2026-09-01T09:00:00.000Z"},"endDate":{"type":"string","format":"date-time","example":"2026-09-04T17:00:00.000Z"},"timezone":{"type":"string","description":"Timezone the rental window is expressed in.","example":"America/New_York"},"total":{"type":"number","example":495},"amountPaid":{"type":"number","example":495},"deposit":{"type":"object","description":"Deposit state. Held at checkout, deducted from on damage, refunded at completion.","properties":{"amount":{"type":"number","example":250},"held":{"type":"boolean","example":true},"transactionId":{"type":"string","description":"Reference captured at hold time — this is what a later refund is issued against.","example":"pi_3PabcXYZ"},"chargeId":{"type":"string"},"paymentGateway":{"type":"string","example":"stripe"},"deductions":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}}},"refunded":{"type":"number","example":175}}},"checkOut":{"type":"object","additionalProperties":true,"description":"Condition record from when the item left."},"checkIn":{"type":"object","additionalProperties":true,"description":"Condition record from when the item came back."},"internalNotes":{"type":"string","description":"Operator-only notes."},"customerNotes":{"type":"string","description":"Notes supplied by the customer at booking."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Rental not found — No rental in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Rental not found","path":"/storefront/rental/{rentalId}/deposit/deduction","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"The underlying error message, passed through verbatim. — An unexpected failure inside the rental service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"The underlying error message, passed through verbatim.","path":"/storefront/rental/{rentalId}/deposit/deduction","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Rentals"],"requestBody":{"description":"What is being deducted, and why.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason","amount"],"properties":{"reason":{"type":"string","description":"Shown to the customer as the justification.","example":"Scratched lens housing"},"amount":{"type":"number","example":75}}},"example":{"reason":"Scratched lens housing","amount":75}}}}}},"/storefront/rental/items/{sku}/validate-restrictions":{"post":{"operationId":"RentalController_validateRestrictions","summary":"Validate customer restrictions","description":"Checks whether a customer may rent an item — age limits, geographic restrictions, and anything else the item defines.\n\nA failure is reported as `valid: false` with a list of what failed, **not** as an error status, so the booking form can show every problem at once. Call this before taking payment: the same rules are enforced at creation, where they produce a `403` instead.\n\n#### Signature\n\n```http\nPOST /storefront/rental/items/{sku}/validate-restrictions (sku: string, body) -> Whether the customer qualifies, and what failed if not\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- An unknown SKU comes back as `valid: false` with a `type: \"item\"` failure and a `200`, not a `404`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/rental`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"sku","required":true,"in":"path","description":"Rental item SKU.","schema":{"type":"string"},"example":"CAM-RED-KOMODO"}],"responses":{"201":{"description":"Whether the customer qualifies, and what failed if not","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"failed":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"age"},"message":{"type":"string","example":"Must be 21 or older"}}}}}},"examples":{"ok":{"summary":"Customer qualifies","value":{"valid":true,"failed":[]}},"failed":{"summary":"Too young","value":{"valid":false,"failed":[{"type":"age","message":"Must be 21 or older"}]}},"noItem":{"summary":"Unknown SKU","description":"A missing item is reported through the same shape rather than as a 404.","value":{"valid":false,"failed":[{"type":"item","message":"Item not found"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Rentals"],"requestBody":{"description":"The customer details to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","example":"ada@example.com"},"dateOfBirth":{"type":"string","format":"date","description":"Needed for any age restriction.","example":"1990-05-12"},"country":{"type":"string","example":"US"},"state":{"type":"string","example":"CA"}}},"example":{"email":"ada@example.com","dateOfBirth":"1990-05-12","country":"US","state":"CA"}}}}}},"/storefront/invoices/save":{"post":{"operationId":"InvoiceController_save","summary":"Create or update an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The saved invoice with recalculated totals","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"A single upsert for invoices: send an `sk` to update an existing one, or omit it to create a new one.\n\nTotals are **computed on the server** from the lines — subtotal, tax, discount and total are recalculated on every save, so any figures you send for them are overwritten. Send the lines, not the arithmetic.\n\n**Saving never sends.** No email or SMS goes to the customer from this endpoint, whatever the `status` (including `quote`). A new invoice with no `status` is saved as `draft`. To deliver it, call `POST /storefront/invoices/{id}/send` — that is the only step that contacts the customer.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/save (body) -> The saved invoice with recalculated totals\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- Totals you supply are ignored and recomputed. Read them back from the response rather than assuming yours were kept.\n- Saving never emails or texts the customer. Send with `POST /storefront/invoices/{id}/send`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/send`","requestBody":{"description":"The invoice to save. Include `sk` to update.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sk":{"type":"string","description":"Existing invoice to update. Omit to create."},"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}},"examples":{"create":{"summary":"Create a new invoice","value":{"customerEmail":"ada@example.com","customerName":"Ada Lovelace","currency":"USD","dueDate":"2026-09-30T23:59:59.000Z","items":[{"sku":"DRK-COLA-330","description":"Cola 330ml","quantity":12,"price":12}]}},"update":{"summary":"Update an existing invoice","value":{"sk":"66f1a2b3c4d5e6f708192a3b","items":[{"sku":"DRK-COLA-330","description":"Cola 330ml","quantity":24,"price":12}]}}}}}}}},"/storefront/invoices/bill-visit":{"post":{"operationId":"InvoiceController_billVisit","summary":"Bill a visit from its booking: the patient's estimated portion to the patient, the rest as a claim to the insurer on the patient's record","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Invoices"]}},"/storefront/invoices/visit/{reservationId}":{"get":{"operationId":"InvoiceController_visitBilling","summary":"A visit's invoices and claims, and what its insurer still owes","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"reservationId","required":true,"in":"path","description":"Booking (reservation) SK","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Invoices"]}},"/storefront/invoices/{id}/eob":{"post":{"operationId":"InvoiceController_postEob","summary":"Post the insurer's EOB on a claim: payment, contractual write-off, and what moves to the patient","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Claim (invoice) SK","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Invoices"]}},"/storefront/invoices/{id}":{"get":{"operationId":"InvoiceController_get","summary":"Get an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The invoice","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Fetches one invoice with its lines, totals and recorded payments.\n\n#### Signature\n\n```http\nGET /storefront/invoices/{id} (id: string) -> The invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/invoices/{id}/amount-due`"}},"/storefront/invoices":{"get":{"operationId":"InvoiceController_list","summary":"List invoices","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"]},"example":"overdue"},{"name":"search","required":false,"in":"query","schema":{"type":"string"},"description":"Free-text search across invoice number and customer.","example":"ada@example.com"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of invoices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}},"total":{"type":"integer","example":42}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Lists invoices with optional status filtering, free-text search and paging.\n\n#### Signature\n\n```http\nGET /storefront/invoices (status?: string, search?: string, page?: integer, pageSize?: integer) -> A page of invoices\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/invoices/dashboard/metrics`"}},"/storefront/invoices/{id}/send":{"post":{"operationId":"InvoiceController_send","summary":"Send an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated invoice (status, sentDate, sentTo)","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"400":{"description":"This invoice has no line items, so there is nothing to send — No lines and nothing owed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This invoice has no line items, so there is nothing to send","path":"/storefront/invoices/{id}/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Delivers the invoice to the customer by email, SMS, or both. Recipients default to the contact details on the invoice; pass `emails`, `phones` or `recipients` to override.\n\nAt least one usable recipient must resolve, or the request is refused rather than silently sending nothing. `channels` defaults to `[\"email\"]`; `recipients` is an alias of `emails`.\n\nThis is the **only** endpoint that delivers an invoice or quote — saving never sends. The invoice becomes `sent` (stamped `sentDate`, `sentTo`, `sentChannels`) — except a **quote**, which stays a quote until the customer accepts it (that is when it is booked as a receivable).\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/send (id: string, body) -> The updated invoice (status, sentDate, sentTo)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- Sends every time it is called — there is no once-only guard, so re-sending mails the customer again.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `400` | NOTHING_TO_PAY | This invoice has no line items, so there is nothing to send | No lines and nothing owed. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/reminder`","requestBody":{"description":"Where to send it. All optional when the invoice carries contact details.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"string","enum":["email","sms"]},"description":"Which channels to use. Defaults to `[\"email\"]`.","example":["email"]},"emails":{"type":"array","items":{"type":"string"},"description":"Explicit email recipients.","example":["ada@example.com"]},"phones":{"type":"array","items":{"type":"string"},"description":"Explicit SMS recipients.","example":["+15551234567"]},"recipients":{"type":"array","items":{"type":"string"},"description":"Alias of `emails`."},"test":{"type":"boolean","description":"Send a test: emails only the addresses in `emails` and leaves the invoice unchanged (no status, `sentDate` or ledger posting).","example":false}}},"examples":{"default":{"summary":"Use the invoice contacts","value":{}},"both":{"summary":"Email and SMS explicitly","value":{"channels":["email","sms"],"emails":["ada@example.com"],"phones":["+15551234567"]}}}}}}}},"/storefront/invoices/{id}/create-order":{"post":{"operationId":"InvoiceController_createOrder","summary":"Create an order from an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The created order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/create-order","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Invoice already converted to order <orderNumber> — The invoice already carries an `orderNumber`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Invoice already converted to order <orderNumber>","path":"/storefront/invoices/{id}/create-order","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Order <orderNumber> was created, but the invoice could not be updated to reference it. Do not convert this invoice again — link it to <orderNumber> first. — The order was written successfully but the follow-up write to the invoice failed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Order <orderNumber> was created, but the invoice could not be updated to reference it. Do not convert this invoice again — link it to <orderNumber> first.","path":"/storefront/invoices/{id}/create-order","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Invoices"],"description":"Converts a paid invoice into a paid order, so invoiced sales land in the same fulfilment pipeline as storefront orders.\n\n**Conversion happens once.** Once an invoice carries an `orderNumber`, a second attempt is refused with a `409` naming the existing order.\n\nThere is one failure mode worth planning for: if the order is created but the invoice cannot then be updated to reference it, the call returns a `500` whose message names the order number and tells you not to convert again. **Do not retry that request** — the order exists. Link the invoice to it manually by setting `orderNumber`, then continue.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/create-order (id: string) -> The created order\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- This is the one endpoint here where a `500` carries actionable, non-generic instructions — read the message rather than treating it as a transient failure.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `409` | ALREADY_CONVERTED | Invoice already converted to order <orderNumber> | The invoice already carries an `orderNumber`. | The order exists — read it rather than converting again. |\n| `500` | ORDER_CREATED_LINK_FAILED | Order <orderNumber> was created, but the invoice could not be updated to reference it. Do not convert this invoice again — link it to <orderNumber> first. | The order was written successfully but the follow-up write to the invoice failed. | **Do not retry.** The order exists. Set `orderNumber` on the invoice with `POST /storefront/invoices/save`, then carry on. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /storefront/invoices/save`"}},"/storefront/invoices/{id}/mark-paid":{"post":{"operationId":"InvoiceController_markPaid","summary":"Mark an invoice as paid","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated invoice","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/mark-paid","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Records a payment against the invoice and moves it towards `paid`. Supply `amount` for a partial payment; omitting it settles the invoice in full.\n\nUse this for payments taken outside the platform — a bank transfer or a cheque. Payments made through the public payment page record themselves.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/mark-paid (id: string, body) -> The updated invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- Not idempotent — each call records another payment. Check `GET /storefront/invoices/{id}/amount-due` before retrying.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/refund`","requestBody":{"description":"How it was paid.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","description":"How the money arrived.","example":"bank_transfer"},"ref":{"type":"string","description":"Reference for reconciliation.","example":"BACS-99182"},"amount":{"type":"number","description":"Partial amount. Omit to settle the full balance.","example":50}}},"examples":{"full":{"summary":"Settle in full","value":{"method":"bank_transfer","ref":"BACS-99182"}},"partial":{"summary":"Record a part payment","value":{"method":"bank_transfer","ref":"BACS-99182","amount":50}}}}}}}},"/storefront/invoices/{id}/accept":{"post":{"operationId":"InvoiceController_accept","summary":"Accept a quote on the customer's behalf","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk` or number.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The invoice, now `sent`","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"400":{"description":"This is not an open quote (status: <status>) / This quote has already been accepted — The document is not in `quote` status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This is not an open quote (status: <status>) / This quote has already been accepted","path":"/storefront/invoices/{id}/accept","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/accept","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"For when the customer said yes on the phone. The quote becomes a `sent` invoice, stamped `acceptedAt`/`acceptedBy` (the typed `name`), is booked as a receivable, and the customer is emailed the acceptance and the invoice (`quote-accepted`, `invoice-generated`). After this the payment page takes payment.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/accept (id: string, body) -> The invoice, now `sent`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `400` | QUOTE_NOT_OPEN | This is not an open quote (status: <status>) / This quote has already been accepted | The document is not in `quote` status. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/decline`\n- `POST /storefront/invoices/pay/{id}/accept`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Who accepted — recorded as the signature."},"note":{"type":"string","description":"Up to 2000 characters."}}},"example":{"name":"Ada Lovelace","note":"Confirmed by phone 3pm"}}}}}},"/storefront/invoices/{id}/decline":{"post":{"operationId":"InvoiceController_decline","summary":"Record that the customer declined a quote","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk` or number.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The invoice, now `declined`","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"400":{"description":"This is not an open quote (status: <status>) / This quote has already been accepted — The document is not in `quote` status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This is not an open quote (status: <status>) / This quote has already been accepted","path":"/storefront/invoices/{id}/decline","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/decline","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"The quote becomes `declined` with the reason (up to 2000 characters; \"No reason given\" when empty). The payment page then shows it as declined and takes no payment.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/decline (id: string, body) -> The invoice, now `declined`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `400` | QUOTE_NOT_OPEN | This is not an open quote (status: <status>) / This quote has already been accepted | The document is not in `quote` status. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"name":{"type":"string"}}},"example":{"reason":"Went with another supplier"}}}}}},"/storefront/invoices/{id}/mark-overdue":{"post":{"operationId":"InvoiceController_markOverdue","summary":"Mark an invoice as overdue","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated invoice","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/mark-overdue","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Moves the invoice to `overdue`, bringing it into the overdue filter and dashboard metrics. This is a manual flag — nothing marks invoices overdue automatically on their due date.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/mark-overdue (id: string) -> The updated invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/reminder`"}},"/storefront/invoices/{id}/cancel":{"post":{"operationId":"InvoiceController_cancel","summary":"Cancel an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The cancelled invoice","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Voids an invoice, recording the reason. The record is kept so the number is not reused and the history stays auditable.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/cancel (id: string, body) -> The cancelled invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- Cancelling does not refund anything. Refund a paid invoice first, then cancel — or use `refund` with `cancel: true` to do both.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/reopen`\n- `POST /storefront/invoices/{id}/refund`","requestBody":{"description":"Why it is being cancelled.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Recorded on the invoice.","example":"Raised against the wrong customer"}}},"example":{"reason":"Raised against the wrong customer"}}}}}},"/storefront/invoices/{id}/reopen":{"post":{"operationId":"InvoiceController_reopen","summary":"Reopen an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The reopened invoice","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/reopen","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Returns a cancelled invoice to `draft` so it can be corrected and sent again. The counterpart to cancel.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/reopen (id: string) -> The reopened invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/cancel`"}},"/storefront/invoices/{id}/duplicate":{"post":{"operationId":"InvoiceController_duplicate","summary":"Duplicate an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The new draft invoice","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/duplicate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Copies an invoice into a new `draft` with a fresh number — the fast path for recurring billing, where the same lines go out to the same customer each period.\n\nPayments, status and any order link are **not** copied; the duplicate starts clean.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/duplicate (id: string) -> The new draft invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/save`"}},"/storefront/invoices/{id}/reminder":{"post":{"operationId":"InvoiceController_sendReminder","summary":"Send a payment reminder","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"origin","in":"header","required":false,"description":"Origin used to build the payment link in the reminder. Sent automatically by browsers.","schema":{"type":"string"},"example":"https://admin.example.com"}],"responses":{"201":{"description":"Dispatch result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"No customer email — The invoice has no `customerEmail`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"No customer email","path":"/storefront/invoices/{id}/reminder","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/reminder","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Emails the customer a reminder that the invoice is outstanding, with a link back to the public payment page. Requires an email on the invoice.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/reminder (id: string) -> Dispatch result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `400` | NO_CUSTOMER_EMAIL | No customer email | The invoice has no `customerEmail`. | Reminders are email-only. Add an email to the invoice, or use `send` with an explicit phone for SMS. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/send`"}},"/storefront/invoices/dashboard/metrics":{"get":{"operationId":"InvoiceController_getMetrics","summary":"Get invoice dashboard metrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Aggregate invoice metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Aggregate invoice figures for the org — outstanding, overdue and collected. The read behind an invoicing dashboard.\n\n#### Signature\n\n```http\nGET /storefront/invoices/dashboard/metrics () -> Aggregate invoice metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- Declared before `GET /storefront/invoices/{id}`, so `dashboard` resolves as this route rather than as an invoice id.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/invoices`"}},"/storefront/invoices/{id}/refund":{"post":{"operationId":"InvoiceController_refund","summary":"Refund an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The refund result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Cannot refund invoice with status '<status>'. Invoice must be paid first. — The invoice has not been paid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot refund invoice with status '<status>'. Invoice must be paid first.","path":"/storefront/invoices/{id}/refund","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/refund","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Refund failed: <gateway message> — The payment gateway rejected the refund.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"Refund failed: <gateway message>","path":"/storefront/invoices/{id}/refund","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Storefront · Invoices"],"description":"Refunds a paid invoice in part or in full, optionally cancelling it in the same call.\n\nThe refund goes back through the **original payment gateway** when the invoice was paid that way. An invoice settled by manual payments alone is refunded as a record only, with no gateway involved.\n\nOmitting `amount` refunds the maximum still refundable — total paid minus anything already returned. A requested amount above that ceiling is rejected, and the error reports the paid and refunded figures so you can see how it was derived.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/{id}/refund (id: string, body) -> The refund result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- This is the only endpoint in the storefront that returns a `502` — it distinguishes a gateway refusal from a platform failure.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `400` | NOT_PAID | Cannot refund invoice with status '<status>'. Invoice must be paid first. | The invoice has not been paid. | Cancel an unpaid invoice instead — there is nothing to return. |\n| `502` | GATEWAY_REFUND_FAILED | Refund failed: <gateway message> | The payment gateway rejected the refund. | A `502` means the gateway was reached and refused. Resolve it with the provider; the invoice is unchanged. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/{id}/mark-paid`\n- `POST /storefront/invoices/{id}/cancel`","requestBody":{"description":"How much to refund, and whether to cancel.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Partial amount. Omit to refund everything still refundable.","example":50},"reason":{"type":"string","description":"Recorded with the refund.","example":"Goods returned"},"cancel":{"type":"boolean","default":false,"description":"Also cancel the invoice after refunding.","example":false}}},"examples":{"full":{"summary":"Refund everything","value":{"reason":"Goods returned"}},"partial":{"summary":"Partial refund","value":{"amount":50,"reason":"Two lines returned"}},"fullAndCancel":{"summary":"Refund and cancel","value":{"cancel":true,"reason":"Order voided"}}}}}}}},"/storefront/invoices/{id}/recompute-balance":{"post":{"operationId":"InvoiceController_recomputeBalance","summary":"Recompute balance — status, paid, credited and balance due worked out again from the invoice’s payments and refunds. Moves no money, posts nothing; idempotent.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Invoice SK","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Invoices"]}},"/storefront/invoices/{id}/amount-due":{"get":{"operationId":"InvoiceController_getAmountDue","summary":"Get the amount still due","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk` **or** invoice number — both resolve here.","schema":{"type":"string"},"example":"INV-4821"}],"responses":{"200":{"description":"The outstanding balance derived from transactions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"Computes what is outstanding **from the actual transaction records**, rather than trusting the `amountPaid` field on the invoice.\n\nUse this rather than subtracting `amountPaid` from `total` yourself — it is the figure that reflects the ledger, including payments recorded through the public payment page and any refunds.\n\n#### Signature\n\n```http\nGET /storefront/invoices/{id}/amount-due (id: string) -> The outstanding balance derived from transactions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- This route accepts an invoice number as well as an `sk`, which most of the others do not.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /storefront/invoices/{id}`"}},"/storefront/invoices/{id}/payment-link":{"get":{"operationId":"InvoiceController_getPaymentLink","summary":"Get the customer payment link for an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Invoice `sk` or number.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"{ url, reason? }","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","nullable":true,"example":"https://shop.example.com/pay?invoiceNumber=INV-4821"},"reason":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/{id}/payment-link","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"The URL where the customer pays this invoice: the site's Payment page when the operator runs one, otherwise the hosted page, with `invoiceNumber` on the query string. `url` is null — with a `reason` — when there is no page to send the customer to.\n\n#### Signature\n\n```http\nGET /storefront/invoices/{id}/payment-link (id: string) -> { url, reason? }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/storefront/invoices/pay/{id}":{"get":{"operationId":"InvoiceController_getForPayment","summary":"Get an invoice for the payment page","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Payment options and the amount due","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the page may take payment now."},"reason":{"type":"string","description":"Why not, when `enabled` is false."},"gateways":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Public gateway view: sk, name, configured, data { provider, name, publishableKey / clientId, sandbox, testMode, instructions, … }, and for Stripe a payIntent { id, client_secret, publishableKey }."}},"invoice":{"type":"object","additionalProperties":true,"description":"sk, number, total, currency, status, customerName, customerEmail, products, subTotal, tax, discount, invoiceDate, dueDate, paymentDate, remarks, validUntil, acceptedAt/By, declinedAt, declineReason."},"quote":{"type":"object","nullable":true,"description":"Null when the document was never a quote.","properties":{"open":{"type":"boolean","description":"Still waiting for the customer."},"validUntil":{"type":"string","nullable":true},"expired":{"type":"boolean"},"declined":{"type":"boolean"},"declinedAt":{"type":"string","format":"date-time"},"reason":{"type":"string"},"acceptedAt":{"type":"string","format":"date-time"},"acceptedBy":{"type":"string","description":"The typed name."},"note":{"type":"string","nullable":true}}}}}}}},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/pay/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"The **public** read behind a customer payment link. Returns what the payment page needs — the amount due and the gateways available — without requiring the customer to sign in.\n\nThe invoice `sk` is the only credential, so treat payment links as secrets and do not make ids guessable.\n\n#### Signature\n\n```http\nGET /storefront/invoices/pay/{id} (id: string) -> Payment options and the amount due\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated. Anyone holding the link can read the invoice.\n- `enabled` is false — with no gateways — while the document is an open quote (`reason: \"This is a quote — accept it first\"`), after it was declined, or when online payment is switched off on the invoice. `quote` says where a quote stands.\n- Each gateway carries only its public checkout fields (provider, name, publishable key / client id, sandbox or test mode, instructions) and `configured`; credentials never leave the server.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /storefront/invoices/pay/{id}`\n- `POST /storefront/invoices/pay/{id}/accept`\n- `POST /storefront/invoices/pay/{id}/decline`"},"post":{"operationId":"InvoiceController_recordPayment","summary":"Record a payment from the payment page","description":"The **public** write that records a customer payment made through the payment page, after the gateway has confirmed it.\n\nIt records what it is told: the caller supplies the gateway, reference and amount. Since the route is unauthenticated, verify the payment with the provider — `GET /storefront/verify-payment/...` — before trusting a client-reported amount.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/pay/{id} (id: string, body) -> The updated invoice\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated and unverified — the amount is taken on trust. Confirm with the provider before relying on it.\n- Not idempotent: a retry records a second payment against the invoice.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /storefront/invoices/pay/{id}`\n- `GET /storefront/verify-payment/{provider}/{configId}/{paymentId}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated invoice","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/pay/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"requestBody":{"description":"The payment the gateway confirmed.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["gateway","ref","amount"],"properties":{"gateway":{"type":"string","description":"Which gateway took the payment.","example":"stripe"},"ref":{"type":"string","description":"Gateway reference.","example":"pi_3PabcXYZ"},"amount":{"type":"number","description":"Amount paid.","example":144},"method":{"type":"string","description":"Payment method used.","example":"card"}}},"example":{"gateway":"stripe","ref":"pi_3PabcXYZ","amount":144,"method":"card"}}}}}},"/storefront/invoices/pay/{id}/accept":{"post":{"operationId":"InvoiceController_acceptQuote","summary":"Accept a quote from the payment page","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk` or number.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The invoice, now `sent`","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"400":{"description":"This is not an open quote (status: <status>) / This quote has already been accepted — The document is not in `quote` status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This is not an open quote (status: <status>) / This quote has already been accepted","path":"/storefront/invoices/pay/{id}/accept","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/pay/{id}/accept","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"The **public** accept step on the payment page: the customer types their name to agree. Same effect as the staff accept — the quote becomes a payable `sent` invoice, is booked, and the acceptance and invoice are emailed.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/pay/{id}/accept (id: string, body) -> The invoice, now `sent`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated: anyone with the link can accept. The id is the only credential.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `400` | QUOTE_NOT_OPEN | This is not an open quote (status: <status>) / This quote has already been accepted | The document is not in `quote` status. | — |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"note":{"type":"string"}}},"example":{"name":"Ada Lovelace"}}}}}},"/storefront/invoices/pay/{id}/decline":{"post":{"operationId":"InvoiceController_declineQuote","summary":"Decline a quote from the payment page","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Invoice `sk` or number.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The invoice, now `declined`","content":{"application/json":{"schema":{"type":"object","description":"An invoice (`sf_invoice`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human invoice number.","example":"INV-4821"},"status":{"type":"string","enum":["new","draft","quote","declined","sent","paid","paid-partial","overpaid","overdue","refunded","cancelled"],"example":"sent"},"customerEmail":{"type":"string","description":"Required before the invoice can be sent or reminded.","example":"ada@example.com"},"customerPhone":{"type":"string","example":"+15551234567"},"customerName":{"type":"string","example":"Ada Lovelace"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"DRK-COLA-330"},"description":{"type":"string","example":"Cola 330ml"},"quantity":{"type":"number","example":12},"price":{"type":"number","description":"Unit price.","example":12},"amount":{"type":"number","description":"Line total. Recalculated on save.","example":144},"taxRate":{"type":"number","example":0}}}},"subtotal":{"type":"number","description":"Computed on save from the lines.","example":144},"tax":{"type":"number","example":0},"discount":{"type":"number","example":0},"total":{"type":"number","description":"Computed on save.","example":144},"amountPaid":{"type":"number","example":0},"currency":{"type":"string","example":"USD"},"dueDate":{"type":"string","format":"date-time","example":"2026-09-30T23:59:59.000Z"},"payments":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Recorded tenders."},"orderNumber":{"type":"string","description":"Set once the invoice has been converted to an order. Its presence blocks a second conversion.","example":"A7K2M9QX4"}}}}}}}},"400":{"description":"This is not an open quote (status: <status>) / This quote has already been accepted — The document is not in `quote` status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This is not an open quote (status: <status>) / This quote has already been accepted","path":"/storefront/invoices/pay/{id}/decline","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Invoice not found — No invoice in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invoice not found","path":"/storefront/invoices/pay/{id}/decline","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Storefront · Invoices"],"description":"The **public** decline step: the quote becomes `declined` with the customer's reason.\n\n#### Signature\n\n```http\nPOST /storefront/invoices/pay/{id}/decline (id: string, body) -> The invoice, now `declined`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated: anyone with the link can decline.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVOICE_NOT_FOUND | Invoice not found | No invoice in the org has that id. | Check the id with `GET /storefront/invoices`. Note this service does return a real `404`, unlike the discount and gift card services. |\n| `400` | QUOTE_NOT_OPEN | This is not an open quote (status: <status>) / This quote has already been accepted | The document is not in `quote` status. | — |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"name":{"type":"string"}}}}}}}},"/sales-channel/channels":{"get":{"operationId":"SalesChannelController_getAvailableChannels","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Channels keyed by id","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List supported channels","description":"Every channel the platform can sell through, with the capabilities each one supports — order sync, pricing sync, inventory sync. Static platform capability, not org configuration; nothing here means the org can actually sell on it.\n\n#### Signature\n\n```http\nGET /sales-channel/channels () -> Channels keyed by id\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/channels/configured`","tags":["Sales channels"]}},"/sales-channel/channels/configured":{"get":{"operationId":"SalesChannelController_getConfiguredChannels","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Channels with an `enabled` flag","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","example":"amazon"},"config":{"type":"object","additionalProperties":true},"enabled":{"type":"boolean","example":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List configured channels","description":"The same channel list, each flagged with whether **this org** has working integration credentials. This is the one to read before offering a channel in a UI.\n\n#### Signature\n\n```http\nGET /sales-channel/channels/configured () -> Channels with an `enabled` flag\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/channels`","tags":["Sales channels"]}},"/sales-channel/channels/status":{"get":{"operationId":"SalesChannelController_getAllChannelStatuses","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Per-channel status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get all channel statuses","description":"Live connection status for every configured channel — whether credentials still authenticate and when each last synced. Use it for a health board; a channel can be enabled but broken.\n\n#### Signature\n\n```http\nGET /sales-channel/channels/status () -> Per-channel status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/channels/{channelId}/status`","tags":["Sales channels"]}},"/sales-channel/channels/{channelId}/categories":{"get":{"operationId":"SalesChannelController_listingCategories","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"},{"name":"q","required":false,"in":"query","schema":{"type":"string"},"description":"Words to search by.","example":"ceramic mug"}],"responses":{"200":{"description":"`{ categories: [{ value, label }] }`, label = the full path","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/channels/{channelId}/categories","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search a marketplace's categories","description":"Categories for a product's marketplace details, searched by the words typed: eBay's category tree for the seller's eBay site. The channel must be open, the platform's app set up and the org connected; otherwise 400 with the sentence why.\n\n#### Signature\n\n```http\nGET /sales-channel/channels/{channelId}/categories (channelId: string, q?: string) -> `{ categories: [{ value, label }] }`, label = the full path\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/channels/{channelId}/listing-details`","tags":["Sales channels"]}},"/sales-channel/channels/{channelId}/listing-details":{"post":{"operationId":"SalesChannelController_listingDetails","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The details definition with values","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/channels/{channelId}/listing-details","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"What a marketplace asks of a product","description":"The marketplace's per-product details for the category picked (eBay: condition and the category's item specifics), each with the value the product gives now (the seller's entry, else the product's own same-named field, attribute or variation option) and `problem`: the sentence of what is still missing, or null when it can be listed. A channel that can't be used yet answers with `comingSoon`/`available`/`connected` and `message` instead.\n\n#### Signature\n\n```http\nPOST /sales-channel/channels/{channelId}/listing-details (channelId: string, body) -> The details definition with values\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/channels/{channelId}/categories`","tags":["Sales channels"],"requestBody":{"description":"The product data as the form holds it, and optionally the category being picked.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"categoryId":"20625","product":{"name":"Stoneware mug","brand":"Clayworks","ebay":{"condition":"NEW"}}}}}}}},"/sales-channel/channels/{channelId}/status":{"get":{"operationId":"SalesChannelController_getChannelStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"200":{"description":"The channel status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/channels/{channelId}/status","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get one channel's status","description":"Connection status and last-sync detail for a single channel.\n\n#### Signature\n\n```http\nGET /sales-channel/channels/{channelId}/status (channelId: string) -> The channel status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/channels/status`","tags":["Sales channels"]}},"/sales-channel/channels/{channelId}/enable":{"post":{"operationId":"SalesChannelController_enableChannel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The enable result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/channels/{channelId}/enable","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Enable a channel","description":"Stores the org's credentials for a channel and turns it on. The body shape is per-channel — a marketplace seller id and API keys, an OAuth token — so read `GET /sales-channel/channels` for what the channel expects.\n\nEnabling does not push anything: listings, inventory and prices still have to be synced explicitly.\n\n#### Signature\n\n```http\nPOST /sales-channel/channels/{channelId}/enable (channelId: string, body) -> The enable result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Stores credentials — do not log the request body.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/channels/{channelId}/disable`","tags":["Sales channels"],"requestBody":{"description":"Channel credentials and options.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sellerId":"A1B2C3D4","apiKey":"<key>","marketplace":"US"}}}}}},"/sales-channel/channels/{channelId}/oauth/start":{"post":{"operationId":"SalesChannelController_startOAuth","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"origin","required":true,"in":"header","schema":{"type":"string"}},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/sales-channel/channels/{channelId}/disable":{"post":{"operationId":"SalesChannelController_disableChannel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The disable result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/channels/{channelId}/disable","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Disable a channel","description":"Turns a channel off so nothing further syncs to it. Listings already live on the marketplace are **not** taken down — they stop receiving inventory and price updates, which leaves them selling at the last synced values. End listings on the channel itself if that is what you want.\n\n#### Signature\n\n```http\nPOST /sales-channel/channels/{channelId}/disable (channelId: string) -> The disable result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Live listings stay up and stop being updated.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/channels/{channelId}/enable`","tags":["Sales channels"]}},"/sales-channel/sync/history":{"get":{"operationId":"SalesChannelController_getSyncHistory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"},{"name":"operation","required":false,"in":"query","schema":{"type":"string"},"description":"Operation name, e.g. `inventory-sync`.","example":"inventory-sync"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"Sync history entries, newest first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get sync history","description":"The log of sync operations across channels — what ran, when, and whether it succeeded. The first place to look when a channel's stock or prices are stale.\n\n#### Signature\n\n```http\nGET /sales-channel/sync/history (channelId?: string, operation?: string, limit?: integer) -> Sync history entries, newest first\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/inventory/sync`","tags":["Sales channels"]}},"/sales-channel/channels/{channelId}/execute":{"post":{"operationId":"SalesChannelController_executeChannelOperation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The channel's response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/channels/{channelId}/execute","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Execute a channel operation","description":"Escape hatch: runs a named operation against one channel, passing `data` through to the channel adapter. Which operations exist depends on the channel — this is the route to use when a capability has no dedicated endpoint.\n\nBecause it is a passthrough, the payload is not validated here; the channel decides what is acceptable.\n\n#### Signature\n\n```http\nPOST /sales-channel/channels/{channelId}/execute (channelId: string, body) -> The channel's response\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Unvalidated passthrough — the channel accepts or rejects the payload.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/channels/bulk-execute`","tags":["Sales channels"],"requestBody":{"description":"The operation and its payload.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["operation","data"],"properties":{"operation":{"type":"string","example":"update-listing"},"data":{"type":"object","additionalProperties":true}}},"example":{"operation":"update-listing","data":{"sku":"COLA-330","title":"Cola 330ml"}}}}}}},"/sales-channel/channels/bulk-execute":{"post":{"operationId":"SalesChannelController_executeBulkOperation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Per-channel results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Execute an operation on many channels","description":"Runs the same operation against several channels in one call. Each channel is attempted independently, so a partial failure is normal — read the per-channel results rather than assuming a 2xx means everything succeeded.\n\n#### Signature\n\n```http\nPOST /sales-channel/channels/bulk-execute (body) -> Per-channel results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Partial success is expected — inspect each channel's result.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/channels/{channelId}/execute`","tags":["Sales channels"],"requestBody":{"description":"Channels, operation and payload.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["channelIds","operation","data"],"properties":{"channelIds":{"type":"array","items":{"type":"string"},"example":["amazon","ebay"]},"operation":{"type":"string","example":"update-listing"},"data":{"type":"object","additionalProperties":true}}},"example":{"channelIds":["amazon","ebay"],"operation":"update-listing","data":{"sku":"COLA-330"}}}}}}},"/sales-channel/inventory/alerts":{"get":{"operationId":"InventorySyncController_listAlerts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"includeAcknowledged","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/sales-channel/inventory/alerts/{alertId}/acknowledge":{"put":{"operationId":"InventorySyncController_acknowledgeAlert","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"alertId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/sales-channel/inventory/{sku}":{"get":{"operationId":"InventorySyncController_getMasterInventory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"COLA-330"}],"responses":{"200":{"description":"Master inventory","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get master inventory for a SKU","description":"The authoritative stock figure for a SKU — the single number every channel is synced from.\n\n#### Signature\n\n```http\nGET /sales-channel/inventory/{sku} (sku: string) -> Master inventory\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/inventory/{sku}/channels`","tags":["Sales channels"]},"put":{"operationId":"InventorySyncController_updateMasterInventory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"COLA-330"}],"responses":{"200":{"description":"The updated inventory","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Product <sku> not found — No product carries that SKU. Returned as 400, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Product <sku> not found","path":"/sales-channel/inventory/{sku}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update master inventory","description":"Sets the master stock level for a SKU. `syncToChannels` decides whether the new figure is pushed to the marketplaces immediately — leave it off and the channels keep selling against the old number until a sync runs.\n\n#### Signature\n\n```http\nPUT /sales-channel/inventory/{sku} (sku: string, body) -> The updated inventory\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Absolute set, not a delta.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PRODUCT_NOT_FOUND | Product <sku> not found | No product carries that SKU. Returned as 400, not 404. | Check the SKU against the catalogue. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /sales-channel/inventory/bulk/update`","tags":["Sales channels"],"requestBody":{"description":"The new quantity.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity"],"properties":{"quantity":{"type":"number","example":120},"syncToChannels":{"type":"boolean","description":"Push to channels immediately.","example":true},"reason":{"type":"string","example":"Stock count"}}},"example":{"quantity":120,"syncToChannels":true,"reason":"Stock count"}}}}}},"/sales-channel/inventory/bulk/update":{"put":{"operationId":"InventorySyncController_bulkUpdateInventory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Per-SKU results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Bulk-update master inventory","description":"Sets stock for many SKUs at once — the endpoint a stock count or a warehouse feed uses. Each quantity is absolute, not a delta.\n\n#### Signature\n\n```http\nPUT /sales-channel/inventory/bulk/update (body) -> Per-SKU results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Quantities are absolute.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /sales-channel/inventory/{sku}`","tags":["Sales channels"],"requestBody":{"description":"The updates.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["updates"],"properties":{"updates":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"COLA-330"},"quantity":{"type":"number","example":120}}}},"syncToChannels":{"type":"boolean","example":true}}},"example":{"updates":[{"sku":"COLA-330","quantity":120},{"sku":"COLA-500","quantity":40}],"syncToChannels":true}}}}}},"/sales-channel/inventory/reserve":{"post":{"operationId":"InventorySyncController_reserveInventory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The reservation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Product <sku> not found — No product carries that SKU. Returned as 400, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Product <sku> not found","path":"/sales-channel/inventory/reserve","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Reserve inventory for an order","description":"Holds stock for an order so it cannot be sold twice while the order is being paid for or fulfilled. Reservations are the mechanism that prevents oversells across channels.\n\nEvery reservation must end in a `commit` or a `release` — one left open holds stock indefinitely.\n\n#### Signature\n\n```http\nPOST /sales-channel/inventory/reserve (body) -> The reservation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Always follow with commit or release.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PRODUCT_NOT_FOUND | Product <sku> not found | No product carries that SKU. Returned as 400, not 404. | Check the SKU against the catalogue. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/inventory/reservation/{reservationId}/commit`","tags":["Sales channels"],"requestBody":{"description":"What to reserve and for which order.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["items","orderId"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"COLA-330"},"quantity":{"type":"number","example":2}}}},"orderId":{"type":"string","example":"ORD-4821"}}},"example":{"items":[{"sku":"COLA-330","quantity":2}],"orderId":"ORD-4821"}}}}}},"/sales-channel/inventory/reservation/{reservationId}/release":{"post":{"operationId":"InventorySyncController_releaseReservation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"reservationId","required":true,"in":"path","schema":{"type":"string"},"description":"Reservation id.","example":"RSV-4821"}],"responses":{"201":{"description":"The release result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Reservation <id> not found — No reservation has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Reservation <id> not found","path":"/sales-channel/inventory/reservation/{reservationId}/release","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Release a reservation","description":"Returns held stock to available — the order was cancelled or the payment failed. Run this on abandoned checkouts; unreleased holds slowly starve the sellable quantity.\n\n#### Signature\n\n```http\nPOST /sales-channel/inventory/reservation/{reservationId}/release (reservationId: string) -> The release result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RESERVATION_NOT_FOUND | Reservation <id> not found | No reservation has that id. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/inventory/reserve`","tags":["Sales channels"]}},"/sales-channel/inventory/reservation/{reservationId}/commit":{"post":{"operationId":"InventorySyncController_commitReservation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"reservationId","required":true,"in":"path","schema":{"type":"string"},"description":"Reservation id.","example":"RSV-4821"}],"responses":{"201":{"description":"The commit result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Reservation <id> not found — No reservation has that id. Returned as 400, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Reservation <id> not found","path":"/sales-channel/inventory/reservation/{reservationId}/commit","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Commit a reservation","description":"Converts a hold into an actual stock decrement — the order shipped or was paid. Irreversible through this API: undoing it means putting the stock back with an inventory update.\n\n#### Signature\n\n```http\nPOST /sales-channel/inventory/reservation/{reservationId}/commit (reservationId: string) -> The commit result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Permanently decrements stock.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | RESERVATION_NOT_FOUND | Reservation <id> not found | No reservation has that id. Returned as 400, not 404. | Check the id from the reserve response. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/inventory/reservation/{reservationId}/release`","tags":["Sales channels"]}},"/sales-channel/inventory/sync/{channelId}":{"post":{"operationId":"InventorySyncController_syncToChannel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The sync result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/inventory/sync/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Push inventory to one channel","description":"Pushes the given SKUs' stock levels to a single channel.\n\n#### Signature\n\n```http\nPOST /sales-channel/inventory/sync/{channelId} (channelId: string, body) -> The sync result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/inventory/sync`","tags":["Sales channels"],"requestBody":{"description":"The items to push.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}},"example":{"items":[{"sku":"COLA-330","quantity":120}]}}}}}},"/sales-channel/inventory/sync":{"post":{"operationId":"InventorySyncController_syncToAllChannels","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Per-channel results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Push inventory to all channels","description":"Pushes the given SKUs' stock to every configured channel. Channels are attempted independently — check the per-channel results, since a single failure leaves that marketplace stale and able to oversell.\n\n#### Signature\n\n```http\nPOST /sales-channel/inventory/sync (body) -> Per-channel results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Partial failure leaves that channel stale.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/sync/history`","tags":["Sales channels"],"requestBody":{"description":"The items to push.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"number"}}}}}},"example":{"items":[{"sku":"COLA-330","quantity":120}]}}}}}},"/sales-channel/inventory/pull/{channelId}":{"post":{"operationId":"InventorySyncController_pullFromChannel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"What the channel reports","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/inventory/pull/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Pull inventory from a channel","description":"Reads stock levels back from a channel — for reconciling after a marketplace-side change, or for a first import. Pulling does not overwrite master; compare before deciding which side is right.\n\n#### Signature\n\n```http\nPOST /sales-channel/inventory/pull/{channelId} (channelId: string) -> What the channel reports\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/inventory/{sku}/channels`","tags":["Sales channels"]}},"/sales-channel/inventory/alerts/low-stock":{"get":{"operationId":"InventorySyncController_getLowStockItems","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Low-stock items","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List low-stock items","description":"SKUs at or below their reorder threshold — what to restock, or to pull from channels before it oversells.\n\n#### Signature\n\n```http\nGET /sales-channel/inventory/alerts/low-stock () -> Low-stock items\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /sales-channel/inventory/bulk/update`","tags":["Sales channels"]}},"/sales-channel/inventory/{sku}/channels":{"get":{"operationId":"InventorySyncController_getInventoryAcrossChannels","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"COLA-330"}],"responses":{"200":{"description":"Per-channel quantities","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a SKU's stock across channels","description":"What each channel currently believes the stock is, next to the master figure. Divergence here is what causes oversells — a channel still showing stock that master no longer has.\n\n#### Signature\n\n```http\nGET /sales-channel/inventory/{sku}/channels (sku: string) -> Per-channel quantities\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/inventory/sync`","tags":["Sales channels"]}},"/sales-channel/mappings/categories":{"get":{"operationId":"ChannelMappingController_getAllCategoryMappings","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Category mappings","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List category mappings","description":"How the org's own categories translate to each channel's taxonomy. Marketplaces reject listings in the wrong category, so these mappings are what make a listing publishable.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/categories () -> Category mappings\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/categories`","tags":["Sales channels"]},"post":{"operationId":"ChannelMappingController_saveCategoryMapping","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The saved mapping","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Save a category mapping","description":"Creates or replaces a category mapping. Saving by source category, so re-posting the same source category overwrites the previous mapping rather than adding a second.\n\n#### Signature\n\n```http\nPOST /sales-channel/mappings/categories (body) -> The saved mapping\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /sales-channel/mappings/categories/{mappingId}`","tags":["Sales channels"],"requestBody":{"description":"The mapping.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sourceCategory":"beverages","channelId":"amazon","channelCategory":"16310101"}}}}}},"/sales-channel/mappings/categories/{sourceCategory}":{"get":{"operationId":"ChannelMappingController_getCategoryMapping","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sourceCategory","required":true,"in":"path","schema":{"type":"string"},"description":"The org's own category.","example":"beverages"}],"responses":{"200":{"description":"The mapping","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a category mapping","description":"The mapping for one source category across all channels.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/categories/{sourceCategory} (sourceCategory: string) -> The mapping\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/mappings/categories/{sourceCategory}/channel/{channelId}`","tags":["Sales channels"]}},"/sales-channel/mappings/categories/{mappingId}":{"delete":{"operationId":"ChannelMappingController_deleteCategoryMapping","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"mappingId","required":true,"in":"path","schema":{"type":"string"},"description":"Mapping id.","example":"MAP-4821"}],"responses":{"200":{"description":"The delete result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a category mapping","description":"Removes a category mapping. Products in that category can no longer be transformed for the affected channel until a new mapping exists.\n\n#### Signature\n\n```http\nDELETE /sales-channel/mappings/categories/{mappingId} (mappingId: string) -> The delete result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/categories`","tags":["Sales channels"]}},"/sales-channel/mappings/categories/{sourceCategory}/channel/{channelId}":{"get":{"operationId":"ChannelMappingController_getChannelCategory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sourceCategory","required":true,"in":"path","schema":{"type":"string"},"description":"The org's own category.","example":"beverages"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"200":{"description":"The channel category","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Resolve a category for a channel","description":"Resolves one source category to the specific category id that channel expects — the single lookup a listing builder needs.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/categories/{sourceCategory}/channel/{channelId} (sourceCategory: string, channelId: string) -> The channel category\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/transform/{channelId}`","tags":["Sales channels"]}},"/sales-channel/mappings/attributes":{"get":{"operationId":"ChannelMappingController_getAllAttributeMappings","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Attribute mappings","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List attribute mappings","description":"How the org's product fields map onto each channel's attribute names — `colour` to `color_name`, and so on.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/attributes () -> Attribute mappings\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/attributes`","tags":["Sales channels"]},"post":{"operationId":"ChannelMappingController_saveAttributeMapping","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The saved mapping","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Save an attribute mapping","description":"Creates or replaces an attribute mapping. A mapping can be marked required — a product missing that source field then fails validation rather than publishing an incomplete listing.\n\n#### Signature\n\n```http\nPOST /sales-channel/mappings/attributes (body) -> The saved mapping\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/validate/{channelId}`","tags":["Sales channels"],"requestBody":{"description":"The mapping.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sourceField":"colour","channelId":"amazon","targetField":"color_name","required":true}}}}}},"/sales-channel/mappings/attributes/{sourceAttribute}":{"get":{"operationId":"ChannelMappingController_getAttributeMapping","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sourceAttribute","required":true,"in":"path","schema":{"type":"string"},"description":"The org's own field name.","example":"colour"}],"responses":{"200":{"description":"The mapping","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an attribute mapping","description":"The mapping for one source attribute.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/attributes/{sourceAttribute} (sourceAttribute: string) -> The mapping\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/mappings/attributes`","tags":["Sales channels"]}},"/sales-channel/mappings/attributes/{mappingId}":{"delete":{"operationId":"ChannelMappingController_deleteAttributeMapping","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"mappingId","required":true,"in":"path","schema":{"type":"string"},"description":"Mapping id.","example":"MAP-77"}],"responses":{"200":{"description":"The delete result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete an attribute mapping","description":"Removes an attribute mapping. Transformed listings will no longer carry that field.\n\n#### Signature\n\n```http\nDELETE /sales-channel/mappings/attributes/{mappingId} (mappingId: string) -> The delete result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/attributes`","tags":["Sales channels"]}},"/sales-channel/mappings/templates":{"get":{"operationId":"ChannelMappingController_getChannelTemplates","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"}],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List channel templates","description":"Listing templates — reusable sets of defaults and field rules applied when building a listing for a channel.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/templates (channelId?: string) -> Templates\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/apply-template/{templateId}`","tags":["Sales channels"]},"post":{"operationId":"ChannelMappingController_saveChannelTemplate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The saved template","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Save a channel template","description":"Creates or replaces a listing template.\n\n#### Signature\n\n```http\nPOST /sales-channel/mappings/templates (body) -> The saved template\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/mappings/templates`","tags":["Sales channels"],"requestBody":{"description":"The template.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Beverages — Amazon","channelId":"amazon","defaults":{"brand":"Acme"}}}}}}},"/sales-channel/mappings/templates/{templateId}":{"get":{"operationId":"ChannelMappingController_getChannelTemplate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"templateId","required":true,"in":"path","schema":{"type":"string"},"description":"Template id.","example":"TPL-12"}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Template <templateId> not found — No template has that id. Returned as 400, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Template <templateId> not found","path":"/sales-channel/mappings/templates/{templateId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a channel template","description":"Fetches one listing template.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/templates/{templateId} (templateId: string) -> The template\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | TEMPLATE_NOT_FOUND | Template <templateId> not found | No template has that id. Returned as 400, not 404. | List templates first. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/templates`","tags":["Sales channels"]},"delete":{"operationId":"ChannelMappingController_deleteChannelTemplate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"templateId","required":true,"in":"path","schema":{"type":"string"},"description":"Template id.","example":"TPL-12"}],"responses":{"200":{"description":"The delete result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a channel template","description":"Removes a listing template. Listings already published are unaffected; future builds lose its defaults.\n\n#### Signature\n\n```http\nDELETE /sales-channel/mappings/templates/{templateId} (templateId: string) -> The delete result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/templates`","tags":["Sales channels"]}},"/sales-channel/mappings/transform/{channelId}":{"post":{"operationId":"ChannelMappingController_transformProduct","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The channel-shaped product","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/mappings/transform/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Transform a product for a channel","description":"Runs a product through the category and attribute mappings and returns the channel-shaped payload — exactly what would be sent to the marketplace. Read-only preview: nothing is published.\n\n#### Signature\n\n```http\nPOST /sales-channel/mappings/transform/{channelId} (channelId: string, body) -> The channel-shaped product\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/validate/{channelId}`","tags":["Sales channels"],"requestBody":{"description":"The product to transform.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sku":"COLA-330","title":"Cola 330ml","category":"beverages","colour":"red"}}}}}},"/sales-channel/mappings/apply-template/{templateId}":{"post":{"operationId":"ChannelMappingController_applyTemplate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"templateId","required":true,"in":"path","schema":{"type":"string"},"description":"Template id.","example":"TPL-12"}],"responses":{"201":{"description":"The product with template defaults applied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Apply a template to a product","description":"Merges a template's defaults into a product and returns the result. A preview — the product itself is not modified.\n\n#### Signature\n\n```http\nPOST /sales-channel/mappings/apply-template/{templateId} (templateId: string, body) -> The product with template defaults applied\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/transform/{channelId}`","tags":["Sales channels"],"requestBody":{"description":"The product.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sku":"COLA-330","title":"Cola 330ml"}}}}}},"/sales-channel/mappings/validate/{channelId}":{"post":{"operationId":"ChannelMappingController_validateProduct","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"Validation result with any problems found","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/mappings/validate/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Validate a product for a channel","description":"Checks one product against a channel's requirements and reports what would be rejected — the cheap check to run before publishing, since marketplace rejections are slow and opaque.\n\n#### Signature\n\n```http\nPOST /sales-channel/mappings/validate/{channelId} (channelId: string, body) -> Validation result with any problems found\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/mappings/validate/{channelId}/bulk`","tags":["Sales channels"],"requestBody":{"description":"The product to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sku":"COLA-330","title":"Cola 330ml","category":"beverages"}}}}}},"/sales-channel/mappings/validate/{channelId}/bulk":{"get":{"operationId":"ChannelMappingController_bulkValidate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"200":{"description":"Per-product validation results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/mappings/validate/{channelId}/bulk","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Validate the whole catalogue for a channel","description":"Validates every product against one channel and reports the failures — the pre-flight before a first publish to a new marketplace.\n\nNote this is a **GET** that scans the full catalogue, so it can be slow on a large one and is not cheap to poll.\n\n#### Signature\n\n```http\nGET /sales-channel/mappings/validate/{channelId}/bulk (channelId: string) -> Per-product validation results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Scans the entire catalogue — expect a long response time.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/mappings/validate/{channelId}`","tags":["Sales channels"]}},"/sales-channel/orders/sync/{channelId}":{"post":{"operationId":"OrderAggregationController_syncChannel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The sync result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/orders/sync/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Pull orders from a channel","description":"Fetches orders from one marketplace into the aggregated order list. Without a date range the channel's own default window applies, so pass `fromDate` when back-filling.\n\n#### Signature\n\n```http\nPOST /sales-channel/orders/sync/{channelId} (channelId: string, body) -> The sync result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/orders/sync`","tags":["Sales channels"],"requestBody":{"description":"Optional window and status filter.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"fromDate":{"type":"string","example":"2026-08-01"},"toDate":{"type":"string","example":"2026-08-31"},"status":{"type":"string","example":"unshipped"}}},"example":{"fromDate":"2026-08-01"}}}}}},"/sales-channel/orders/sync":{"post":{"operationId":"OrderAggregationController_syncAll","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Per-channel results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Pull orders from all channels","description":"Runs the order pull across every configured channel. Channels that do not support order sync are skipped rather than failing the call — read the per-channel results.\n\n#### Signature\n\n```http\nPOST /sales-channel/orders/sync (body) -> Per-channel results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/orders`","tags":["Sales channels"],"requestBody":{"description":"Optional window.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"fromDate":{"type":"string","example":"2026-08-01"},"toDate":{"type":"string","example":"2026-08-31"}}},"example":{"fromDate":"2026-08-01"}}}}}},"/sales-channel/orders":{"get":{"operationId":"OrderAggregationController_getOrders","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"example":"unshipped"},{"name":"fromDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-01"},{"name":"toDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-31"},{"name":"page","required":false,"in":"query","schema":{"type":"integer"},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"Aggregated orders","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List aggregated orders","description":"Orders from every channel in one list with a common shape — the single queue an operations team works from instead of logging into each marketplace.\n\n#### Signature\n\n```http\nGET /sales-channel/orders (channel?: string, status?: string, fromDate?: string, toDate?: string, page?: integer, pageSize?: integer) -> Aggregated orders\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/orders/{orderId}`","tags":["Sales channels"]}},"/sales-channel/orders/{orderId}":{"get":{"operationId":"OrderAggregationController_getOrder","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderId","required":true,"in":"path","schema":{"type":"string"},"description":"Aggregated order id.","example":"ORD-4821"}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Order <orderId> not found — No aggregated order has that id. Returned as 400, not 404.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Order <orderId> not found","path":"/sales-channel/orders/{orderId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an aggregated order","description":"One order with its items, buyer detail and channel of origin.\n\n#### Signature\n\n```http\nGET /sales-channel/orders/{orderId} (orderId: string) -> The order\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORDER_NOT_FOUND | Order <orderId> not found | No aggregated order has that id. Returned as 400, not 404. | Check the id from the order list. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /sales-channel/orders/{orderId}/status`","tags":["Sales channels"]}},"/sales-channel/orders/{orderId}/status":{"put":{"operationId":"OrderAggregationController_updateStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orderId","required":true,"in":"path","schema":{"type":"string"},"description":"Aggregated order id.","example":"ORD-4821"}],"responses":{"200":{"description":"The updated order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Order <orderId> not found — No aggregated order has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Order <orderId> not found","path":"/sales-channel/orders/{orderId}/status","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update an order's status","description":"Moves an aggregated order to a new status, optionally attaching a tracking number. Marking an order shipped with tracking is what pushes fulfilment back to the marketplace — the buyer sees it, so the tracking number must be real.\n\n#### Signature\n\n```http\nPUT /sales-channel/orders/{orderId}/status (orderId: string, body) -> The updated order\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Shipment status is visible to the marketplace buyer.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORDER_NOT_FOUND | Order <orderId> not found | No aggregated order has that id. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/orders`","tags":["Sales channels"],"requestBody":{"description":"The new status.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","example":"shipped"},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"}}},"example":{"status":"shipped","trackingNumber":"1Z999AA10123456784"}}}}}},"/sales-channel/orders/stats/summary":{"get":{"operationId":"OrderAggregationController_getStats","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"fromDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-01"},{"name":"toDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-31"}],"responses":{"200":{"description":"Order statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get order statistics","description":"Order counts and value by channel over a date range.\n\n#### Signature\n\n```http\nGET /sales-channel/orders/stats/summary (fromDate?: string, toDate?: string) -> Order statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/summary`","tags":["Sales channels"]}},"/sales-channel/pricing/rules":{"get":{"operationId":"PricingController_getPricingRules","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"}],"responses":{"200":{"description":"Pricing rules","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List pricing rules","description":"Rules that derive a channel price from the base price — marketplace fee uplifts, per-channel margins, floors. Optionally filtered to one channel.\n\n#### Signature\n\n```http\nGET /sales-channel/pricing/rules (channel?: string) -> Pricing rules\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/pricing/rules`","tags":["Sales channels"]},"post":{"operationId":"PricingController_savePricingRule","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The saved rule","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Save a pricing rule","description":"Creates or replaces a pricing rule. Rules change what customers are charged on live marketplaces the next time prices sync — calculate first and check the numbers before syncing.\n\n#### Signature\n\n```http\nPOST /sales-channel/pricing/rules (body) -> The saved rule\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Affects live selling prices once synced.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/pricing/calculate/all`","tags":["Sales channels"],"requestBody":{"description":"The rule.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Amazon fee uplift","channel":"amazon","adjustmentType":"percentage","adjustmentValue":15,"minMargin":10}}}}}},"/sales-channel/pricing/rules/{ruleId}":{"get":{"operationId":"PricingController_getPricingRule","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"ruleId","required":true,"in":"path","schema":{"type":"string"},"description":"Rule id.","example":"PR-12"}],"responses":{"200":{"description":"The rule","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a pricing rule","description":"Fetches one pricing rule.\n\n#### Signature\n\n```http\nGET /sales-channel/pricing/rules/{ruleId} (ruleId: string) -> The rule\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /sales-channel/pricing/rules/{ruleId}`","tags":["Sales channels"]},"delete":{"operationId":"PricingController_deletePricingRule","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"ruleId","required":true,"in":"path","schema":{"type":"string"},"description":"Rule id.","example":"PR-12"}],"responses":{"200":{"description":"The delete result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a pricing rule","description":"Removes a pricing rule. Prices already pushed to channels stay as they are until the next sync recalculates them without the rule — which can drop a marketplace price below the margin the rule was protecting.\n\n#### Signature\n\n```http\nDELETE /sales-channel/pricing/rules/{ruleId} (ruleId: string) -> The delete result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Re-sync deliberately after deleting a rule.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/pricing/sync/{channelId}`","tags":["Sales channels"]}},"/sales-channel/pricing/calculate/{channelId}":{"post":{"operationId":"PricingController_calculateChannelPrice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The calculated price and breakdown","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/pricing/calculate/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Calculate a channel price","description":"Runs the pricing rules for one channel against a product and returns the resulting price with its breakdown. Pure calculation — nothing is saved or pushed.\n\n#### Signature\n\n```http\nPOST /sales-channel/pricing/calculate/{channelId} (channelId: string, body) -> The calculated price and breakdown\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/pricing/calculate/all`","tags":["Sales channels"],"requestBody":{"description":"The product to price.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","price"],"properties":{"sku":{"type":"string","example":"COLA-330"},"price":{"type":"number","description":"Base price.","example":1.99},"cost":{"type":"number","description":"Enables margin rules.","example":0.8},"categoryId":{"type":"string"},"brand":{"type":"string"}}},"example":{"sku":"COLA-330","price":1.99,"cost":0.8}}}}}},"/sales-channel/pricing/calculate/all":{"post":{"operationId":"PricingController_calculateAllChannelPrices","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Per-channel prices","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Calculate prices for every channel","description":"Prices one product for all configured channels side by side — the preview to check before a price sync.\n\n#### Signature\n\n```http\nPOST /sales-channel/pricing/calculate/all (body) -> Per-channel prices\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/pricing/sync/{channelId}`","tags":["Sales channels"],"requestBody":{"description":"The product to price.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","price"],"properties":{"sku":{"type":"string"},"price":{"type":"number"},"cost":{"type":"number"},"categoryId":{"type":"string"},"brand":{"type":"string"}}},"example":{"sku":"COLA-330","price":1.99,"cost":0.8}}}}}},"/sales-channel/pricing/sync/{channelId}":{"post":{"operationId":"PricingController_syncPricesToChannel","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The sync result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/pricing/sync/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Push prices to a channel","description":"Recalculates and pushes prices to a channel. Omit `skus` and the **whole catalogue** is repriced on that marketplace — run `calculate/all` on a sample first.\n\n#### Signature\n\n```http\nPOST /sales-channel/pricing/sync/{channelId} (channelId: string, body) -> The sync result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- An empty body reprices the entire catalogue on that channel.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/pricing/calculate/all`","tags":["Sales channels"],"requestBody":{"description":"Optional SKU list; omit for the whole catalogue.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"example":["COLA-330"]}}},"examples":{"some":{"summary":"Specific SKUs","value":{"skus":["COLA-330","COLA-500"]}},"all":{"summary":"Entire catalogue","description":"Reprices everything on the marketplace.","value":{}}}}}}}},"/sales-channel/pricing/history/{sku}":{"get":{"operationId":"PricingController_getPriceHistory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"COLA-330"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"Price history, newest first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get price history for a SKU","description":"What a SKU has been priced at over time, optionally on one channel — the record for answering why a customer was charged what they were.\n\n#### Signature\n\n```http\nGET /sales-channel/pricing/history/{sku} (sku: string, channel?: string, limit?: integer) -> Price history, newest first\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/pricing/compare/{sku}`","tags":["Sales channels"]}},"/sales-channel/pricing/competitor":{"post":{"operationId":"PricingController_saveCompetitorPrice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The recorded price","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Record a competitor price","description":"Stores an observed competitor price for a SKU. Feeds the comparison view and any repricing rules that key off competitor data — it is an observation, so record where it came from.\n\n#### Signature\n\n```http\nPOST /sales-channel/pricing/competitor (body) -> The recorded price\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/pricing/competitor/{sku}`","tags":["Sales channels"],"requestBody":{"description":"The observation.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku","competitor","price"],"properties":{"sku":{"type":"string","example":"COLA-330"},"competitor":{"type":"string","example":"BigMart"},"price":{"type":"number","example":1.79},"url":{"type":"string","example":"https://bigmart.example.com/cola-330"}}},"example":{"sku":"COLA-330","competitor":"BigMart","price":1.79,"url":"https://bigmart.example.com/cola-330"}}}}}},"/sales-channel/pricing/competitor/{sku}":{"get":{"operationId":"PricingController_getCompetitorPrices","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"COLA-330"}],"responses":{"200":{"description":"Competitor prices","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get competitor prices for a SKU","description":"Recorded competitor prices for one SKU. Each carries its observation time — treat older entries as stale rather than current market truth.\n\n#### Signature\n\n```http\nGET /sales-channel/pricing/competitor/{sku} (sku: string) -> Competitor prices\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/pricing/competitor`","tags":["Sales channels"]}},"/sales-channel/pricing/compare/{sku}":{"get":{"operationId":"PricingController_getPriceComparison","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"COLA-330"}],"responses":{"200":{"description":"The comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Compare a SKU's prices","description":"The org's price on each channel alongside recorded competitor prices — the one view for deciding whether a SKU is mispriced.\n\n#### Signature\n\n```http\nGET /sales-channel/pricing/compare/{sku} (sku: string) -> The comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/pricing/history/{sku}`","tags":["Sales channels"]}},"/sales-channel/analytics/metrics/sync/{channelId}":{"post":{"operationId":"ChannelAnalyticsController_syncSalesMetrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The sync result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/analytics/metrics/sync/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Sync sales metrics from a channel","description":"Pulls the channel's own sales figures into the analytics store, so channel reporting reflects marketplace-side numbers rather than only locally aggregated orders.\n\n#### Signature\n\n```http\nPOST /sales-channel/analytics/metrics/sync/{channelId} (channelId: string) -> The sync result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/metrics`","tags":["Sales channels"]}},"/sales-channel/analytics/metrics/{channelId}":{"post":{"operationId":"ChannelAnalyticsController_recordSalesMetrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The stored metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Record sales metrics","description":"Writes sales metrics for a channel directly — for channels with no metrics API, or for back-filling. Manually written figures sit alongside synced ones and are not distinguished in reports.\n\n#### Signature\n\n```http\nPOST /sales-channel/analytics/metrics/{channelId} (channelId: string, body) -> The stored metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sales-channel/analytics/metrics/sync/{channelId}`","tags":["Sales channels"],"requestBody":{"description":"The metrics.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"revenue":12400,"orders":320,"units":890}}}}}},"/sales-channel/analytics/metrics":{"get":{"operationId":"ChannelAnalyticsController_getSalesMetrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"},{"name":"fromDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-01"},{"name":"toDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-31"}],"responses":{"200":{"description":"Metrics","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get sales metrics","description":"Sales metrics over a date range, optionally for one channel.\n\n#### Signature\n\n```http\nGET /sales-channel/analytics/metrics (channel?: string, fromDate?: string, toDate?: string) -> Metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/summary`","tags":["Sales channels"]}},"/sales-channel/analytics/products/{sku}/{channelId}":{"post":{"operationId":"ChannelAnalyticsController_recordProductPerformance","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":true,"in":"path","schema":{"type":"string"},"description":"Product SKU.","example":"COLA-330"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The stored metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Record product performance","description":"Writes performance metrics for one SKU on one channel — views, conversion, units.\n\n#### Signature\n\n```http\nPOST /sales-channel/analytics/products/{sku}/{channelId} (sku: string, channelId: string, body) -> The stored metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/products`","tags":["Sales channels"],"requestBody":{"description":"The metrics.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"views":4200,"unitsSold":118,"conversionRate":2.8}}}}}},"/sales-channel/analytics/products":{"get":{"operationId":"ChannelAnalyticsController_getProductPerformance","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":false,"in":"query","schema":{"type":"string"},"example":"COLA-330"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"},{"name":"fromDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-01"},{"name":"toDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-31"}],"responses":{"200":{"description":"Product performance","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get product performance","description":"Per-product performance across channels — which SKUs sell where, and which listings get traffic without converting.\n\n#### Signature\n\n```http\nGET /sales-channel/analytics/products (sku?: string, channel?: string, fromDate?: string, toDate?: string) -> Product performance\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/compare`","tags":["Sales channels"]}},"/sales-channel/analytics/summary":{"get":{"operationId":"ChannelAnalyticsController_getChannelSummary","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"fromDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-01"},{"name":"toDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-31"}],"responses":{"200":{"description":"The summary","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an analytics summary","description":"Headline figures across all channels for a date range.\n\n#### Signature\n\n```http\nGET /sales-channel/analytics/summary (fromDate?: string, toDate?: string) -> The summary\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/dashboard`","tags":["Sales channels"]}},"/sales-channel/analytics/dashboard":{"get":{"operationId":"ChannelAnalyticsController_getDashboardMetrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"fromDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-01"},{"name":"toDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-31"}],"responses":{"200":{"description":"The dashboard payload","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get the channel dashboard","description":"The composed dashboard payload — summary, per-channel breakdown and top products in one response, so a dashboard renders from a single call.\n\n#### Signature\n\n```http\nGET /sales-channel/analytics/dashboard (fromDate?: string, toDate?: string) -> The dashboard payload\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/summary`","tags":["Sales channels"]}},"/sales-channel/analytics/compare":{"get":{"operationId":"ChannelAnalyticsController_getChannelComparison","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channels","required":true,"in":"query","schema":{"type":"string"},"description":"Comma-separated channel ids.","example":"amazon,ebay"},{"name":"fromDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-01"},{"name":"toDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date, inclusive.","example":"2026-08-31"}],"responses":{"200":{"description":"The comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Compare channels","description":"Puts named channels side by side over the same date range — the read for deciding where a product actually earns its margin.\n\n#### Signature\n\n```http\nGET /sales-channel/analytics/compare (channels?: string, fromDate?: string, toDate?: string) -> The comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/analytics/dashboard`","tags":["Sales channels"]}},"/sales-channel/optimization/analyze/{channelId}":{"post":{"operationId":"ListingOptimizationController_analyzeProduct","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"Score and suggestions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/optimization/analyze/{channelId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Analyse a listing","description":"Scores one product's listing for a channel and returns improvement suggestions — title length, missing attributes, image count, keyword coverage. Analysis only; nothing is changed until a suggestion is applied.\n\n#### Signature\n\n```http\nPOST /sales-channel/optimization/analyze/{channelId} (channelId: string, body) -> Score and suggestions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/optimization/suggestions`","tags":["Sales channels"],"requestBody":{"description":"The product to analyse.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sku":"COLA-330","title":"Cola 330ml","description":"Refreshing cola."}}}}}},"/sales-channel/optimization/analyze/{channelId}/bulk":{"post":{"operationId":"ListingOptimizationController_bulkAnalyze","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channelId","required":true,"in":"path","schema":{"type":"string"},"description":"Channel identifier, e.g. `amazon`, `ebay`, `walmart`.","example":"amazon"}],"responses":{"201":{"description":"The analysis result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Unknown channel: <channelId> — The channel id is not one the platform supports.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown channel: <channelId>","path":"/sales-channel/optimization/analyze/{channelId}/bulk","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Analyse the whole catalogue","description":"Runs listing analysis across every product for a channel and stores the scores and suggestions. Catalogue-wide, so it can run for a while on a large catalogue.\n\n#### Signature\n\n```http\nPOST /sales-channel/optimization/analyze/{channelId}/bulk (channelId: string) -> The analysis result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | UNKNOWN_CHANNEL | Unknown channel: <channelId> | The channel id is not one the platform supports. | List supported channels with `GET /sales-channel/channels`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/optimization/scores`","tags":["Sales channels"]}},"/sales-channel/optimization/scores":{"get":{"operationId":"ListingOptimizationController_getListingScores","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":false,"in":"query","schema":{"type":"string"},"example":"COLA-330"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"}],"responses":{"200":{"description":"Scores","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List listing scores","description":"Stored listing-quality scores, filterable by SKU or channel — where to focus listing work.\n\n#### Signature\n\n```http\nGET /sales-channel/optimization/scores (sku?: string, channel?: string) -> Scores\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/optimization/summary`","tags":["Sales channels"]}},"/sales-channel/optimization/suggestions":{"get":{"operationId":"ListingOptimizationController_getSuggestions","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"sku","required":false,"in":"query","schema":{"type":"string"},"example":"COLA-330"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"example":"amazon"},{"name":"priority","required":false,"in":"query","schema":{"type":"string"},"example":"high"},{"name":"applied","required":false,"in":"query","schema":{"type":"boolean"},"description":"Filter by whether the suggestion has been applied.","example":false}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List optimisation suggestions","description":"Individual suggestions from listing analysis, filterable by SKU, channel, priority and whether they have already been applied. Filter `applied=false` for the outstanding work.\n\n#### Signature\n\n```http\nGET /sales-channel/optimization/suggestions (sku?: string, channel?: string, priority?: string, applied?: boolean) -> Suggestions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /sales-channel/optimization/suggestions/{suggestionId}/apply`","tags":["Sales channels"]}},"/sales-channel/optimization/suggestions/{suggestionId}/apply":{"put":{"operationId":"ListingOptimizationController_markSuggestionApplied","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"suggestionId","required":true,"in":"path","schema":{"type":"string"},"description":"Suggestion id.","example":"SUG-4821"}],"responses":{"200":{"description":"The applied suggestion","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Apply an optimisation suggestion","description":"Applies a suggestion to the listing and marks it applied. This edits real listing content — review the suggestion before applying, particularly anything that rewrites a title or description.\n\n#### Signature\n\n```http\nPUT /sales-channel/optimization/suggestions/{suggestionId}/apply (suggestionId: string) -> The applied suggestion\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Modifies listing content.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/optimization/suggestions`","tags":["Sales channels"]}},"/sales-channel/optimization/summary":{"get":{"operationId":"ListingOptimizationController_getOptimizationSummary","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The summary","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an optimisation summary","description":"Aggregate listing health — average scores and outstanding suggestion counts by channel.\n\n#### Signature\n\n```http\nGET /sales-channel/optimization/summary () -> The summary\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sales-channel/optimization/scores`","tags":["Sales channels"]}},"/crm/prospects/estimate":{"post":{"operationId":"ProspectingController_estimate","summary":"What a search would cost at most, before anything is charged","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/search":{"post":{"operationId":"ProspectingController_search","summary":"Search people (PDL), companies (Diffbot) or the map (Google) with ICP filters; results land in the raw contact list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects":{"get":{"operationId":"ProspectingController_list","summary":"The raw contact list with counts by status","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/{id}/read-website":{"post":{"operationId":"ProspectingController_readWebsite","summary":"Read the company's website into the raw contact (Spider Cloud)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/classify/{criteriaId}":{"post":{"operationId":"ProspectingController_classify","summary":"Rank found contacts with the AI Classifier on a rule set: qualified / review / rejected","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"criteriaId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/run":{"post":{"operationId":"ProspectingController_run","summary":"Start a Lead Finder run (a background job): steps of blocks — bring_in, look_up, find_people, rank, move, reach_out — on a selection; with listId, what is brought in joins that list (one run per list at a time)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/lists/{id}/run":{"post":{"operationId":"ProspectingController_runList","summary":"Run a saved list's steps again (a background job): known contacts recognised, new matches added; the run is kept on the list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/lists/{id}/add":{"post":{"operationId":"ProspectingController_addToList","summary":"Put found contacts on a saved list without searching again (a search's refs, or ids) — nothing is charged","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/bulk":{"post":{"operationId":"ProspectingController_bulk","summary":"One action on picked prospects: add_to_list / remove_from_list (listId), set_status (new|qualified|review|rejected), delete. Moving them into the CRM is promote.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/runs/{jobId}":{"get":{"operationId":"ProspectingController_runStatus","summary":"A Lead Finder run: status, each step’s counts, cost and failures","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/promote":{"post":{"operationId":"ProspectingController_promote","summary":"Move found contacts into the CRM: contact (merged) + a lead in the chosen pipeline","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/prospects/ingest":{"post":{"operationId":"ProspectingController_ingest","summary":"Add captured finds (Lead Search Chrome plugin: LinkedIn profiles, Google Maps businesses) to the raw contact list","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Prospecting"]}},"/crm/blueprints/{id}/build":{"post":{"operationId":"BlueprintController_build","summary":"Build the blueprint as a background job (the AI makes each block in its app and joins the wires); survives a restart","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM Blueprints"]},"get":{"operationId":"BlueprintController_buildRunning","summary":"The build of this blueprint running now, if any (started by Build or by the AI)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/builds/{jobId}":{"get":{"operationId":"BlueprintController_buildStatus","summary":"A build's state: running or not, what is left, the AI's last word","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/catalogue":{"get":{"operationId":"BlueprintController_catalogue","summary":"The block types: what each is, the app that delivers it, its record, its ports","parameters":[],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/candidates/{type}":{"get":{"operationId":"BlueprintController_candidates","summary":"Existing records that could be placed as a block of this type","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"type","required":true,"in":"path","schema":{"type":"string"}},{"name":"search","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/{id}/view":{"get":{"operationId":"BlueprintController_view","summary":"A blueprint as it stands: each block with its record, what it holds, its numbers for the period; and the links that exist between placed records","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"days","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/{id}/place":{"post":{"operationId":"BlueprintController_place","summary":"Put an existing record on the blueprint as a built block","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/{id}/edit":{"post":{"operationId":"BlueprintController_edit","summary":"Change the design: add_block, update_block, move_block, remove_block, add_wire, remove_wire","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/list":{"get":{"operationId":"BlueprintController_list","summary":"The org's blueprints, a page at a time, each with its status, parts switched off, leads in the last 30 days and failed runs","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/{id}/activity":{"get":{"operationId":"BlueprintController_activity","summary":"What happened to people in the blueprint, newest first: form answers, leads and their history, automation runs, broadcast sends, list runs","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/{id}/dashboard":{"get":{"operationId":"BlueprintController_dashboard","summary":"How the blueprint is doing: totals, per day, funnels, what failed, what is switched off","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"days","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/{id}/copy":{"post":{"operationId":"BlueprintController_copy","summary":"A new blueprint as a design copy of this one (a starter or any blueprint): same blocks and wires, nothing built","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM Blueprints"]}},"/crm/blueprints/{id}/link":{"post":{"operationId":"BlueprintController_link","summary":"Link a block or wire to the record it was built as (or mark it failed, with why)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM Blueprints"]}},"/sync/social-activities/profiles/{platform}":{"get":{"operationId":"SocialActivityController_getProfiles","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","in":"path","required":true,"description":"Optional segment, accepted but **ignored** — only the `platform` query parameter is read. `GET /sync/social-activities/profiles` reaches the same handler.","schema":{"type":"string"},"example":"instagram"},{"name":"platform","in":"query","required":false,"description":"Comma-separated platforms to fetch, from `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`. Omit for every platform in the sync settings.","schema":{"type":"string"},"example":"facebook,instagram"}],"responses":{"200":{"description":"Account details keyed by platform","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true,"description":"The platform's account details, as it returned them."}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get connected social profiles","description":"Fetches the account details of the org's connected social accounts **live from each platform** — one call per platform, made now, not read from the activity store.\n\nName the platforms in the `platform` **query** parameter, comma-separated (`?platform=facebook,instagram`). Omit it and every platform in the org's social sync settings is fetched. For each platform the account asked about is the one saved for it in those settings, through the `default` integration config.\n\nThe result is an object keyed by platform; each value is what the platform returned for the account. A platform that fails — not in the sync settings, not connected, or refused by the platform — is left out, so a missing key means \"could not fetch\", not \"no account\".\n\n#### Signature\n\n```http\nGET /sync/social-activities/profiles/{platform} (platform: string, platform?: string) -> Account details keyed by platform\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `/profiles/instagram` returns every platform, not just Instagram — the path segment is not read. Use `?platform=instagram`.\n- With no `platform` and no social sync settings saved for the org, the call fails with a 500 rather than returning `{}`.\n- Each call goes to the platforms and counts against their rate limits.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platforms`","tags":["CRM · Social"]}},"/sync/social-activities/reply":{"post":{"operationId":"SocialActivityController_replyToActivity","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"`success: true` and the page or account it was sent from; or `success: false` with the reason (e.g. the message was not found, no connected page, or the platform refused it).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"sentFrom":{"type":"string","description":"The page or account the reply was sent from.","example":"115816908447835"},"error":{"type":"string","description":"Why it was not sent, when `success` is false."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Reply to a social message or comment","description":"Sends a reply to a customer on the platform they wrote on — a direct message stays a direct message, a comment reply goes on the comment — and records it in the conversation thread.\n\nName the message being answered by our own id (`activityId`, the `social_activity` record) and give the reply. The server works out everything else from that record: the platform, whether it is a message or a comment, the customer to send to, the page or account they wrote to (the reply is sent from it), and the comment and post ids. The reply is signed with the name of the signed-in user.\n\nThe reply is recorded as an outbound `social_activity` (`isAiGenerated: false`), so it shows in the thread and the platform's echo of the same message is not recorded twice.\n\n#### Signature\n\n```http\nPOST /sync/social-activities/reply (body) -> `success: true` and the page or account it was sent from; or `success: false` with the reason (e.g. the message was not found, no connected page, or the platform refused it).\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A reply to a public comment is public. Move anything sensitive to a direct message first.\n- Older callers may still send platform, to, pageId, commentId and postId themselves; with `activityId` those are worked out by the server.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/conversation-thread`\n- `POST /sync/social-activities/ai-hold`","tags":["CRM · Social"],"requestBody":{"description":"The message being answered, and the reply.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["activityId"],"properties":{"activityId":{"type":"string","description":"Our id of the message or comment being answered (a `social_activity` sk) — usually the customer's latest message in the thread.","example":"6ab60d3a4501ae658d446b10"},"message":{"type":"string","description":"The reply text. Required unless attachments are sent.","example":"It is back in stock now — thanks for waiting!"},"attachments":{"type":"array","items":{"type":"string"},"description":"Optional file URLs to send with the reply (direct messages)."},"note":{"type":"string","description":"Optional handover note kept on the recorded reply — what was done or decided, for whoever picks the conversation up next."}}},"example":{"activityId":"6ab60d3a4501ae658d446b10","message":"It is back in stock now — thanks for waiting!"}}}}}},"/sync/social-activities/ai-hold":{"post":{"operationId":"SocialActivityController_setAiHold","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The new state","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","example":"instagram"},"customerId":{"type":"string","example":"17841400000000000"},"aiHold":{"type":"boolean","description":"`true` when AI replies are now paused.","example":true},"by":{"type":"string","description":"The signed-in user's email (`agent` if it has none).","example":"ada@example.com"},"at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"platform and customerId are required — `platform` or `customerId` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"platform and customerId are required","path":"/sync/social-activities/ai-hold","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Pause or resume AI replies to a customer","description":"Pauses or resumes AI replies to one customer on one platform, so a person can handle the conversation without an assistant answering over them.\n\nIt holds **replies only**. Assistants still run on the conversation — tickets, notes and notifications still happen — they just do not message the customer. A hold never expires: it stays until someone resumes it.\n\nEvery call adds a record to the conversation (`social_activity` with `standardActivityType: ai-hold`); nothing is updated or deleted, so the trail of who paused and resumed, and why, is kept. The current state is the latest record. The signed-in user's email is recorded as who did it.\n\n#### Signature\n\n```http\nPOST /sync/social-activities/ai-hold (body) -> The new state\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A hold is per customer id per platform — it covers that customer on every one of our accounts on the platform. The same person on another platform has a different id and still gets AI replies.\n- Pausing twice is harmless: it adds a second record and the state stays paused.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | HOLD_TARGET_REQUIRED | platform and customerId are required | `platform` or `customerId` is missing. | Send both — a hold is always for one customer on one platform. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/ai-hold`\n- `POST /sync/social-activities/reply`","tags":["CRM · Social"],"requestBody":{"description":"Whose replies to pause or resume.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","customerId"],"properties":{"platform":{"type":"string","description":"The platform, e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"},"customerId":{"type":"string","description":"Platform id of the customer.","example":"17841400000000000"},"hold":{"type":"boolean","default":true,"description":"`false` resumes AI replies. Anything else — including leaving it out — pauses them.","example":true},"reason":{"type":"string","description":"Why. Kept in the trail and shown in the record's text (\"AI replies paused: …\").","example":"Complaint — needs a human"},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on. Stored on the record only — it does not narrow the hold.","example":"115816908447835"}}},"examples":{"hold":{"summary":"Pause AI replies","value":{"platform":"instagram","customerId":"17841400000000000","hold":true,"reason":"Complaint — needs a human"}},"release":{"summary":"Resume AI replies","value":{"platform":"instagram","customerId":"17841400000000000","hold":false}}}}}}},"get":{"operationId":"SocialActivityController_getAiHold","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":true,"in":"query","schema":{"type":"string"},"description":"The platform.","example":"instagram"},{"name":"customerId","required":true,"in":"query","schema":{"type":"string"},"description":"Platform id of the customer.","example":"17841400000000000"}],"responses":{"200":{"description":"Current state and the trail","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","example":"instagram"},"customerId":{"type":"string","example":"17841400000000000"},"aiHold":{"type":"boolean","description":"Whether AI replies are paused now (the latest action was a pause).","example":true},"since":{"type":"string","format":"date-time","nullable":true,"description":"When the latest action was taken; `null` if there has never been one."},"by":{"type":"string","nullable":true,"description":"Who took the latest action.","example":"ada@example.com"},"trail":{"type":"array","description":"The last 20 pause/resume actions, newest first.","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"hold":{"type":"boolean","description":"`true` for a pause, `false` for a resume."},"by":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true}}}}}},"example":{"platform":"instagram","customerId":"17841400000000000","aiHold":true,"since":"2026-09-24T14:05:00.000Z","by":"ada@example.com","trail":[{"at":"2026-09-24T14:05:00.000Z","hold":true,"by":"ada@example.com","reason":"Complaint — needs a human"}]}}}},"400":{"description":"platform and customerId are required — `platform` or `customerId` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"platform and customerId are required","path":"/sync/social-activities/ai-hold","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get AI hold state for a customer","description":"Whether AI replies to one customer on one platform are paused, and the trail behind it — who paused or resumed, when and why — so an agent can tell whether the pause still makes sense.\n\n#### Signature\n\n```http\nGET /sync/social-activities/ai-hold (platform?: string, customerId?: string) -> Current state and the trail\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- If the lookup itself fails the answer is \"not paused\" with an empty trail, not an error.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | HOLD_TARGET_REQUIRED | platform and customerId are required | `platform` or `customerId` is missing. | Send both — a hold is always for one customer on one platform. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sync/social-activities/ai-hold`","tags":["CRM · Social"]}},"/sync/social-activities/conversations":{"get":{"operationId":"SocialActivityController_getSocialConversations","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"account","required":false,"in":"query","schema":{"type":"string"},"description":"Only conversations on this connected account (page or account id). `all`, or leaving it out, means every account.","example":"115816908447835"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":0},"description":"Page number, **0-based**.","example":0},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":30},"description":"How many to return. Capped at 100; `0` or omitted gives 30.","example":30}],"responses":{"200":{"description":"One page of conversations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The conversation's grouping key: `platform|ourId|customerId`, with the post id before the customer id for comment threads.","example":"instagram|17841400000000001|17841400000000000"},"platform":{"type":"string","example":"instagram"},"ourId":{"type":"string","description":"Our page or account the conversation is on.","example":"17841400000000001"},"accountName":{"type":"string","nullable":true,"description":"Display name of that account, from the records or the connected integrations; `null` when unknown.","example":"Acme Retail"},"customerId":{"type":"string","description":"Platform id of the customer. Can be empty for comment threads where the platform gave no commenter id.","example":"17841400000000000"},"customerName":{"type":"string","description":"The customer's name as last seen; falls back to `customerId`.","example":"ada.lovelace"},"activityType":{"type":"string","enum":["message","comment"],"description":"`comment` for a comment thread, otherwise `message`.","example":"message"},"postId":{"type":"string","description":"The post, for comment threads."},"lastMessageDate":{"type":"number","description":"Epoch milliseconds of the latest activity.","example":1788000000000},"lastMessageText":{"type":"string","example":"Is this back in stock?"},"messageCount":{"type":"integer","example":6},"hasAI":{"type":"boolean","description":"Whether an assistant has replied anywhere in the conversation."}}},"description":"The conversations on this page."},"page":{"type":"integer","description":"The page returned, 0-based.","example":0},"pageSize":{"type":"integer","description":"The page size used, after the default and cap.","example":30},"hasMore":{"type":"boolean","description":"`true` when the page came back full. It can be `true` on the last page when the count divides exactly — the next page is then empty."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List social conversations","description":"The social inbox: message, comment and mention activity grouped into conversations, the most recently active first. Grouping, the account filter, account names and paging are all done on the server.\n\nA direct-message conversation is one customer on one of our accounts on one platform. Comments are also split by post, so one person commenting on two posts is two conversations.\n\nSeparate from `/crm/inbox`, which covers email, SMS and chat.\n\n#### Signature\n\n```http\nGET /sync/social-activities/conversations (account?: string, page?: integer, pageSize?: integer) -> One page of conversations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Pages are **0-based** here, unlike most list endpoints, and no `total` is returned — page on until `hasMore` is `false`.\n- The account filter matches the account id on the record, the author or recipient id, or a post id that starts with `<account>_`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/conversation-thread`\n- `GET /crm/inbox/conversations`","tags":["CRM · Social"]}},"/sync/social-activities/conversation-thread":{"get":{"operationId":"SocialActivityController_getSocialThread","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":true,"in":"query","schema":{"type":"string"},"description":"The platform. Not checked by the server, but always send it — without it nothing from a real platform matches.","example":"instagram"},{"name":"customer","required":false,"in":"query","schema":{"type":"string"},"description":"Platform id of the customer. Needed unless `postId` is given.","example":"17841400000000000"},{"name":"postId","required":false,"in":"query","schema":{"type":"string"},"description":"The post, for a comment thread.","example":"18021234567890"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":0},"description":"Page number, **0-based**.","example":0},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":100},"description":"How many to return. Capped at 200; `0` or omitted gives 100.","example":100}],"responses":{"200":{"description":"One page of the thread, oldest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"The messages on this page. A message someone reacted to carries `data.reactions: [{ emoji, reaction, authorId }]`."},"page":{"type":"integer","description":"The page returned, 0-based.","example":0},"pageSize":{"type":"integer","description":"The page size used, after the default and cap.","example":30},"hasMore":{"type":"boolean","description":"`true` when the page came back full. It can be `true` on the last page when the count divides exactly — the next page is then empty."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a social conversation thread","description":"The messages in one conversation, both sides, oldest first.\n\nFor a direct-message thread pass the customer's id: that matches what they sent us and what we sent them. For a comment thread pass `postId`: that returns the comments on the post, narrowed to one commenter when `customer` is given too. Instagram comment webhooks often carry no commenter id, so `postId` alone is the usual call there.\n\nOnly `message`, `comment` and `mention` rows are returned — the per-conversation summary row the sync writes, and AI-hold records, are left out. Reactions to a message are attached to it as `data.reactions`: the latest reaction from each person, with withdrawn reactions dropped.\n\n#### Signature\n\n```http\nGET /sync/social-activities/conversation-thread (platform?: string, customer?: string, postId?: string, page?: integer, pageSize?: integer) -> One page of the thread, oldest first\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- With neither `customer` nor `postId` — or with them sent as the strings `null` or `undefined` — the result is an empty page, not an error.\n- Pages are **0-based**.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sync/social-activities/reply`\n- `GET /sync/social-activities/conversations`","tags":["CRM · Social"]}},"/sync/social-activities/messages":{"get":{"operationId":"SocialActivityController_getAllMessages","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The first page of matching social activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social messages","description":"Direct messages across social platforms — both what customers sent and the replies we sent. These are **not** in the `/crm/inbox` store; social DMs live in `social_activity`.\n\nMatches `standardActivityType` = `message`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/messages (startDate?: string, endDate?: string, platform?: string) -> The first page of matching social activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/comments":{"get":{"operationId":"SocialActivityController_getAllComments","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The first page of matching social activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social comments","description":"Comments on the org's social posts, across platforms — customers' comments and our replies to them.\n\nMatches `standardActivityType` = `comment`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/comments (startDate?: string, endDate?: string, platform?: string) -> The first page of matching social activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/posts":{"get":{"operationId":"SocialActivityController_getAllPosts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The posts in unified feed form","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"A generated label — the platform name plus \" Page\" (e.g. `Instagram Page`), or `Social Media Page` with no platform. Not the account's real name.","example":"Instagram Page"},"picture":{"type":"object","description":"Always `{ data: { url: \"\" } }` — no profile picture is looked up."},"platform":{"type":"string","description":"The platform asked for; absent when none was.","example":"instagram"},"feed":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The platform's id for the item (`sourceId`).","example":"18021234567890"},"message":{"type":"string","description":"The text — taken from `content`, `message`, `text` or `description`, whichever is set."},"created_time":{"description":"From `createdAt`, `created_time` or `timestamp`, as stored (a string or epoch milliseconds)."},"likes":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_count":{"type":"integer","example":42}}}}},"comments":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_count":{"type":"integer","example":7}}}}},"shares":{"type":"object","properties":{"count":{"type":"integer","example":3}}},"attachments":{"type":"object","properties":{"data":{"type":"array","description":"Built from `mediaUrls`, `picture`, `full_picture` and `video`.","items":{"type":"object","properties":{"media":{"type":"object","description":"`{ image: { src } }` or `{ video: { src } }`."},"type":{"type":"string","description":"`photo`, `video`, `link` or `unknown` — guessed from the URL's file extension.","example":"photo"}}}}}},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"picture":{"type":"string"}}},"platform":{"type":"string","example":"instagram"},"sourceType":{"type":"string","example":"instagram-post"},"url":{"type":"string"},"views":{"type":"integer","example":0},"reach":{"type":"integer","example":0},"impressions":{"type":"integer","example":0}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social posts","description":"The org's own posts (`standardActivityType` `post` or `article`), reshaped into a single \"unified feed\" layout for display: one object with the posts under `feed.data`, each post with its counts, attachments and author in a fixed shape whatever platform it came from.\n\n#### Signature\n\n```http\nGET /sync/social-activities/posts (startDate?: string, endDate?: string, platform?: string) -> The posts in unified feed form\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- At most 50 posts, most recently modified first; there is no paging and no total.\n- Unlike the other feeds this does not return the stored records — only the unified shape.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/dashboard/analytics/{platform}`\n- `GET /sync/social-activities/refresh/{platform}/{action}`","tags":["CRM · Social"]}},"/sync/social-activities/engagement":{"get":{"operationId":"SocialActivityController_getAllEngagement","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The first page of matching social activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get engagement activity","description":"Likes, reactions, shares and retweets recorded across platforms.\n\nMatches `standardActivityType` of `like`, `reaction`, `share`, `retweet`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/engagement (startDate?: string, endDate?: string, platform?: string) -> The first page of matching social activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/leads":{"get":{"operationId":"SocialActivityController_getAllLeads","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The first page of matching social activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social leads","description":"Leads captured from social platforms, such as lead-ad form fills.\n\nMatches `standardActivityType` = `lead`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/leads (startDate?: string, endDate?: string, platform?: string) -> The first page of matching social activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/ads":{"get":{"operationId":"SocialActivityController_getAllAds","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The first page of matching social activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social ad activity","description":"Ad records synced into the social store — distinct from the campaign management under `/crm/ads`.\n\nMatches `standardActivityType` = `ad`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/ads (startDate?: string, endDate?: string, platform?: string) -> The first page of matching social activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/campaigns":{"get":{"operationId":"SocialActivityController_getAllCampaigns","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The first page of matching social activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social campaign activity","description":"Campaign records synced into the social store.\n\nMatches `standardActivityType` = `campaign`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/campaigns (startDate?: string, endDate?: string, platform?: string) -> The first page of matching social activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/analytics":{"get":{"operationId":"SocialActivityController_getAllAnalytics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one platform (exact match), e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"}],"responses":{"200":{"description":"The first page of matching social activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social analytics records","description":"The analytics, insight and metric records synced from the platforms, as stored — not aggregated.\n\nMatches `standardActivityType` of `analytics`, `insight`, `metric`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/analytics (startDate?: string, endDate?: string, platform?: string) -> The first page of matching social activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/platform/{platform}/type/{activityType}":{"get":{"operationId":"SocialActivityController_getActivitiesByPlatformAndType","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":true,"in":"path","schema":{"type":"string"},"description":"The platform, e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"},{"name":"activityType","required":true,"in":"path","schema":{"type":"string"},"description":"A standard activity type — `GET /sync/social-activities/platforms` lists them all. Not validated: an unknown type returns an empty page.","example":"mention"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"}],"responses":{"200":{"description":"The first page of matching activity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get activity by platform and type","description":"Activity of one `standardActivityType` on one platform — for combinations the fixed feeds do not cover, such as `story`, `reel`, `mention` or `follower`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/platform/{platform}/type/{activityType} (platform: string, activityType: string, startDate?: string, endDate?: string) -> The first page of matching activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first page comes back: at most 50 records, ordered by when the record was last modified (not by `timestamp`). There is no paging parameter — narrow with the date range or platform, and read `total` for how many matched.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sync/social-activities/search`\n- `GET /sync/social-activities/platforms`","tags":["CRM · Social"]}},"/sync/social-activities/summary/platforms":{"get":{"operationId":"SocialActivityController_getActivitySummaryByPlatform","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"}],"responses":{"200":{"description":"One row per platform","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"The platform.","example":"instagram"},"totalActivities":{"type":"integer","example":1240},"activities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","nullable":true,"description":"The `standardActivityType`.","example":"comment"},"count":{"type":"integer","example":380},"latestActivity":{"type":"number","description":"Latest `timestamp` of that type, epoch milliseconds.","example":1788000000000}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a per-platform summary","description":"How many activity records each platform has, broken down by activity type, busiest platform first.\n\n#### Signature\n\n```http\nGET /sync/social-activities/summary/platforms (startDate?: string, endDate?: string) -> One row per platform\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Give either date alone and the other is filled in: `startDate` defaults to the beginning of time, `endDate` to now.\n- If the summary cannot be computed the response is `[]`, not an error.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/dashboard/analytics`\n- `GET /sync/social-activities/platforms`","tags":["CRM · Social"]}},"/sync/social-activities/metrics/engagement":{"get":{"operationId":"SocialActivityController_getEngagementMetrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"}],"responses":{"200":{"description":"One row per platform","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"The platform.","example":"instagram"},"platform":{"type":"string","example":"instagram"},"totalLikes":{"type":"integer","example":820},"totalComments":{"type":"integer","example":380},"totalShares":{"type":"integer","example":45},"totalReactions":{"type":"integer","example":120},"totalEngagement":{"type":"integer","description":"The four totals added up.","example":1365}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get engagement metrics","description":"Engagement counts per platform over a period: the number of like, comment, share and reaction records, and their sum. Counts of records, not rates. Most engaged platform first.\n\n#### Signature\n\n```http\nGET /sync/social-activities/metrics/engagement (startDate?: string, endDate?: string) -> One row per platform\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Give either date alone and the other is filled in: `startDate` defaults to the beginning of time, `endDate` to now.\n- Retweets are not counted in `totalShares`.\n- If the metrics cannot be computed the response is `[]`, not an error.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/metrics/business`\n- `GET /sync/social-activities/dashboard/analytics`","tags":["CRM · Social"]}},"/sync/social-activities/metrics/business":{"get":{"operationId":"SocialActivityController_getBusinessMetrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"}],"responses":{"200":{"description":"One row per platform","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"The platform.","example":"facebook"},"platform":{"type":"string","example":"facebook"},"totalAds":{"type":"integer","example":12},"totalCampaigns":{"type":"integer","example":3},"totalLeads":{"type":"integer","example":57},"totalSpend":{"type":"number","description":"Sum of the records' `cost`.","example":1840.5},"totalReach":{"type":"number","example":52000},"totalImpressions":{"type":"number","example":88000},"totalClicks":{"type":"number","example":1320},"ctr":{"type":"number","description":"Clicks ÷ impressions, as a fraction (0.015 = 1.5%). `0` with no impressions.","example":0.015}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get business metrics from social","description":"Ad, campaign and lead figures per platform over a period: how many of each record, and the spend, reach, impressions and clicks summed from them. Highest spend first.\n\n#### Signature\n\n```http\nGET /sync/social-activities/metrics/business (startDate?: string, endDate?: string) -> One row per platform\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Give either date alone and the other is filled in: `startDate` defaults to the beginning of time, `endDate` to now.\n- If the metrics cannot be computed the response is `[]`, not an error.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/metrics/engagement`\n- `GET /sync/social-activities/dashboard/analytics`","tags":["CRM · Social"]}},"/sync/social-activities/search":{"post":{"operationId":"SocialActivityController_searchActivitiesByContent","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Matching activity — at most 50, no total","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search social activity","description":"Searches social activity by text, with optional platform, type and date filters.\n\nWith `searchTerm`, it runs a full-text search, best matches first. If that finds nothing it falls back to a case-insensitive \"contains\" match on the text — and that fallback **drops the other filters**, so it can return activity from other platforms, types or dates. Without `searchTerm`, only the filters apply, most recently modified first.\n\n#### Signature\n\n```http\nPOST /sync/social-activities/search (body) -> Matching activity — at most 50, no total\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the first 50 matches come back and there is no paging.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/platform/{platform}/type/{activityType}`","tags":["CRM · Social"],"requestBody":{"description":"What to search for. Every field is optional; an empty body returns the most recently modified activity.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"searchTerm":{"type":"string","description":"Text to search for.","example":"refund"},"activityTypes":{"type":"array","items":{"type":"string"},"description":"Only these `standardActivityType` values.","example":["comment","message"]},"platforms":{"type":"array","items":{"type":"string"},"description":"Only these platforms.","example":["instagram"]},"startDate":{"type":"string","description":"Start of the period. Applied only when `endDate` is given too.","example":"2026-08-01"},"endDate":{"type":"string","description":"End of the period. Applied only when `startDate` is given too.","example":"2026-09-01"}}},"example":{"searchTerm":"refund","platforms":["instagram"],"activityTypes":["comment"]}}}}}},"/sync/social-activities/author/{authorId}":{"get":{"operationId":"SocialActivityController_getActivitiesByAuthor","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"authorId","required":true,"in":"path","schema":{"type":"string"},"description":"Platform id of the author.","example":"17841400000000000"},{"name":"authorName","required":false,"in":"query","schema":{"type":"string"},"description":"Also match activity whose author name contains this, case-insensitively. Read as a regular expression.","example":"ada"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Meant to restrict to one platform — currently empties the result instead (see above).","example":"instagram"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Meant to bound the period — currently empties the result instead (see above).","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"Meant to bound the period — currently empties the result instead (see above).","example":"2026-09-01"}],"responses":{"200":{"description":"A one-element array holding the page of the author's activity; `[]` when a filter is sent","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A social activity (`social_activity`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"description":"Fields vary by platform and by how the row was written; these are the ones the server itself reads.","properties":{"platform":{"type":"string","example":"instagram"},"standardActivityType":{"type":"string","description":"The normalised type every feed filters on — `message`, `comment`, `mention`, `post`, `reaction`, `lead`, `ai-hold`, …","example":"comment"},"sourceType":{"type":"string","description":"Platform plus the raw kind of item.","example":"instagram-comment"},"sourceId":{"type":"string","description":"The platform's own id for the item.","example":"18021234567890123"},"timestamp":{"type":"number","description":"When it happened, epoch milliseconds. Date filters apply to this field.","example":1788000000000},"content":{"type":"string","example":"Is this back in stock?"},"authorId":{"type":"string","description":"Who produced it — the customer on their messages, our page or account on replies we sent.","example":"17841400000000000"},"authorName":{"type":"string","example":"ada.lovelace"},"recipientId":{"type":"string","description":"Who it was sent to — the customer, on replies we sent."},"accountId":{"type":"string","description":"Which of our connected accounts the conversation is on.","example":"115816908447835"},"postId":{"type":"string","description":"Post the activity belongs to, for comments.","example":"18021234567890"},"parentId":{"type":"string","description":"The item this one answers or reacts to."},"direction":{"type":"string","description":"`outbound` for replies we sent, `internal` for AI-hold rows. Customer activity is never `outbound`.","example":"outbound"},"isAiGenerated":{"type":"boolean","description":"On replies we sent: whether an assistant wrote it."}}}}},"description":"Up to 50 records, most recently modified first."},"total":{"type":"integer","description":"Every matching record, not just the ones returned.","example":312},"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":50},"hasNext":{"type":"boolean","description":"`true` when more matched than were returned."},"datatype":{"type":"string","example":"social_activity"}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get activity by author","description":"Activity one person authored — their messages, comments and engagement — matched on their platform id, or also on a name when `authorName` is given. Replies we sent them are not included (they are authored by us).\n\n**The response is not a plain list of activity.** It is a one-element array whose only item is the page object `{ data, total, page, pageSize, hasNext, … }`, with the activity in `[0].data` (first 50, most recently modified first). And because the `platform`, `startDate` and `endDate` filters are applied to that page object rather than to the activity, sending any of them returns `[]`.\n\n#### Signature\n\n```http\nGET /sync/social-activities/author/{authorId} (authorId: string, authorName?: string, platform?: string, startDate?: string, endDate?: string) -> A one-element array holding the page of the author's activity; `[]` when a filter is sent\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Author ids are per platform — the same person has a different id on each.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/conversation-thread`\n- `POST /sync/social-activities/search`","tags":["CRM · Social"]}},"/sync/social-activities/platforms":{"get":{"operationId":"SocialActivityController_getAvailablePlatforms","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Platforms and activity types","content":{"application/json":{"schema":{"type":"object","properties":{"platforms":{"type":"array","description":"Busiest first.","items":{"type":"object","properties":{"name":{"type":"string","example":"instagram"},"totalActivities":{"type":"integer","example":1240},"activityTypes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","nullable":true,"description":"The `standardActivityType`; `null` for records without one.","example":"comment"},"count":{"type":"integer","example":380},"latestActivity":{"type":"string","format":"date-time","nullable":true,"description":"Latest `timestamp` of that type."}}}}}}},"standardActivityTypes":{"type":"array","items":{"type":"string"},"description":"Every standard activity type the server knows.","example":["post","comment","message","thread","story","reel"]},"totalPlatforms":{"type":"integer","example":3}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List platforms with activity","description":"The platforms that have activity in the store, with a count per activity type, plus the full list of standard activity types.\n\nBuilt from stored activity over all time, not from connections: a platform connected but not yet synced is missing, and one disconnected keeps appearing while its records remain.\n\n#### Signature\n\n```http\nGET /sync/social-activities/platforms () -> Platforms and activity types\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/summary/platforms`\n- `GET /sync/social-activities/profiles/{platform}`","tags":["CRM · Social"]}},"/sync/social-activities/dashboard/analytics":{"get":{"operationId":"SocialActivityController_getDashboardAnalytics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"}],"responses":{"200":{"description":"Summary, engagement and business figures","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"totalPlatforms":{"type":"integer","example":3},"totalActivities":{"type":"integer","example":2710},"platforms":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The rows of `GET /sync/social-activities/summary/platforms`."}}},"engagement":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The rows of `GET /sync/social-activities/metrics/engagement`."},"business":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The rows of `GET /sync/social-activities/metrics/business`."},"dateRange":{"type":"object","nullable":true,"description":"The period used, after defaults; `null` when no dates were given.","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get social dashboard analytics","description":"The per-platform summary, engagement metrics and business metrics in one call, over the same period — what a social dashboard needs.\n\n#### Signature\n\n```http\nGET /sync/social-activities/dashboard/analytics (startDate?: string, endDate?: string) -> Summary, engagement and business figures\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Give either date alone and the other is filled in: `startDate` defaults to the beginning of time, `endDate` to now.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/dashboard/analytics/{platform}`","tags":["CRM · Social"]}},"/sync/social-activities/dashboard/analytics/{platform}":{"get":{"operationId":"SocialActivityController_getPlatformDashboardAnalytics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":true,"in":"path","schema":{"type":"string"},"description":"The platform, e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the period, as a date or ISO timestamp. Compared with the activity's `timestamp`. A value that is not a date matches nothing.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"End of the period, inclusive of that exact instant. A bare date is midnight UTC at the **start** of that day, so the day itself is left out — pass the next day, or a full timestamp, to include it.","example":"2026-09-01"},{"name":"range","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Post totals and recent posts","content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","example":"instagram"},"summary":{"type":"object","properties":{"totalPosts":{"type":"integer","example":50},"totalEngagement":{"type":"integer","description":"Likes + comments + shares.","example":1245},"totalLikes":{"type":"integer","example":1020},"totalComments":{"type":"integer","example":180},"totalShares":{"type":"integer","example":45},"totalViews":{"type":"integer","example":30500},"totalReach":{"type":"integer","example":21000},"engagementRate":{"type":"string","description":"Average engagement **per post** (not a percentage), as a string with two decimals; `\"0\"` with no posts.","example":"24.90"}}},"recentPosts":{"type":"array","description":"Up to 10 posts, most recently modified first.","items":{"type":"object","properties":{"id":{"type":"string","description":"The platform's post id."},"message":{"type":"string"},"created_time":{"description":"As stored on the post."},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"views":{"type":"integer"}}}},"dateRange":{"type":"object","nullable":true,"description":"The period used, after defaults; `null` when no dates were given.","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get dashboard analytics for one platform","description":"Post performance on one platform: totals of likes, comments, shares, views and reach, and the ten most recently modified posts.\n\nThe figures come from the counts stored on the post records themselves, and only from the **50 most recently modified** posts (`post` or `article`) in the period — on a busy account the totals cover those 50, not every post.\n\n#### Signature\n\n```http\nGET /sync/social-activities/dashboard/analytics/{platform} (platform: string, startDate?: string, endDate?: string) -> Post totals and recent posts\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Give either date alone and the other is filled in: `startDate` defaults to the beginning of time, `endDate` to now.\n- An unknown platform returns zero totals and no posts, not an error.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/dashboard/analytics`\n- `GET /sync/social-activities/posts`","tags":["CRM · Social"]}},"/sync/social-activities/refresh/{platform}/{action}":{"get":{"operationId":"SocialActivityController_refreshPlatformData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":true,"in":"path","schema":{"type":"string"},"description":"The platform, e.g. `facebook`, `instagram`, `whatsapp`, `tiktok`, `twitter`, `linkedin`, `pinterest`.","example":"instagram"},{"name":"action","required":true,"in":"path","schema":{"type":"string"},"description":"What to fetch: `feed`, `posts`, `insights`, `analytics`, `comments`, `messages`, `notifications`, `reactions`, `engagement`, `leads`, `ads`, `campaigns`, `followers`, `profile`, or another provider `get…` operation.","example":"posts"},{"name":"configId","required":false,"in":"query","schema":{"type":"string"},"description":"Integration config to use. Defaults to the one in the sync settings, then `default`.","example":"default"},{"name":"accountId","required":false,"in":"query","schema":{"type":"string"},"description":"Account to fetch for, passed to the platform as `accountId`. Defaults to the account in the sync settings.","example":"115816908447835"},{"name":"limit","in":"query","required":false,"description":"Passed to the platform, like any other query parameter. Defaults to 25 for `feed` and `posts`.","schema":{"type":"integer"},"example":25}],"responses":{"200":{"description":"Always HTTP 200 — check `success`. On success, the saved items in unified feed form; on failure, the reason.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"platform":{"type":"string","description":"The platform asked for; absent when none was.","example":"instagram"},"action":{"type":"string","example":"posts"},"timestamp":{"type":"number","description":"Epoch milliseconds of the refresh.","example":1788000000000},"count":{"type":"integer","description":"Items the platform returned that had an id or name — including ones already stored and skipped.","example":25},"error":{"type":"string","description":"Why it failed, when `success` is false.","example":"No sync configuration found for platform: tiktok"},"name":{"type":"string","description":"A generated label — the platform name plus \" Page\" (e.g. `Instagram Page`), or `Social Media Page` with no platform. Not the account's real name.","example":"Instagram Page"},"picture":{"type":"object","description":"Always `{ data: { url: \"\" } }` — no profile picture is looked up."},"feed":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The platform's id for the item (`sourceId`).","example":"18021234567890"},"message":{"type":"string","description":"The text — taken from `content`, `message`, `text` or `description`, whichever is set."},"created_time":{"description":"From `createdAt`, `created_time` or `timestamp`, as stored (a string or epoch milliseconds)."},"likes":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_count":{"type":"integer","example":42}}}}},"comments":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_count":{"type":"integer","example":7}}}}},"shares":{"type":"object","properties":{"count":{"type":"integer","example":3}}},"attachments":{"type":"object","properties":{"data":{"type":"array","description":"Built from `mediaUrls`, `picture`, `full_picture` and `video`.","items":{"type":"object","properties":{"media":{"type":"object","description":"`{ image: { src } }` or `{ video: { src } }`."},"type":{"type":"string","description":"`photo`, `video`, `link` or `unknown` — guessed from the URL's file extension.","example":"photo"}}}}}},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"picture":{"type":"string"}}},"platform":{"type":"string","example":"instagram"},"sourceType":{"type":"string","example":"instagram-post"},"url":{"type":"string"},"views":{"type":"integer","example":0},"reach":{"type":"integer","example":0},"impressions":{"type":"integer","example":0}}}}}}}},"examples":{"failed":{"summary":"Platform not set up","value":{"success":false,"platform":"tiktok","action":"posts","error":"No sync configuration found for platform: tiktok","timestamp":1788000000000}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Refresh social data from a platform","description":"Calls the platform now for one kind of data, saves what comes back into the social store, and returns it in the unified feed shape.\n\nThe platform must be in the org's social sync settings (Instagram and WhatsApp can use the Facebook entry). The integration used is `configId`, else the one named in those settings, else `default`, and it must hold valid tokens. The account comes from `accountId`, else the settings (for Facebook and Instagram a saved `pageId/instagramId` pair is split into `pageId` and `instagramId`). **Every** query parameter is passed through to the platform call, so extra ones such as `limit` reach it; `feed` and `posts` default `limit` to 25.\n\n`action` picks the call: `feed` and `posts` → getFeed, `insights` and `analytics` → getInsights, `comments`, `messages`, `notifications`, `reactions`, `engagement`, `leads`, `ads`, `campaigns`, `followers`, `profile`; any other value calls `get<Action>` on the provider.\n\nEach returned item that has an `id` or `name` is saved as a `social_activity` with `platform`, `sourceType` (`<platform>-<action>`), `sourceId` (the item's id) and `timestamp` (the time of the refresh, unless the item has its own) added to the platform's fields. An item whose `sourceId` is already stored is skipped — the stored copy is not updated.\n\n#### Signature\n\n```http\nGET /sync/social-activities/refresh/{platform}/{action} (platform: string, action: string, configId?: string, accountId?: string, limit?: integer) -> Always HTTP 200 — check `success`. On success, the saved items in unified feed form; on failure, the reason.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A write on `GET`, and a live platform call that counts against its rate limits — do not put it behind a prefetchable link.\n- Failures (no sync settings, no configuration for the platform, integration missing or without valid tokens, the platform refusing the call) come back as `success: false`, not as an HTTP error.\n- Whatever the action, the response is shaped as a feed of posts — messages or insights are squeezed into the post layout.\n- Items saved here carry no `standardActivityType`, so the typed feeds (`/messages`, `/comments`, `/posts`, …) do not show them; they appear in `/platforms`, `/summary/platforms` and search.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/social-activities/posts`","tags":["CRM · Social"]}},"/crm/chat-message/get/{id}":{"get":{"operationId":"CRMController_getChatMessages","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Chat message id. Omit to list all.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Chat messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/chat-message/get/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Chat"],"summary":"Get chat messages","description":"The caller's chat messages. Supply `id` for one; omit the segment to list them all.\n\n#### Signature\n\n```http\nGET /crm/chat-message/get/{id} (id: string) -> Chat messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/chat-message/create`"}},"/crm/chat-message/delete/{id}":{"delete":{"operationId":"CRMController_deleteChatMessage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","in":"path","required":true,"description":"Chat message id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"customer does not match — The record belongs to a different customer than the caller.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"customer does not match","path":"/crm/chat-message/delete/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/chat-message/delete/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Chat"],"summary":"Delete a chat message","description":"Deletes one of the caller's chat messages.\n\n#### Signature\n\n```http\nDELETE /crm/chat-message/delete/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n| `400` | CUSTOMER_MISMATCH | customer does not match | The record belongs to a different customer than the caller. | You can only act on your own messages. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/chat-message/update`"}},"/crm/chat-message/create":{"post":{"operationId":"CRMController_createChatMessage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created chat message","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/chat-message/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Chat"],"summary":"Create a chat message","description":"Posts a new chat message on behalf of the caller.\n\n#### Signature\n\n```http\nPOST /crm/chat-message/create (body) -> The created chat message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/chat-message/update`","requestBody":{"description":"The message to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"data":{"type":"object","additionalProperties":true,"description":"Message fields."}}},"example":{"data":{"body":"Hello, I have a question about my order","channel":"chat"}}}}}}},"/crm/chat-message/update":{"post":{"operationId":"CRMController_updateChatMesssage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated chat message","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"customer does not match — The record belongs to a different customer than the caller.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"customer does not match","path":"/crm/chat-message/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/chat-message/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Chat"],"summary":"Update a chat message","description":"Updates an existing chat message belonging to the caller.\n\n#### Signature\n\n```http\nPOST /crm/chat-message/update (body) -> The updated chat message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n| `400` | CUSTOMER_MISMATCH | customer does not match | The record belongs to a different customer than the caller. | You can only act on your own messages. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/chat-message/delete/{id}`","requestBody":{"description":"The message to update. Include its `sk`.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"sk":{"type":"string","description":"The message to update."},"data":{"type":"object","additionalProperties":true}}},"example":{"sk":"66f1a2b3c4d5e6f708192a3b","data":{"body":"Corrected text"}}}}}}},"/crm/flexdata/get/{id}":{"get":{"operationId":"CRMController_getFlexData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"query","required":false,"in":"query","schema":{"type":"string"},"description":"Filter expression.","example":"type=preference"},{"name":"id","in":"path","required":true,"description":"Record id. Omit to query.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The matching flex data","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/flexdata/get/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM"],"summary":"Get flex data","description":"Reads flexible, schema-less records scoped to the caller. Supply `id` for one, or a `query` to filter.\n\n#### Signature\n\n```http\nGET /crm/flexdata/get/{id} (id: string, query?: string) -> The matching flex data\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`."}},"/crm/inbox/conversations":{"get":{"operationId":"CRMController_inboxDistinctConversations","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"groupBy","in":"query","required":false,"description":"How messages are grouped into threads.","schema":{"type":"string","default":"contact_channel"},"example":"contact_channel"}],"responses":{"200":{"description":"One entry per conversation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/conversations","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"List inbox conversations","description":"Groups the caller's messages into conversations and returns one entry per thread — the list view of an inbox.\n\n`groupBy` decides what counts as a conversation. The default, `contact_channel`, treats one contact on one channel as a thread, so the same person's email and SMS appear separately.\n\nCovers `email`, `sms` and `chat` only. Social DMs are in `social_activity` and do not appear here.\n\n#### Signature\n\n```http\nGET /crm/inbox/conversations (groupBy?: string) -> One entry per conversation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The `parties` value on each conversation is what the thread endpoints take.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/inbox/conversations/{parties}`\n- `GET /crm/inbox/messages`"}},"/crm/inbox/conversations/{parties}":{"get":{"operationId":"CRMController_inboxGetConversationMessages","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"parties","required":true,"in":"path","schema":{"type":"string"},"description":"Conversation key identifying the participants, as returned by `GET /crm/inbox/conversations`.","example":"ada@example.com|support@acme.com"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one channel — `email`, `sms`, `chat`.","example":"email"}],"responses":{"200":{"description":"The thread's messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A message (`DataType.message`) — email, SMS or chat.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","description":"How it travelled — `email`, `sms`, `chat`.","example":"email"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"from":{"type":"string","example":"ada@example.com"},"to":{"type":"string","example":"support@acme.com"},"subject":{"type":"string","example":"Where is my order?"},"body":{"type":"string"},"status":{"type":"string","description":"Read state or delivery state, depending on direction.","example":"unread"},"parties":{"type":"string","description":"Conversation key — the participants, used to group a thread.","example":"ada@example.com|support@acme.com"}}}}}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/conversations/{parties}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Get messages in a conversation","description":"Every message in one thread, in order. Narrow with `channel` when a contact has been reached on more than one.\n\n#### Signature\n\n```http\nGET /crm/inbox/conversations/{parties} (parties: string, channel?: string) -> The thread's messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/inbox/thread/{parties}`"}},"/crm/inbox/messages":{"get":{"operationId":"CRMController_inboxGetMessages","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"l","required":false,"in":"query","schema":{"type":"string"},"description":"Cursor for keyset pagination: the sort value of the last record from the previous page. Pass it to continue past that record instead of skipping with `p`, which stays fast at any depth."},{"name":"en","required":false,"in":"query","schema":{"type":"boolean"},"description":"Resolve linked records inline instead of returning bare references.","example":true},{"name":"p","in":"query","required":false,"description":"Page number, 1-based.","schema":{"type":"integer","default":1},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size — how many records to return. Large values are slower; prefer cursor paging via `l` for deep scans.","schema":{"type":"integer","default":50},"example":50},{"name":"s","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string","default":"createdate"},"example":"createdate"},{"name":"st","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"}],"responses":{"200":{"description":"A page of messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A message (`DataType.message`) — email, SMS or chat.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","description":"How it travelled — `email`, `sms`, `chat`.","example":"email"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"from":{"type":"string","example":"ada@example.com"},"to":{"type":"string","example":"support@acme.com"},"subject":{"type":"string","example":"Where is my order?"},"body":{"type":"string"},"status":{"type":"string","description":"Read state or delivery state, depending on direction.","example":"unread"},"parties":{"type":"string","description":"Conversation key — the participants, used to group a thread.","example":"ada@example.com|support@acme.com"}}}}}},"total":{"type":"integer","example":214}}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/messages","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"List inbox messages","description":"A flat, paged list of the caller's messages, newest first by default. Use the conversation endpoints when you want them threaded.\n\n#### Signature\n\n```http\nGET /crm/inbox/messages (p?: integer, ps?: integer, l?: string, s?: string, st?: string, en?: boolean) -> A page of messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/inbox/messages/{id}`"}},"/crm/inbox/whatsapp-window":{"get":{"operationId":"CRMController_inboxWhatsAppWindow","summary":"Whether WhatsApp free text may go from a business number to a customer now (24-hour window)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Business number, +E164","schema":{"type":"string"}},{"name":"to","required":true,"in":"query","description":"Customer number, +E164","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM"]}},"/crm/inbox/messages/{id}":{"get":{"operationId":"CRMController_inboxGetMessage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Message id.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"en","required":false,"in":"query","schema":{"type":"boolean"},"description":"Resolve linked records inline instead of returning bare references.","example":true}],"responses":{"200":{"description":"The message","content":{"application/json":{"schema":{"type":"object","description":"A message (`DataType.message`) — email, SMS or chat.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","description":"How it travelled — `email`, `sms`, `chat`.","example":"email"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"from":{"type":"string","example":"ada@example.com"},"to":{"type":"string","example":"support@acme.com"},"subject":{"type":"string","example":"Where is my order?"},"body":{"type":"string"},"status":{"type":"string","description":"Read state or delivery state, depending on direction.","example":"unread"},"parties":{"type":"string","description":"Conversation key — the participants, used to group a thread.","example":"ada@example.com|support@acme.com"}}}}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/messages/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"message not found — No message has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"message not found","path":"/crm/inbox/messages/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Get an inbox message","description":"Fetches one message. Pass `en=true` to resolve its linked records — the contact, the related order — inline.\n\n#### Signature\n\n```http\nGET /crm/inbox/messages/{id} (id: string, en?: boolean) -> The message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n| `404` | MESSAGE_NOT_FOUND | message not found | No message has that id. | Check the id with `GET /crm/inbox/messages`. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/inbox/update-status/{messageId}/{status}`"}},"/crm/inbox/delete/{id}":{"delete":{"operationId":"CRMController_inboxDeleteMessage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","in":"path","required":true,"description":"Message id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"customer does not match — The record belongs to a different customer than the caller.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"customer does not match","path":"/crm/inbox/delete/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/delete/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"message not found — No message has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"message not found","path":"/crm/inbox/delete/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Delete an inbox message","description":"Deletes one message belonging to the caller. Deleting a whole thread is a separate endpoint.\n\n#### Signature\n\n```http\nDELETE /crm/inbox/delete/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n| `400` | CUSTOMER_MISMATCH | customer does not match | The record belongs to a different customer than the caller. | You can only act on your own messages. |\n| `404` | MESSAGE_NOT_FOUND | message not found | No message has that id. | Check the id with `GET /crm/inbox/messages`. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/inbox/thread/{parties}`"}},"/crm/inbox/thread/{parties}":{"delete":{"operationId":"CRMController_inboxDeleteThread","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"channel","required":false,"in":"query","schema":{"type":"string"},"description":"Restrict to one channel — `email`, `sms`, `chat`.","example":"email"},{"name":"parties","in":"path","required":true,"description":"Conversation key identifying the participants, as returned by `GET /crm/inbox/conversations`.","schema":{"type":"string"},"example":"ada@example.com|support@acme.com"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/thread/{parties}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Delete a conversation","description":"Deletes every message in a thread. Pass `channel` to remove only one channel's messages, leaving the contact's other conversations intact.\n\nThis removes the whole history with that contact — there is no undo.\n\n#### Signature\n\n```http\nDELETE /crm/inbox/thread/{parties} (parties: string, channel?: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Omitting `channel` deletes the thread across every channel with that contact.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/inbox/delete/{id}`"}},"/crm/inbox/update":{"post":{"operationId":"CRMController_inboxUpdateMessage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"send","in":"query","required":false,"description":"`true` dispatches the message as well as saving it.","schema":{"type":"boolean","default":false},"example":true}],"responses":{"201":{"description":"The saved message","content":{"application/json":{"schema":{"type":"object","description":"A message (`DataType.message`) — email, SMS or chat.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","description":"How it travelled — `email`, `sms`, `chat`.","example":"email"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"from":{"type":"string","example":"ada@example.com"},"to":{"type":"string","example":"support@acme.com"},"subject":{"type":"string","example":"Where is my order?"},"body":{"type":"string"},"status":{"type":"string","description":"Read state or delivery state, depending on direction.","example":"unread"},"parties":{"type":"string","description":"Conversation key — the participants, used to group a thread.","example":"ada@example.com|support@acme.com"}}}}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Message was not saved — an identical message already exists. Change the message, or open the existing one to send it. — An identical payload has already been saved — typically a double-clicked send.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Message was not saved — an identical message already exists. Change the message, or open the existing one to send it.","path":"/crm/inbox/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Update or send a message","description":"Saves a message, and **sends it when `send=true`** — the same endpoint covers saving a draft and dispatching it.\n\nA duplicate guard rejects an identical payload posted twice with a `409`, so a double-clicked send does not mail the customer twice. The error says plainly what happened rather than surfacing as a generic failure.\n\n#### Signature\n\n```http\nPOST /crm/inbox/update (send?: boolean, body) -> The saved message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Sending is driven by the `send` query parameter, not the body — it is easy to save when you meant to send.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n| `409` | DUPLICATE_MESSAGE | Message was not saved — an identical message already exists. Change the message, or open the existing one to send it. | An identical payload has already been saved — typically a double-clicked send. | Treat this as success for a retry. The message already exists; open it rather than resending. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/send-template`","requestBody":{"description":"The message to save or send.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"sk":{"type":"string","description":"Existing message to update. Omit to create."},"data":{"type":"object","additionalProperties":true,"description":"Message fields — channel, to, subject, body."}}},"examples":{"draft":{"summary":"Save a draft","value":{"data":{"channel":"email","to":"ada@example.com","subject":"Your order","body":"Hello…"}}},"send":{"summary":"Save and send","description":"Set `?send=true` on the query string.","value":{"data":{"channel":"email","to":"ada@example.com","subject":"Your order","body":"Hello…"}}}}}}}}},"/crm/inbox/update-status/{messageId}/{status}":{"post":{"operationId":"CRMController_inboxUpdateMessageStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"messageId","in":"path","required":true,"description":"Message id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"status","in":"path","required":true,"description":"New status, e.g. `read`, `unread`, `archived`.","schema":{"type":"string"},"example":"read"}],"responses":{"201":{"description":"The updated message","content":{"application/json":{"schema":{"type":"object","description":"A message (`DataType.message`) — email, SMS or chat.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","description":"How it travelled — `email`, `sms`, `chat`.","example":"email"},"direction":{"type":"string","enum":["inbound","outbound"],"example":"inbound"},"from":{"type":"string","example":"ada@example.com"},"to":{"type":"string","example":"support@acme.com"},"subject":{"type":"string","example":"Where is my order?"},"body":{"type":"string"},"status":{"type":"string","description":"Read state or delivery state, depending on direction.","example":"unread"},"parties":{"type":"string","description":"Conversation key — the participants, used to group a thread.","example":"ada@example.com|support@acme.com"}}}}}}}},"400":{"description":"customer does not match — The record belongs to a different customer than the caller.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"customer does not match","path":"/crm/inbox/update-status/{messageId}/{status}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/update-status/{messageId}/{status}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"message not found — No message has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"message not found","path":"/crm/inbox/update-status/{messageId}/{status}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Set a message status","description":"Changes a message's status — marking it read, archived or handled. Both values are path segments rather than a body.\n\n#### Signature\n\n```http\nPOST /crm/inbox/update-status/{messageId}/{status} (messageId: string, status: string) -> The updated message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n| `400` | CUSTOMER_MISMATCH | customer does not match | The record belongs to a different customer than the caller. | You can only act on your own messages. |\n| `404` | MESSAGE_NOT_FOUND | message not found | No message has that id. | Check the id with `GET /crm/inbox/messages`. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/inbox/messages/{id}`"}},"/crm/send-template":{"post":{"operationId":"CRMController_sendTemplate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Queued for sending: `{ queued, template, to }`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Templates"],"summary":"Send a templated message","description":"Renders a message template and sends it. This is the path for transactional mail that should look like every other message from the org — the template chain resolves org override, then shared-org, then the factory default.\n\nUse `POST /crm/test-template` first to see the rendered output without sending.\n\n#### Signature\n\n```http\nPOST /crm/send-template (body) -> Queued for sending: `{ queued, template, to }`.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Sends on every call — there is no duplicate guard here, unlike `POST /crm/inbox/update`.\n- Values in `data` render as `{{data.<key>}}`. A template whose subject or body would render with an empty placeholder is not sent: 400 with `reason: \"UNRESOLVED_PLACEHOLDERS\"`, `unresolved` (the empty placeholders) and `available` (the data paths that were supplied).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/test-template`","requestBody":{"description":"Which template, to whom, with what data.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"template":{"type":"string","description":"Template name.","example":"order-confirmation"},"to":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Recipients.","example":"ada@example.com"},"channel":{"type":"string","enum":["email","sms"],"example":"email"},"data":{"type":"object","additionalProperties":true,"description":"Values interpolated into the template."}}},"example":{"template":"order-confirmation","to":"ada@example.com","channel":"email","data":{"orderNumber":"A7K2M9QX4"}}}}}}},"/crm/test-template":{"post":{"operationId":"CRMController_testTemplate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The rendered template","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Templates"],"summary":"Test a message template","description":"Renders a template with sample data and returns the result **without sending it**. The safe way to check wording and interpolation before mailing customers.\n\n#### Signature\n\n```http\nPOST /crm/test-template (body) -> The rendered template\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Nothing is sent and nothing is stored.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/send-template`","requestBody":{"description":"The template and the data to render it with.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"template":{"type":"string","example":"order-confirmation"},"data":{"type":"object","additionalProperties":true,"description":"Values to interpolate."}}},"example":{"template":"order-confirmation","data":{"orderNumber":"A7K2M9QX4"}}}}}}},"/crm/inbox/notifications/{id}":{"get":{"operationId":"CRMController_inboxGetNotifications","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Notification id. Omit to list all.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"en","required":true,"in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Notifications","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/notifications/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Get inbox notifications","description":"The caller's notifications. Supply `id` for one; omit the segment to list them all.\n\n#### Signature\n\n```http\nGET /crm/inbox/notifications/{id} (id: string) -> Notifications\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/inbox/save-push-token`"}},"/crm/inbox/save-push-token":{"post":{"operationId":"CRMController_inboxSaveToken","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The saved token record","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"customer is required — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"customer is required","path":"/crm/inbox/save-push-token","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Inbox"],"summary":"Save a push notification token","description":"Registers a device token so the caller can receive push notifications. Call it on every app launch — tokens are rotated by the platforms and a stale one silently stops delivering.\n\n#### Signature\n\n```http\nPOST /crm/inbox/save-push-token (body) -> The saved token record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | customer is required | No signed-in customer or user could be resolved. | Sign in — these routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/inbox/notifications/{id}`","requestBody":{"description":"The device token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token":{"type":"string","description":"Device push token.","example":"fcm_dGhpcyBpcyBhIHRva2Vu"},"platform":{"type":"string","enum":["ios","android","web"],"example":"ios"}}},"example":{"token":"fcm_dGhpcyBpcyBhIHRva2Vu","platform":"ios"}}}}}},"/crm/place/near-by":{"get":{"operationId":"CRMController_getNearbyPlaces","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"lat","required":true,"in":"query","schema":{"type":"number"},"description":"Latitude.","example":40.7128},{"name":"lng","required":true,"in":"query","schema":{"type":"number"},"description":"Longitude.","example":-74.006},{"name":"radius","required":true,"in":"query","schema":{"type":"number"},"description":"Search radius in metres.","example":1500},{"name":"type","required":true,"in":"query","schema":{"type":"string"},"description":"Place type to search for.","example":"restaurant"}],"responses":{"200":{"description":"Nearby places","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM"],"summary":"Find nearby places","description":"Looks up places near a point, backed by a maps provider.\n\n**This route reads no `orgid` header** and is not scoped to an organization — it is a plain proxy to the places lookup.\n\n#### Signature\n\n```http\nGET /crm/place/near-by (lat?: number, lng?: number, radius?: number, type?: string) -> Nearby places\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Backed by a billable maps provider — do not call it per keystroke.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/send-invitation":{"post":{"operationId":"CRMController_sendInvitation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The invitation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Templates"],"summary":"Send an invitation","description":"Sends an invitation to join the organization. The invitee receives a link to accept.\n\n#### Signature\n\n```http\nPOST /crm/send-invitation (body) -> The invitation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Sends every time — re-inviting an existing member mails them again.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"description":"Who to invite.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"role":{"type":"string","description":"Role to grant on acceptance.","example":"User"},"message":{"type":"string","description":"Personal note included in the invitation."}}},"example":{"email":"ada@example.com","role":"User"}}}}}},"/crm/workflows/benefit-application":{"post":{"operationId":"CRMController_createBenefitWorkflow","summary":"Create a benefit application workflow","description":"Scaffolds a standard benefit-application workflow from the built-in template. Customise its stages afterwards through the workflow API.\n\n#### Signature\n\n```http\nPOST /crm/workflows/benefit-application (body) -> The created workflow\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/workflows/benefit-application/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The created workflow","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Benefits"],"requestBody":{"description":"Workflow name.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique workflow name. Defaults to the standard benefit-application name.","example":"benefit-application"}}},"example":{"name":"benefit-application"}}}}}},"/crm/workflows/benefit-application/{name}":{"get":{"operationId":"CRMController_getBenefitWorkflow","summary":"Get the benefit application workflow","description":"Fetches a benefit-application workflow by name, or omit the segment to find it by the datatype it is bound to — the reliable way to ask which pipeline benefit applications run on.\n\n#### Signature\n\n```http\nGET /crm/workflows/benefit-application/{name} (name: string) -> The workflow definition\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/workflows/benefit-application`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Workflow name. Omit to find by owner datatype.","schema":{"type":"string"},"example":"benefit-application"}],"responses":{"200":{"description":"The workflow definition","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Benefits"]}},"/crm/benefit-enrollments":{"get":{"operationId":"CRMController_getEnrollments","summary":"List benefit enrolments","description":"Lists benefit enrolments with optional filters. The operator queue for reviewing applications — filter on `status` for those awaiting a decision.\n\n#### Signature\n\n```http\nGET /crm/benefit-enrollments (customerId?: string, benefit?: string, status?: string) -> Matching enrolments\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/benefit-enrollments/{enrollmentId}/action`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"customerId","required":false,"in":"query","schema":{"type":"string"},"description":"Filter to one customer.","example":"cus_4821"},{"name":"benefit","required":false,"in":"query","schema":{"type":"string"},"description":"Filter to one benefit.","example":"health-plan"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by enrolment status.","example":"pending"},{"name":"q","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching enrolments","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Benefits"]},"post":{"operationId":"CRMController_enrollCustomer","summary":"Enrol a customer in a benefit","description":"Staff enrolling a customer. Runs the same checks as the customer's own application (already holds it, already pending, agreement), puts an application that needs approval on the benefit applications board, and sends the customer the submitted notice.\n\n#### Signature\n\n```http\nPOST /crm/benefit-enrollments (body) -> The enrolment created\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/benefit-enrollments/{enrollmentId}/action`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The enrolment created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Benefits"],"requestBody":{"description":"Who and what","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"},"benefit":{"type":"string"},"notes":{"type":"string"},"agreementAccepted":{"type":"boolean"}}},"example":{"customerId":"cus_4821","benefit":"Studio Club"}}}}}},"/crm/benefit-enrollments/{enrollmentId}/action":{"post":{"operationId":"CRMController_updateEnrollmentStatus","summary":"Review, approve or reject an enrolment","description":"Acts on a benefit enrolment. `action` decides what happens: `review` marks it as being examined, `approve` accepts it, `reject` declines it.\n\nNotes are recorded against the decision and are what an applicant is shown when rejected, so write them for that audience.\n\n#### Signature\n\n```http\nPOST /crm/benefit-enrollments/{enrollmentId}/action (enrollmentId: string, body) -> The updated enrolment\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/benefit-enrollments/{enrollmentId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"enrollmentId","required":true,"in":"path","description":"Enrolment id.","schema":{"type":"string"},"example":"ENR-4821"}],"responses":{"201":{"description":"The updated enrolment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Benefits"],"requestBody":{"description":"The decision.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["review","approve","reject"],"example":"approve"},"notes":{"type":"string","description":"Recorded with the decision.","example":"Eligibility confirmed against payroll records"}}},"examples":{"approve":{"summary":"Approve","value":{"action":"approve","notes":"Eligibility confirmed"}},"reject":{"summary":"Reject with a reason","value":{"action":"reject","notes":"Applicant does not meet the service-length requirement"}}}}}}}},"/crm/benefit-enrollments/{enrollmentId}":{"delete":{"operationId":"CRMController_deleteEnrollment","summary":"Delete a benefit enrolment","description":"Deletes an enrolment **and all its associated data**, including the submitted application. This is a hard delete with nothing to restore — reject the enrolment instead when you need to keep the record of what was applied for.\n\n#### Signature\n\n```http\nDELETE /crm/benefit-enrollments/{enrollmentId} (enrollmentId: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Removes associated application data too. Prefer `reject` where an audit trail matters.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/benefit-enrollments/{enrollmentId}/action`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"enrollmentId","required":true,"in":"path","description":"Enrolment id.","schema":{"type":"string"},"example":"ENR-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Benefits"]}},"/crm/customer-data/{customerId}":{"get":{"operationId":"CRMController_getCustomerData","summary":"Get complete customer data","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"customerId","required":true,"in":"path","description":"Customer `sk`, email address, or username.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"The customer and every linked record","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Customer not found — The identifier does not resolve to a customer.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Customer not found","path":"/crm/customer-data/{customerId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Customers"],"description":"Returns a customer together with **every linked record** — addresses, phone numbers, and the other sub-records attached to them — in one response.\n\nThe identifier is flexible: a customer `sk`, an email address or a username all resolve, so a support tool can look someone up by whatever it has.\n\n#### Signature\n\n```http\nGET /crm/customer-data/{customerId} (customerId: string) -> The customer and every linked record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CUSTOMER_NOT_FOUND | Customer not found | The identifier does not resolve to a customer. | Try the email address or `sk` — all three forms are accepted. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/customer-data/{customerId}`"},"post":{"operationId":"CRMController_addCustomerData","summary":"Add linked data to a customer","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"customerId","required":true,"in":"path","description":"Customer `sk`, email address, or username.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"201":{"description":"The created linked record","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Customer not found — The identifier does not resolve.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Customer not found","path":"/crm/customer-data/{customerId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Customers"],"description":"Attaches a sub-record to a customer — an address, a phone number, or any other linked datatype. `datatype` names what kind of record it is and `data` carries its fields.\n\nAs with the read, the customer can be identified by `sk`, email or username.\n\n#### Signature\n\n```http\nPOST /crm/customer-data/{customerId} (customerId: string, body) -> The created linked record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Notes\n\n- `datatype` is not validated against a list — an unrecognised value creates a record nothing else reads.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | CUSTOMER_NOT_FOUND | Customer not found | The identifier does not resolve. | Check the identifier. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/customer-data/{customerId}`","requestBody":{"description":"The linked record to add.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["datatype","data"],"properties":{"datatype":{"type":"string","description":"What kind of record this is.","example":"address"},"data":{"type":"object","additionalProperties":true,"description":"The record's fields."}}},"examples":{"address":{"summary":"Add an address","value":{"datatype":"address","data":{"line1":"12 Ada Way","city":"London","postcode":"E1 6AN","country":"GB"}}},"phone":{"summary":"Add a phone number","value":{"datatype":"phone","data":{"number":"+442071234567","label":"mobile"}}}}}}}}},"/crm/customer-activity/{email}/timeline":{"get":{"operationId":"CustomerActivityController_getTimeline","summary":"Get a customer activity timeline","description":"Everything a customer has done, in order — the behavioural history behind their record.\n\n#### Signature\n\n```http\nGET /crm/customer-activity/{email}/timeline (email: string, types?: string, from?: string, to?: string, limit?: string, page?: string) -> The activity timeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/customer-activity/{email}/summary`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Customer email.","example":"ada@example.com"},{"name":"types","required":false,"in":"query","description":"Comma-separated activity types.","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"ISO date — start of the range.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"ISO date — end of the range.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"string"},"description":"Maximum rows."},{"name":"page","required":false,"in":"query","schema":{"type":"string"},"description":"Page number (1-based)."}],"responses":{"200":{"description":"The activity timeline","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Activity"]}},"/crm/customer-activity/visitor/{visitorId}/timeline":{"get":{"operationId":"CustomerActivityController_getVisitorTimeline","summary":"Get an anonymous visitor timeline","description":"Activity for a visitor who has not identified themselves yet, tracked by visitor id. Calling `identify` links this history to a real customer.\n\n#### Signature\n\n```http\nGET /crm/customer-activity/visitor/{visitorId}/timeline (visitorId: string, limit?: string, page?: string) -> The visitor timeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/customer-activity/identify`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"visitorId","required":true,"in":"path","schema":{"type":"string"},"description":"Anonymous visitor id.","example":"vis_9k2m4h1p7q"},{"name":"limit","required":false,"in":"query","schema":{"type":"string"},"description":"Maximum rows."},{"name":"page","required":false,"in":"query","schema":{"type":"string"},"description":"Page number (1-based)."}],"responses":{"200":{"description":"The visitor timeline","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Activity"]}},"/crm/customer-activity/{email}/summary":{"get":{"operationId":"CustomerActivityController_getSummary","summary":"Get a customer activity summary","description":"Aggregate view of a customer's behaviour rather than the raw event list — visit counts, recency and engagement.\n\n#### Signature\n\n```http\nGET /crm/customer-activity/{email}/summary (email: string) -> The activity summary\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/customer-activity/{email}/timeline`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Customer email.","example":"ada@example.com"}],"responses":{"200":{"description":"The activity summary","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Activity"]}},"/crm/customer-activity/identify":{"post":{"operationId":"CustomerActivityController_identifyVisitor","summary":"Identify a visitor","description":"Links an anonymous visitor's history to a known customer — what happens at sign-up or sign-in, so the browsing that led to the account is not lost.\n\nCall it as soon as identity is known; activity recorded before it stays attached to the visitor id.\n\n#### Signature\n\n```http\nPOST /crm/customer-activity/identify (body) -> The identification result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/customer-activity/record`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The visitor and who they turned out to be.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"visitorId":{"type":"string","example":"vis_9k2m4h1p7q"},"email":{"type":"string","example":"ada@example.com"}}},"example":{"visitorId":"vis_9k2m4h1p7q","email":"ada@example.com"}}}},"responses":{"201":{"description":"The identification result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Activity"]}},"/crm/customer-activity/record":{"post":{"operationId":"CustomerActivityController_recordEvent","summary":"Record customer activity","description":"Records an activity event against a customer or visitor — a page view, a search, a product view. The write behind the timeline.\n\n#### Signature\n\n```http\nPOST /crm/customer-activity/record (body) -> The recorded event\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- High-volume by nature — batch where you can rather than calling per interaction.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/customer-activity/erase`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The recorded event","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Activity"],"requestBody":{"description":"The event to record.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"visitorId":{"type":"string"},"email":{"type":"string"},"type":{"type":"string","example":"product_view"},"data":{"type":"object","additionalProperties":true}}},"example":{"visitorId":"vis_9k2m4h1p7q","type":"product_view","data":{"sku":"DRK-COLA-330"}}}}}}},"/crm/customer-activity/erase":{"post":{"operationId":"CustomerActivityController_eraseCustomer","summary":"Erase customer activity","description":"Deletes a customer's recorded activity — the data-subject erasure path for a deletion request.\n\nIrreversible by design: the point is that the history genuinely goes.\n\n#### Signature\n\n```http\nPOST /crm/customer-activity/erase (body) -> The erasure result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Irreversible. This erases activity only — the customer record itself is deleted through the user API.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/customer-activity/{email}/timeline`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Whose activity to erase.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"visitorId":{"type":"string"}}},"example":{"email":"ada@example.com"}}}},"responses":{"201":{"description":"The erasure result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Activity"]}},"/crm/customer-360":{"get":{"operationId":"Customer360Controller_get","summary":"Everything recent about a phone number or email","description":"Who it is (customers, leads) and their recent calls, messages, orders, invoices, tickets, reservations, AI employee work and website activity — computed on the server, ready to show. A phone number matches on its last 10 digits.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"phone","required":false,"in":"query","schema":{"type":"string"}},{"name":"email","required":false,"in":"query","schema":{"type":"string"}},{"name":"name","required":false,"in":"query","description":"A name: returns { matches } — the customers and leads to pick from.","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Customer 360"]}},"/crm/customer-groups/of/{customerId}":{"get":{"operationId":"CustomerGroupsController_of","summary":"Every customer group, and whether (and how) this contact is in it: listed, named on the record, or by a smart group's rules — members first","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM - Customer groups"]}},"/crm/customer-groups/match":{"post":{"operationId":"CustomerGroupsController_match","summary":"The contacts a group holds right now, a page at a time: a saved group (groupId) or one being written (group: groupType, addRules, addRulesMatch, query, contacts, name) so rules can be tried before saving. q narrows by name, email, company or phone; filter adds plain data.* values; sort (a contact field, createdate or modifydate) and sortType (1 or -1) order the pages, newest first when left out. The answer carries `query`: the membership as the query the database ran.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Customer groups"]}},"/crm/customer-groups/counts":{"get":{"operationId":"CustomerGroupsController_counts","summary":"How many contacts each group holds right now: { [groupId]: count }","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM - Customer groups"]}},"/crm/customer-groups/members":{"post":{"operationId":"CustomerGroupsController_members","summary":"Put contacts in groups (add: group ids) and take them out of others (remove: group ids). Keeps the group's list and each contact's Customer Groups field in step. Smart groups are refused (their rules decide).","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Customer groups"]}},"/crm/contacts/bulk":{"post":{"operationId":"ContactsBulkController_run","summary":"One action on many contacts: add_tags / remove_tags (tags), set_status (status: a lead status), delete. Each contact is reported done or why not. Groups: crm/customer-groups/members.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Contacts"]}},"/crm/alert/sms/{id}":{"get":{"operationId":"CRMAlertController_setSMSAlert","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","in":"path","required":true,"description":"Alert id. Omit to list.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"SMS alerts","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get SMS alerts","description":"Fetches one SMS alert configuration by id, or lists them when the segment is omitted.\n\n#### Signature\n\n```http\nGET /crm/alert/sms/{id} (id: string) -> SMS alerts\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/alert/sms`","tags":["CRM · Alerts"]}},"/crm/alert/sms":{"post":{"operationId":"CRMAlertController_sendSMSAlert","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created alert","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create an SMS alert","description":"Creates an SMS alert — a message triggered by a condition rather than sent manually.\n\n#### Signature\n\n```http\nPOST /crm/alert/sms (body) -> The created alert\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- SMS costs money per message — check the trigger cannot fire in a loop.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/alert/sms/{id}`","tags":["CRM · Alerts"],"requestBody":{"description":"The alert to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"data":{"name":"Low stock alert","to":"+15551234567","trigger":"inventory.low"}}}}}}},"/crm/marketing/campaign-manager/list":{"post":{"operationId":"MarketingController_managerList","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ summary, data: Campaign[], total, page, pageSize, hasNext }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List campaigns (Campaign Manager)","description":"Totals across **every** campaign in the org (`summary`: counts per status, budget, spent and the other metrics, tracked/untracked counts, `statusOptions`) plus one page of enriched campaign cards. Each card carries its computed `status`/`statusLabel`, `channel` (ads | email | offline), `metrics` gathered from every source that reports on it (ad platform insights, linked social posts, the linked email broadcast, checkout attribution, manually entered actuals), `tracking` (which sources, or \"Not tracked\"), `failure` for a failed launch, `adsReadiness`, `blockedActions` and `testLaunch`. `status` and `search` (name, description, type, platforms) filter the page only; totals never change with them.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/list (body) -> { summary, data: Campaign[], total, page, pageSize, hasNext }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","default":1},"pageSize":{"type":"integer","default":24,"maximum":100},"status":{"type":"string","enum":["all","draft","scheduled","active","paused","completed","failed","cancelled"]},"search":{"type":"string"}}},"example":{"status":"active","pageSize":24}}}}}},"/crm/marketing/campaign-manager/social-feeds":{"get":{"operationId":"MarketingController_managerSocialFeeds","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"Posts per platform, 1–50 (default 10)."}],"responses":{"200":{"description":"Platform feeds","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Social feeds by platform","description":"One column per social network: its connection `state` (connected | needs_reconnect | not_connected | no_account), a `message` and next `action` when it needs attention, and the latest synced posts.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaign-manager/social-feeds (limit?: integer) -> Platform feeds\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/create":{"post":{"operationId":"MarketingController_managerCreate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The new campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A campaign needs a name — `name` missing or blank (create, or an update that sends it).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A campaign needs a name","path":"/crm/marketing/campaign-manager/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"This campaign was just created — open it from Campaigns to keep editing it — The same create was sent twice in a row (double click / resend).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This campaign was just created — open it from Campaigns to keep editing it","path":"/crm/marketing/campaign-manager/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a campaign","description":"Creates a campaign in `draft`. `name` and `type` are required; `type` is one of `email`, `social`, `ppc`, `display`, `video`, `radio`, `billboard`, `newspaper`, `magazine`, `tv`, `website`. Editable fields: name, description, type, objective, budget (≥ 0), budgetType (daily | lifetime), dailyBudget, platforms, landingPage, utmParameters, tags, notes, location, timeSlots, frequency, duration, audienceIds, targetAudience, audiences, timezone, broadcastId (email campaigns), creatives and the Smart Builder state. The ad account is never set here — see `POST …/{id}/ad-account`.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/create (body) -> The new campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAME_REQUIRED | A campaign needs a name | `name` missing or blank (create, or an update that sends it). | — |\n| `409` | DUPLICATE_CREATE | This campaign was just created — open it from Campaigns to keep editing it | The same create was sent twice in a row (double click / resend). | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Fall sale — Meta","type":"social","platforms":["facebook","instagram"],"budget":500,"budgetType":"lifetime"}}}}}},"/crm/marketing/campaign-manager/social-draft":{"post":{"operationId":"MarketingController_managerSocialDraft","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ id, platform, status: \"draft\", text, campaignId, openIn }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Platform must be one of: facebook, instagram, linkedin, twitter, tiktok, pinterest — Unknown platform.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Platform must be one of: facebook, instagram, linkedin, twitter, tiktok, pinterest","path":"/crm/marketing/campaign-manager/social-draft","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/social-draft","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Draft a social post for a campaign","description":"Creates a draft social post (a `message` with status `draft`, never sent) for one platform — `facebook`, `instagram`, `linkedin`, `twitter`, `tiktok`, `pinterest` — linked to the campaign when `campaignId` is given. It is reviewed and published from Social › Posts.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/social-draft (body) -> { id, platform, status: \"draft\", text, campaignId, openIn }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | BAD_PLATFORM | Platform must be one of: facebook, instagram, linkedin, twitter, tiktok, pinterest | Unknown platform. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"platform":{"type":"string","enum":["facebook","instagram","linkedin","twitter","tiktok","pinterest"]},"text":{"type":"string"},"imageUrl":{"type":"string"}}},"example":{"campaignId":"66f1a2b3c4d5e6f708192a3b","platform":"instagram","text":"Fall sale starts Friday 🍂"}}}}}},"/crm/marketing/campaign-manager/ads-readiness":{"get":{"operationId":"MarketingController_managerAdsReadiness","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"campaign","required":false,"in":"query","schema":{"type":"string"},"description":"Narrow to this campaign: only its ad platforms, with its own ad account overrides applied.","example":"68413e97a20417481150d5ed"},{"name":"refresh","required":false,"in":"query","schema":{"type":"string"},"description":"`1` to skip the short cache.","example":"1"}],"responses":{"200":{"description":"`{ checkedAt, campaign, applies, ready, blockedReason, summary: { total, ready, attention }, platforms: [{ platform, label, connection, ready, status, adAccount, issues: [{ code, message, severity, fix }], supportsTestLaunch, guide }] }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ready":false,"blockedReason":"Facebook, Instagram — No ad account is chosen for Facebook & Instagram (Meta).","summary":{"total":2,"ready":0,"attention":2},"platforms":[{"platform":"facebook","label":"Facebook","connection":"meta","ready":false,"status":"needs_attention","adAccount":null,"issues":[{"code":"no_ad_account_selected","severity":"blocker","message":"No ad account is chosen for Facebook & Instagram (Meta).","fix":{"label":"Choose ad account","target":{"app":"/social-manager","tab":"accounts","section":"meta"}}}]}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Check whether each ad platform can publish ads","description":"For every ad platform (`facebook`, `instagram`, `google`, `linkedin`, `tiktok`, `pinterest`, `twitter`), or for one campaign when `campaign` is given, the answer is **ready** or the list of issues in the way. Each issue has a `fix: { label, target }`, where `target` is either an in-app screen (`{ app: \"/social-manager\", tab: \"accounts\", section }`, the platform's \"Ad account\" settings) or a page on the platform itself (`{ url }`).\n\nWhat is checked, read-only on the platforms (nothing is created and nothing is spent):\n- the connection exists, is turned on, and has a token that has not expired;\n- the token carries the ads permission (Meta `ads_management` + `ads_read` from `/me/permissions`; Google `adwords` scope; LinkedIn `rw_ads`; Pinterest `ads:read`). TikTok needs a TikTok for Business (Marketing API) advertiser authorization, and X needs X Ads API access; posting-only connections are reported as `ads_api_unavailable`;\n- an ad account is chosen: the campaign's own override, otherwise the connection default (`adAccountIds` on the connection);\n- that account is one the login can use and is fully ready: active, with a payment method where the API reports it (Meta `account_status`, `disable_reason`, `funding_source_details`; Google customer status and an approved billing setup);\n- the identity ads run as: a Facebook Page for Facebook, an Instagram professional account linked to a Page for Instagram.\n\nResults are cached per organization for about a minute; `refresh=1` checks again.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaign-manager/ads-readiness (campaign?: string, refresh?: string) -> `{ checkedAt, campaign, applies, ready, blockedReason, summary: { total, ready, attention }, platforms: [{ platform, label, connection, ready, status, adAccount, issues: [{ code, message, severity, fix }], supportsTestLaunch, guide }] }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Issue codes: `not_connected`, `connection_inactive`, `token_expired`, `token_invalid`, `missing_ads_permission`, `ads_api_unavailable`, `no_ad_account_selected`, `no_usable_ad_account`, `ad_account_not_found`, `ad_account_not_ready`, `no_page`, `no_instagram_account`, `platform_integration_outdated`, `check_failed`.\n- Also mounted as `GET /crm/marketing/campaign-manager/ads-readiness/{campaignId}`.\n- Campaign cards from `POST /crm/marketing/campaign-manager/list` carry the same result as `adsReadiness`, plus `blockedActions` (`launch`, `retry`, `schedule` → the reason) while a targeted platform is not ready.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaign-manager/ad-accounts`\n- `POST /crm/marketing/campaign-manager/{id}/launch`","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/ads-readiness/{campaignId}":{"get":{"operationId":"MarketingController_managerAdsReadinessFor","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id."},{"name":"refresh","required":false,"in":"query","schema":{"type":"string","enum":["1","true"]},"description":"Re-check the platforms instead of the short cache."}],"responses":{"200":{"description":"Readiness per platform","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Ads readiness for one campaign","description":"Same as `GET …/ads-readiness?campaign=` — only the platforms this campaign targets.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaign-manager/ads-readiness/{campaignId} (campaignId: string, refresh?: string) -> Readiness per platform\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaign-manager/ads-readiness`","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/ad-accounts":{"get":{"operationId":"MarketingController_managerAdAccounts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"A platform (`facebook`, `instagram`, `google`, `linkedin`, `tiktok`, `pinterest`, `twitter`) or connection key (`meta`). Facebook and Instagram share the Meta connection.","example":"meta"},{"name":"refresh","required":false,"in":"query","schema":{"type":"string"},"description":"`1` to skip the short cache.","example":"1"}],"responses":{"200":{"description":"`{ connection, label, platforms, connected, issues, canList, accounts: [{ id, name, currency, status, selectable, reasons, paymentMethod, business, fixUrl }], usableCount, selected, manualEntry, guide, checkedAt }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List the ad accounts a platform connection can use","description":"The ad accounts the connected login can see on a platform, each marked `selectable` or not with `reasons` in plain words (inactive or disabled, no payment method, limited API access…) and a `fixUrl` on the platform where there is one. `selected` is the connection's current default. When nothing is usable, `guide` holds the platform's own steps to create one (official link included). `manualEntry` is true where an id can be typed in and verified (Meta). Without `platform`, every connection is returned as `{ connections: [...] }`.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaign-manager/ad-accounts (platform?: string, refresh?: string) -> `{ connection, label, platforms, connected, issues, canList, accounts: [{ id, name, currency, status, selectable, reasons, paymentMethod, business, fixUrl }], usableCount, selected, manualEntry, guide, checkedAt }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Also mounted as `GET /crm/marketing/campaign-manager/ad-accounts/{platform}`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/marketing/campaign-manager/ad-accounts/default`","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/objectives":{"get":{"operationId":"MarketingController_managerObjectives","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"refresh","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/crm/marketing/campaign-manager/connections/{connection}/disconnect":{"post":{"operationId":"MarketingController_managerDisconnect","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"connection","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/crm/marketing/campaign-manager/connections":{"get":{"operationId":"MarketingController_managerConnections","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"refresh","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/crm/marketing/campaign-manager/ad-accounts/{platform}":{"get":{"operationId":"MarketingController_managerAdAccountsFor","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":true,"in":"path","schema":{"type":"string"},"description":"Ad platform key.","example":"facebook"},{"name":"refresh","required":false,"in":"query","schema":{"type":"string","enum":["1","true"]}}],"responses":{"200":{"description":"Ad accounts, each marked usable or not with the reason","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Ad accounts for one platform","description":"Same as `GET …/ad-accounts?platform=`.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaign-manager/ad-accounts/{platform} (platform: string, refresh?: string) -> Ad accounts, each marked usable or not with the reason\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaign-manager/ad-accounts`","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/ad-accounts/default":{"post":{"operationId":"MarketingController_managerSetDefaultAdAccount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The connection's ad accounts, as `GET …/ad-accounts`, with the new `selected`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"… the connected login has no access to ad account … — The id is not one this login can use.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"… the connected login has no access to ad account …","path":"/crm/marketing/campaign-manager/ad-accounts/default","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Choose a platform connection's ad account","description":"Saves the ad account that campaigns on this platform launch from (stored on the connection as `adAccountIds`; also `adsAccountId` for Google and `advertiserId` for TikTok, which those integrations read). The account is checked against the platform again first: only one the login can use **and** that is fully ready is accepted. `accountId: null` clears it.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/ad-accounts/default (body) -> The connection's ad accounts, as `GET …/ad-accounts`, with the new `selected`.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The error body carries `reason` (the code above) next to the message.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `409` | ad_account_not_found | … the connected login has no access to ad account … | The id is not one this login can use. | Pick one from the list, or give the login access on the platform and refresh. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaign-manager/ad-accounts`","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","example":"facebook"},"accountId":{"type":"string","nullable":true,"example":"act_24661883323447662"}},"required":["platform"]},"example":{"platform":"facebook","accountId":"act_24661883323447662"}}}}}},"/crm/marketing/campaign-manager/{id}":{"get":{"operationId":"MarketingController_managerGet","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The enriched campaign card (same shape as the list rows)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a campaign card","description":"#### Signature\n\n```http\nGET /crm/marketing/campaign-manager/{id} (id: string) -> The enriched campaign card (same shape as the list rows)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]},"delete":{"operationId":"MarketingController_managerDelete","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"{ deleted: true, id }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a campaign","description":"Cancels its schedules, pauses it on its ad platforms if it is live (the platform campaign and its history are kept in the ad account), removes any paused test campaign, then deletes the record.\n\n#### Signature\n\n```http\nDELETE /crm/marketing/campaign-manager/{id} (id: string) -> { deleted: true, id }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/update":{"post":{"operationId":"MarketingController_managerUpdate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A campaign needs a name — `name` missing or blank (create, or an update that sends it).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A campaign needs a name","path":"/crm/marketing/campaign-manager/{id}/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update a campaign","description":"Changes any editable field (see create). On a live ad campaign a new name or budget is also pushed to its platforms; a platform refusal is logged and the local change is kept.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/update (id: string, body) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAME_REQUIRED | A campaign needs a name | `name` missing or blank (create, or an update that sends it). | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"budget":750}}}}}},"/crm/marketing/campaign-manager/{id}/launch":{"post":{"operationId":"MarketingController_managerLaunch","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/launch","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This campaign can't launch yet. Facebook, Instagram — No ad account is chosen for Facebook & Instagram (Meta). — A targeted ad platform is not connected, lacks the ads permission, or has no usable ad account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This campaign can't launch yet. Facebook, Instagram — No ad account is chosen for Facebook & Instagram (Meta).","path":"/crm/marketing/campaign-manager/{id}/launch","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Launch a campaign","description":"Launches through the campaign's channel. An **ad** campaign is refused up front while any platform it targets is not ready: nothing is sent to any platform and the campaign keeps its status. `POST …/{id}/schedule` applies the same check before booking a launch, and a scheduled launch that comes due while a platform is not ready is marked failed with the reason.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/launch (id: string) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `409` | ads_not_ready | This campaign can't launch yet. Facebook, Instagram — No ad account is chosen for Facebook & Instagram (Meta). | A targeted ad platform is not connected, lacks the ads permission, or has no usable ad account. | The body carries `readiness` (as `GET …/ads-readiness`) — follow each issue's `fix`, then launch again. |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaign-manager/ads-readiness`","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/pause":{"post":{"operationId":"MarketingController_managerPause","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Only an active campaign can be paused (this one is <status>) — The campaign is not active.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Only an active campaign can be paused (this one is <status>)","path":"/crm/marketing/campaign-manager/{id}/pause","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/pause","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Pause a campaign","description":"Only an active campaign. Pauses it on every ad platform it is live on (results kept in `platformResults`) and, for an email campaign, cancels the linked broadcast if it has not gone out.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/pause (id: string) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_ACTIVE | Only an active campaign can be paused (this one is <status>) | The campaign is not active. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/resume":{"post":{"operationId":"MarketingController_managerResume","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Only a paused campaign can be resumed (this one is <status>) — The campaign is not paused.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Only a paused campaign can be resumed (this one is <status>)","path":"/crm/marketing/campaign-manager/{id}/resume","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/resume","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Resume a paused campaign","description":"Only a paused campaign. Re-activates it on its ad platforms and sets it active.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/resume (id: string) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_PAUSED | Only a paused campaign can be resumed (this one is <status>) | The campaign is not paused. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/complete":{"post":{"operationId":"MarketingController_managerComplete","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Only a running or paused campaign can be ended — Any other status.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Only a running or paused campaign can be ended","path":"/crm/marketing/campaign-manager/{id}/complete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/complete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"End a campaign","description":"Only an active or paused campaign. Pauses it on its ad platforms (if active), cancels any pending schedule and marks it completed.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/complete (id: string) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_RUNNING | Only a running or paused campaign can be ended | Any other status. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/schedule":{"post":{"operationId":"MarketingController_managerSchedule","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A <status> campaign cannot be scheduled — Status is not draft, scheduled or failed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A <status> campaign cannot be scheduled","path":"/crm/marketing/campaign-manager/{id}/schedule","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/schedule","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This campaign can't be scheduled yet. … — A targeted ad platform is not ready; body carries `readiness`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This campaign can't be scheduled yet. …","path":"/crm/marketing/campaign-manager/{id}/schedule","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Schedule a launch","description":"Books a `schedule` record owned by the campaign that launches it at `startDate` (and ends it at `endDate` when given), replacing any earlier booking, and sets the campaign `scheduled`. Only draft, scheduled or failed campaigns. An ad campaign is only booked when every platform it targets is ready (same check as launch).\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/schedule (id: string, body) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_SCHEDULABLE | A <status> campaign cannot be scheduled | Status is not draft, scheduled or failed. | — |\n| `409` | ads_not_ready | This campaign can't be scheduled yet. … | A targeted ad platform is not ready; body carries `readiness`. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}}},"example":{"startDate":"2026-10-15T14:00:00Z","endDate":"2026-10-31T23:59:00Z"}}}}}},"/crm/marketing/campaign-manager/{id}/unschedule":{"post":{"operationId":"MarketingController_managerUnschedule","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"This campaign is not scheduled — Status is not scheduled.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This campaign is not scheduled","path":"/crm/marketing/campaign-manager/{id}/unschedule","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/unschedule","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Cancel a scheduled launch","description":"Deletes the pending schedule (which cancels its queued jobs) and returns the campaign to draft.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/unschedule (id: string) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_SCHEDULED | This campaign is not scheduled | Status is not scheduled. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/duplicate":{"post":{"operationId":"MarketingController_managerDuplicate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The new campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/duplicate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This campaign was just created — open it from Campaigns to keep editing it — The same duplicate was sent twice in a row.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This campaign was just created — open it from Campaigns to keep editing it","path":"/crm/marketing/campaign-manager/{id}/duplicate","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Duplicate a campaign","description":"A new draft with the same settings and none of the runtime state (platform ids, results, metrics, schedule). `name` defaults to \"<name> (Copy)\".\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/duplicate (id: string, body) -> The new campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n| `409` | DUPLICATE_CREATE | This campaign was just created — open it from Campaigns to keep editing it | The same duplicate was sent twice in a row. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}},"example":{"name":"Fall sale — TikTok"}}}}}},"/crm/marketing/campaign-manager/{id}/actuals":{"post":{"operationId":"MarketingController_managerActuals","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"<field> must be a number of zero or more — A figure is negative or not a number.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"<field> must be a number of zero or more","path":"/crm/marketing/campaign-manager/{id}/actuals","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/actuals","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Enter actual results","description":"For channels no system reports on (radio, print, TV…): `spent`, `reach`, `impressions`, `clicks`, `conversions`, `revenue` (each ≥ 0) and an optional `note`. They replace the previous entry and count toward the card's metrics.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/actuals (id: string, body) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | BAD_FIGURE | <field> must be a number of zero or more | A figure is negative or not a number. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spent":{"type":"number"},"reach":{"type":"number"},"impressions":{"type":"number"},"clicks":{"type":"number"},"conversions":{"type":"number"},"revenue":{"type":"number"},"note":{"type":"string","maxLength":1000}}},"example":{"spent":1200,"reach":40000,"note":"Invoice from KXYZ radio"}}}}}},"/crm/marketing/campaign-manager/{id}/refresh-metrics":{"post":{"operationId":"MarketingController_managerRefresh","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"This campaign is not live on any ad platform yet, so there are no platform insights to pull — No platform reference on the campaign.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"This campaign is not live on any ad platform yet, so there are no platform insights to pull","path":"/crm/marketing/campaign-manager/{id}/refresh-metrics","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/refresh-metrics","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"No platform returned insights: <platform>: <error> — Every platform failed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"No platform returned insights: <platform>: <error>","path":"/crm/marketing/campaign-manager/{id}/refresh-metrics","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"Pull platform insights","description":"Fetches spend, reach, impressions, clicks and conversions from every ad platform the campaign is live on and stores them (`platformMetrics`). Platforms that fail are listed in `platformMetrics.errors`.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/refresh-metrics (id: string) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_LIVE | This campaign is not live on any ad platform yet, so there are no platform insights to pull | No platform reference on the campaign. | — |\n| `502` | NO_INSIGHTS | No platform returned insights: <platform>: <error> | Every platform failed. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/copy":{"post":{"operationId":"MarketingController_managerCopy","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Send at least one headline or description — Both lists empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Send at least one headline or description","path":"/crm/marketing/campaign-manager/{id}/copy","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/copy","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Save ad copy","description":"Saves headlines, descriptions and a call to action for one `platform` (default `all`) as the campaign's creative for that platform, replacing the previous one. Nothing is published.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/copy (id: string, body) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NO_COPY | Send at least one headline or description | Both lists empty. | — |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"headlines":{"type":"array","items":{"type":"string"}},"descriptions":{"type":"array","items":{"type":"string"}},"cta":{"type":"string"}}},"example":{"platform":"facebook","headlines":["30% off this week"],"descriptions":["Ends Sunday."],"cta":"SHOP_NOW"}}}}}},"/crm/marketing/campaign-manager/{id}/ad-account":{"post":{"operationId":"MarketingController_managerSetAdAccount","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card, with `adAccounts` and fresh `adsReadiness`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/ad-account","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Override a campaign's ad account on one platform","description":"Launch this campaign from a different ad account than the connection default, on one platform (Facebook and Instagram share one Meta account). Verified exactly like the default. `accountId: null` returns to the default. Only while the campaign is a draft, scheduled or failed.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/ad-account (id: string, body) -> The campaign card, with `adAccounts` and fresh `adsReadiness`.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","example":"facebook"},"accountId":{"type":"string","nullable":true,"example":"act_36945266"}},"required":["platform"]}}}}}},"/crm/marketing/campaign-manager/{id}/test-launch":{"post":{"operationId":"MarketingController_managerTestLaunch","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card with `testLaunch.launches`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A paused test launch is available for Facebook and Instagram … — The campaign targets neither Facebook nor Instagram.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A paused test launch is available for Facebook and Instagram …","path":"/crm/marketing/campaign-manager/{id}/test-launch","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Test launch needs Meta to be ready first. … — Meta is not ready (no ad account chosen, missing permission…).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Test launch needs Meta to be ready first. …","path":"/crm/marketing/campaign-manager/{id}/test-launch","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Test-launch a campaign on Meta, paused","description":"Proves the Meta setup end to end without spending: creates the campaign on the chosen Meta ad account in **PAUSED** status, with no budget, no ad sets and no ads, reads it back, and deletes it at once if Meta reports anything other than PAUSED. The platform campaign id is kept on the campaign (`testLaunch.launches`) with an Ads Manager link. Only Meta supports this; other platforms are never test-created.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/test-launch (id: string) -> The campaign card with `testLaunch.launches`.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `409` | ads_not_ready | Test launch needs Meta to be ready first. … | Meta is not ready (no ad account chosen, missing permission…). | Follow the `readiness` fixes. |\n| `400` | test_launch_unsupported | A paused test launch is available for Facebook and Instagram … | The campaign targets neither Facebook nor Instagram. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/marketing/campaign-manager/{id}/test-remove`","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager/{id}/test-remove":{"post":{"operationId":"MarketingController_managerRemoveTest","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The campaign card","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaign-manager/{id}/test-remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The test could not be removed on Meta: … — Meta refused the delete.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"The test could not be removed on Meta: …","path":"/crm/marketing/campaign-manager/{id}/test-remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"Remove a paused test campaign","description":"Deletes the paused test campaign on Meta and clears it from the campaign. Deleting the campaign record removes its test too.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaign-manager/{id}/test-remove (id: string) -> The campaign card\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `502` | test_remove_failed | The test could not be removed on Meta: … | Meta refused the delete. | Retry, or delete it in Ads Manager. |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-manager-performance":{"get":{"operationId":"MarketingController_managerPerformance","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"{ summary, topByConversions, failed, untracked, campaigns }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Campaign performance summary","description":"What the marketing AI answers \"how are my campaigns doing?\" from: the org totals, the top 5 campaigns by conversions, failed campaigns with their reason, untracked campaigns, and a compact row per campaign (first 100).\n\n#### Signature\n\n```http\nGET /crm/marketing/campaign-manager-performance () -> { summary, topByConversions, failed, untracked, campaigns }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","tags":["CRM · Marketing"]}},"/crm/marketing/social-profiles/{platform}":{"get":{"operationId":"MarketingController_getSocialProviders","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":true,"in":"path","schema":{"type":"string"},"description":"One of `facebook`, `instagram`, `tiktok`, `twitter`, `linkedin`, `pinterest`. Omit for all.","example":"instagram"}],"responses":{"200":{"description":"Connected profiles","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get connected social profiles","description":"The social accounts available to publish marketing campaigns from. Supply `platform` to narrow it.\n\n#### Signature\n\n```http\nGET /crm/marketing/social-profiles/{platform} (platform: string) -> Connected profiles\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/platforms`","tags":["CRM · Marketing"]}},"/crm/marketing/campaigns":{"post":{"operationId":"MarketingController_createCampaign","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created campaign","content":{"application/json":{"schema":{"type":"object","description":"A marketing campaign.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a marketing campaign","description":"Creates a marketing campaign. Distinct from `/crm/ads` — that manages paid advertising on ad platforms; this covers owned marketing across channels.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaigns (body) -> The created campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaign-types`","tags":["CRM · Marketing"],"requestBody":{"description":"The campaign to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Summer newsletter"},"type":{"type":"string","example":"email"},"audienceId":{"type":"string","description":"Segment to target.","example":"AUD-4821"},"schedule":{"type":"object","additionalProperties":true}}},"example":{"name":"Summer newsletter","type":"email","audienceId":"AUD-4821"}}}}},"get":{"operationId":"MarketingController_getCampaigns","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by status."},{"name":"type","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by type."},{"name":"platforms","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated platforms."},{"name":"tags","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated tags."},{"name":"createdBy","required":false,"in":"query","schema":{"type":"string"},"description":"Creator email."},{"name":"search","required":false,"in":"query","schema":{"type":"string"},"description":"Search text."},{"name":"budgetMin","required":false,"in":"query","schema":{"type":"integer"},"description":"Minimum budget."},{"name":"budgetMax","required":false,"in":"query","schema":{"type":"integer"},"description":"Maximum budget."},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — start of the range."},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — end of the range."},{"name":"sortDirection","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows.","schema":{"type":"string"}},{"name":"sortField","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string"}}],"responses":{"200":{"description":"Marketing campaigns","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List marketing campaigns","description":"The org's marketing campaigns, with their status and schedule.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaigns (status?: string, type?: string, platforms?: string, tags?: string, createdBy?: string, search?: string, budgetMin?: integer, budgetMax?: integer, startDate?: string, endDate?: string, page?: string, limit?: string, sortField?: string, sortDirection?: string) -> Marketing campaigns\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaigns/{id}`","tags":["CRM · Marketing"]}},"/crm/marketing/campaigns/{id}":{"get":{"operationId":"MarketingController_getCampaign","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object","description":"A marketing campaign.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaigns/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a marketing campaign","description":"Fetches one campaign with its targeting, schedule and current state.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaigns/{id} (id: string) -> The campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaigns/{id}/analytics`","tags":["CRM · Marketing"]},"put":{"operationId":"MarketingController_updateCampaign","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The updated campaign","content":{"application/json":{"schema":{"type":"object","description":"A marketing campaign.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaigns/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update a marketing campaign","description":"Updates a campaign. Changes to one already sent affect only future sends — a delivered email cannot be edited.\n\n#### Signature\n\n```http\nPUT /crm/marketing/campaigns/{id} (id: string, body) -> The updated campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/marketing/campaigns/{id}`","tags":["CRM · Marketing"],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Summer newsletter (v2)"}}}}},"delete":{"operationId":"MarketingController_deleteCampaign","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaigns/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a marketing campaign","description":"Deletes a campaign. Its historical performance data goes with it — export analytics first if you need them.\n\n#### Signature\n\n```http\nDELETE /crm/marketing/campaigns/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaigns/{id}/analytics`","tags":["CRM · Marketing"]}},"/crm/marketing/campaigns/{id}/analytics":{"get":{"operationId":"MarketingController_getCampaignAnalytics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — start of the range."},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — end of the range."}],"responses":{"200":{"description":"Campaign analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Campaign not found — No campaign has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Campaign not found","path":"/crm/marketing/campaigns/{id}/analytics","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get campaign analytics","description":"Performance for one campaign — sends, opens, clicks and conversions.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaigns/{id}/analytics (id: string, startDate?: string, endDate?: string) -> Campaign analytics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Campaign not found | No campaign has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/marketing/campaigns/aggregated-metrics`","tags":["CRM · Marketing"]}},"/crm/marketing/campaigns/aggregated-metrics":{"post":{"operationId":"MarketingController_getAggregatedMetrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Aggregated metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get aggregated campaign metrics","description":"Combines metrics across several campaigns in one call — the read behind a marketing overview, rather than fetching analytics per campaign.\n\n#### Signature\n\n```http\nPOST /crm/marketing/campaigns/aggregated-metrics (body) -> Aggregated metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/dashboard`","tags":["CRM · Marketing"],"requestBody":{"description":"Which campaigns and period to aggregate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"campaignIds":{"type":"array","items":{"type":"string"}},"startDate":{"type":"string","example":"2026-08-01"},"endDate":{"type":"string","example":"2026-08-31"}}},"example":{"campaignIds":["CMP-4821","CMP-4822"],"startDate":"2026-08-01","endDate":"2026-08-31"}}}}}},"/crm/marketing/platforms":{"get":{"operationId":"MarketingController_getAvailablePlatforms","parameters":[{"name":"orgId","required":true,"in":"header","schema":{"type":"string"}},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Marketing platforms","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List marketing platforms","description":"The channels marketing campaigns can run on, and which are connected for this org.\n\n#### Signature\n\n```http\nGET /crm/marketing/platforms () -> Marketing platforms\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/campaign-types`","tags":["CRM · Marketing"]}},"/crm/marketing/campaign-types":{"get":{"operationId":"MarketingController_getCampaignTypes","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Campaign types","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List campaign types","description":"The kinds of campaign that can be created, with the fields each requires. Read this to build a campaign form generically.\n\n#### Signature\n\n```http\nGET /crm/marketing/campaign-types () -> Campaign types\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/marketing/campaigns`","tags":["CRM · Marketing"]}},"/crm/marketing/dashboard":{"get":{"operationId":"MarketingController_getCampaignDashboard","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — start of the range."},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — end of the range."}],"responses":{"200":{"description":"Dashboard figures","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get the marketing dashboard","description":"Headline marketing figures across campaigns and channels.\n\n#### Signature\n\n```http\nGET /crm/marketing/dashboard (startDate?: string, endDate?: string) -> Dashboard figures\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/health`","tags":["CRM · Marketing"]}},"/crm/marketing/health":{"get":{"operationId":"MarketingController_healthCheck","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Integration health","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get marketing health","description":"Whether the marketing integrations are connected and working — check this first when campaigns fail to send.\n\n#### Signature\n\n```http\nGET /crm/marketing/health () -> Integration health\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/platforms`","tags":["CRM · Marketing"]}},"/crm/marketing/audiences/website":{"post":{"operationId":"AudienceController_createWebsiteAudience","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/crm/marketing/audiences/segments":{"post":{"operationId":"AudienceController_createAudienceSegment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"createdBy","in":"query","required":false,"description":"Recorded as the creator. Defaults to the literal string `api`, **not** the calling user.","schema":{"type":"string","default":"api"},"example":"ada@example.com"}],"responses":{"201":{"description":"The created segment, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"An audience segment.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"High-value repeat buyers"},"description":{"type":"string"},"criteria":{"type":"object","additionalProperties":true,"description":"The rules that define membership."},"size":{"type":"number","description":"How many people match, as an ad network counted it. Absent until one has."},"platforms":{"type":"array","items":{"type":"string"},"example":["facebook"]}}}}},"message":{"type":"string","example":"Audience segment created successfully"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create an audience segment","description":"Defines a reusable audience from targeting criteria, so campaigns can reference it instead of restating the rules.\n\nNote `createdBy` is a **query parameter** defaulting to the literal string `api` — it is not taken from the authenticated user, so pass it explicitly if you want a real name in the audit trail.\n\n#### Signature\n\n```http\nPOST /crm/marketing/audiences/segments (createdBy?: string, body) -> The created segment, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Responses on this controller are wrapped as `{ success, data, message }` rather than returning the record bare.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/marketing/audiences/estimate-reach`","tags":["CRM · Audiences"],"requestBody":{"description":"The segment to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"High-value repeat buyers"},"description":{"type":"string"},"criteria":{"type":"object","additionalProperties":true,"description":"The rules defining membership."}}},"example":{"name":"High-value repeat buyers","description":"Three or more orders over $200","criteria":{"minOrders":3,"minLifetimeValue":200}}}}}},"get":{"operationId":"AudienceController_getAudienceSegments","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by status."},{"name":"platforms","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated platforms."},{"name":"sizeMin","required":false,"in":"query","schema":{"type":"integer"},"description":"Minimum audience size."},{"name":"sizeMax","required":false,"in":"query","schema":{"type":"integer"},"description":"Maximum audience size."},{"name":"ageMin","required":false,"in":"query","schema":{"type":"integer"},"description":"Minimum age."},{"name":"ageMax","required":false,"in":"query","schema":{"type":"integer"},"description":"Maximum age."},{"name":"locations","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated locations."},{"name":"interests","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated interests."},{"name":"behaviors","required":false,"in":"query","schema":{"type":"string"},"description":"Comma-separated behaviors."},{"name":"createdBy","required":false,"in":"query","schema":{"type":"string"},"description":"Creator email."},{"name":"search","required":false,"in":"query","schema":{"type":"string"},"description":"Search text."},{"name":"sortDirection","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows.","schema":{"type":"string"}},{"name":"sortField","in":"query","required":false,"description":"Field to sort by.","schema":{"type":"string"}}],"responses":{"200":{"description":"Audience segments, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","description":"An audience segment.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"High-value repeat buyers"},"description":{"type":"string"},"criteria":{"type":"object","additionalProperties":true,"description":"The rules that define membership."},"size":{"type":"number","description":"How many people match, as an ad network counted it. Absent until one has."},"platforms":{"type":"array","items":{"type":"string"},"example":["facebook"]}}}}}},"message":{"type":"string","example":"Audience segments retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List audience segments","description":"The audience segments defined for the org.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/segments (status?: string, platforms?: string, sizeMin?: integer, sizeMax?: integer, ageMin?: integer, ageMax?: integer, locations?: string, interests?: string, behaviors?: string, createdBy?: string, search?: string, page?: string, limit?: string, sortField?: string, sortDirection?: string) -> Audience segments, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/segments/{id}`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/segments/{id}":{"get":{"operationId":"AudienceController_getAudienceSegment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Audience segment id.","example":"AUD-4821"}],"responses":{"200":{"description":"The segment, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"An audience segment.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"High-value repeat buyers"},"description":{"type":"string"},"criteria":{"type":"object","additionalProperties":true,"description":"The rules that define membership."},"size":{"type":"number","description":"How many people match, as an ad network counted it. Absent until one has."},"platforms":{"type":"array","items":{"type":"string"},"example":["facebook"]}}}}},"message":{"type":"string","example":"Audience segment retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an audience segment","description":"Fetches one segment with its criteria.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/segments/{id} (id: string) -> The segment, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/marketing/audiences/segments/{id}`","tags":["CRM · Audiences"]},"put":{"operationId":"AudienceController_updateAudienceSegment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Audience segment id.","example":"AUD-4821"},{"name":"updatedBy","in":"query","required":false,"description":"Who made the change (recorded on the record).","schema":{"type":"string"}}],"responses":{"200":{"description":"The updated segment, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"An audience segment.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"High-value repeat buyers"},"description":{"type":"string"},"criteria":{"type":"object","additionalProperties":true,"description":"The rules that define membership."},"size":{"type":"number","description":"How many people match, as an ad network counted it. Absent until one has."},"platforms":{"type":"array","items":{"type":"string"},"example":["facebook"]}}}}},"message":{"type":"string","example":"Audience segment updated"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update an audience segment","description":"Updates a segment's criteria or details. Changing criteria changes who is in the audience for **future** campaigns; campaigns already sent are unaffected.\n\n#### Signature\n\n```http\nPUT /crm/marketing/audiences/segments/{id} (id: string, updatedBy?: string, body) -> The updated segment, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/marketing/audiences/segments/{id}`","tags":["CRM · Audiences"],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"criteria":{"minOrders":5,"minLifetimeValue":500}}}}}},"delete":{"operationId":"AudienceController_deleteAudienceSegment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Audience segment id.","example":"AUD-4821"},{"name":"deletedBy","in":"query","required":false,"description":"Who deleted it (recorded).","schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion result, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string","example":"Audience segment deleted"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete an audience segment","description":"Deletes a segment. Campaigns still referencing it lose their targeting — check what uses it before deleting.\n\n#### Signature\n\n```http\nDELETE /crm/marketing/audiences/segments/{id} (id: string, deletedBy?: string) -> Deletion result, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Nothing checks for campaigns using the segment first.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/segments`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/custom":{"post":{"operationId":"AudienceController_createCustomAudience","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"createdBy","in":"query","required":false,"description":"Recorded as the creator. Defaults to the literal string `api`, **not** the calling user.","schema":{"type":"string","default":"api"},"example":"ada@example.com"}],"responses":{"201":{"description":"The created custom audience, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string","example":"Custom audience created successfully"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a custom audience","description":"Creates a platform-specific custom audience — an uploaded list or a lookalike — as opposed to a criteria-based segment.\n\n#### Signature\n\n```http\nPOST /crm/marketing/audiences/custom (createdBy?: string, body) -> The created custom audience, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Uploading customer data to an ad platform carries its own consent obligations — this endpoint does not check them.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/custom`","tags":["CRM · Audiences"],"requestBody":{"description":"The custom audience to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Newsletter subscribers"},"platform":{"type":"string","example":"facebook"},"type":{"type":"string","example":"customer_list"}}},"example":{"name":"Newsletter subscribers","platform":"facebook","type":"customer_list"}}}}},"get":{"operationId":"AudienceController_getCustomAudiences","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"example":"facebook"},{"name":"type","required":false,"in":"query","schema":{"type":"string"},"example":"customer_list"}],"responses":{"200":{"description":"Custom audiences, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"message":{"type":"string","example":"Custom audiences retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List custom audiences","description":"The platform-specific custom audiences, optionally filtered by platform or type.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/custom (platform?: string, type?: string) -> Custom audiences, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/custom-types`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/segments/{id}/insights":{"get":{"operationId":"AudienceController_getAudienceInsights","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Audience segment id.","example":"AUD-4821"}],"responses":{"200":{"description":"Audience insights, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string","example":"Insights retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get audience insights","description":"Demographic and behavioural breakdown of who is in a segment — what the audience actually looks like, rather than just how large it is.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/segments/{id}/insights (id: string) -> Audience insights, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/segments/{id1}/overlap/{id2}`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/estimate-reach":{"post":{"operationId":"AudienceController_estimateAudienceReach","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"No estimate, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"estimatedReach":{"type":"null"},"message":{"type":"string"}}},"message":{"type":"string","example":"No estimate"}}},"example":{"success":true,"data":{"estimatedReach":null,"message":"Audience size comes from each ad network once its ad account is connected."}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Estimate audience reach","description":"The server does not estimate audience size: each ad network counts an audience once its ad account is connected. This answers `estimatedReach: null` with a message saying so.\n\n#### Signature\n\n```http\nPOST /crm/marketing/audiences/estimate-reach () -> No estimate, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Creates nothing.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/marketing/audiences/segments`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/segments/{id1}/overlap/{id2}":{"get":{"operationId":"AudienceController_getAudienceOverlap","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id1","required":true,"in":"path","schema":{"type":"string"},"description":"First segment.","example":"AUD-4821"},{"name":"id2","required":true,"in":"path","schema":{"type":"string"},"description":"Second segment.","example":"AUD-4822"}],"responses":{"200":{"description":"No overlap figure, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"audienceId1":{"type":"string"},"audienceId2":{"type":"string"},"overlapPercentage":{"type":"null"},"message":{"type":"string"}}},"message":{"type":"string","example":"No overlap figure"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get overlap between two audiences","description":"The server does not estimate how much two segments share: each ad network measures overlap once its ad account is connected. This checks both segments exist (404 otherwise) and answers `overlapPercentage: null` with a message saying so.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/segments/{id1}/overlap/{id2} (id1: string, id2: string) -> No overlap figure, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/segments/{id}/insights`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/interests":{"get":{"operationId":"AudienceController_getPopularInterests","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"category","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Interests, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"message":{"type":"string","example":"Interests retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List targetable interests","description":"The interest categories available for targeting — the vocabulary a segment's criteria can draw on.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/interests (category?: string) -> Interests, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/targeting-options`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/locations":{"get":{"operationId":"AudienceController_getLocationSuggestions","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"query","required":false,"in":"query","schema":{"type":"string"},"description":"Location search text."}],"responses":{"200":{"description":"Locations, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"message":{"type":"string","example":"Locations retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List targetable locations","description":"The geographic locations available for targeting.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/locations (query?: string) -> Locations, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/targeting-options`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/custom-types":{"get":{"operationId":"AudienceController_getCustomAudienceTypes","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Custom audience types, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"message":{"type":"string","example":"Types retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List custom audience types","description":"The kinds of custom audience that can be created — customer list, lookalike, engagement-based and so on.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/custom-types () -> Custom audience types, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/marketing/audiences/custom`","tags":["CRM · Audiences"]}},"/crm/marketing/audiences/targeting-options":{"get":{"operationId":"AudienceController_getTargetingOptions","parameters":[{"name":"orgId","required":false,"in":"query","schema":{"type":"string"},"description":"Organization id (the `orgid` header is what scopes the request)."},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Targeting options, wrapped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string","example":"Targeting options retrieved"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List all targeting options","description":"Every dimension a segment can target on, in one call — build a targeting UI from this rather than fetching interests and locations separately.\n\n#### Signature\n\n```http\nGET /crm/marketing/audiences/targeting-options (orgId?: string) -> Targeting options, wrapped\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/marketing/audiences/interests`\n- `GET /crm/marketing/audiences/locations`","tags":["CRM · Audiences"]}},"/crm/leads/sla/sweep":{"post":{"operationId":"LeadsController_runSlaSweep","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ ran: true, lastRun }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"],"summary":"Run the stage-SLA sweep now","description":"Root admins only. Runs the hourly job that chases leads sitting in a stage past its SLA, instead of waiting for the next run.\n\n#### Signature\n\n```http\nPOST /crm/leads/sla/sweep () -> { ran: true, lastRun }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootSystem`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/leads/import":{"post":{"operationId":"LeadsController_importLeads","summary":"Import leads from spreadsheet rows","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"{ total, created, skipped, failed, errors: [{ row, error }], skippedRows: [{ row, reason }] }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"No rows to import — `rows` missing or empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"No rows to import","path":"/crm/leads/import","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"],"description":"Creates a lead per row (at most 5,000 per call). Column names from a HubSpot export are recognised. A row with no usable data is skipped, and so is a row whose email is already a lead (or appears earlier in the same import). `pipelineId` / `stageId` place every new lead. Each row is created independently: one failing row is reported and the rest carry on.\n\n#### Signature\n\n```http\nPOST /crm/leads/import (body) -> { total, created, skipped, failed, errors: [{ row, error }], skippedRows: [{ row, reason }] }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NO_ROWS | No rows to import | `rows` missing or empty. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":true}},"pipelineId":{"type":"string"},"stageId":{"type":"string"}}},"example":{"rows":[{"First Name":"Ada","Last Name":"Lovelace","Email":"ada@example.com","Company":"Analytical Ltd"}],"pipelineId":"PL-1"}}}}}},"/crm/leads/detail":{"post":{"operationId":"LeadsController_createLead","summary":"Create a lead","description":"Creates a lead. **Validation is deliberately minimal** — almost every field is optional, because the point is to capture whatever a form or a phone call produced and fill in the rest later.\n\nOnly two rules apply: an `email`, *if supplied*, must be well-formed; and `status` defaults to `new` when omitted. A lead with nothing but a first name is valid.\n\nA duplicate on a unique field is reported as a `409` naming the field.\n\nLead errors carry a richer body than the platform default — `{ statusCode, message, error?, suggestion? }`. The `suggestion` is written for a person and is safe to show in a UI.\n\n#### Signature\n\n```http\nPOST /crm/leads/detail (body) -> The created lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Empty is better than wrong here — omit a field you are unsure of rather than guessing, and enrich it later.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_EMAIL | Invalid email format: \"<email>\" | An `email` was supplied and is not well-formed. | Fix the address, or leave it blank and add it later — a lead does not need one. |\n| `409` | DUPLICATE_LEAD | A lead with this <field> already exists | A unique field collides with an existing lead. | Update the existing lead instead, or use different contact details. The message names the offending field. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/enrich/{id}`\n- `GET /crm/leads/detail`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The lead to create. Nearly everything is optional.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}},"examples":{"minimal":{"summary":"Almost nothing","description":"Entirely valid — enrich it later.","value":{"firstName":"Ada"}},"typical":{"summary":"A form submission","value":{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","phone":"+15551234567","company":"Analytical Engines Ltd","source":"website"}},"intoPipeline":{"summary":"Straight into a pipeline stage","value":{"firstName":"Ada","email":"ada@example.com","pipelineId":"PIPE-4821","stageId":"STG-1","priority":"high"}}}}}},"responses":{"201":{"description":"The created lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"400":{"description":"Invalid email format: \"<email>\" — An `email` was supplied and is not well-formed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"message":"Invalid email format: \"ada@\"","suggestion":"Fix the email or leave it blank to add later"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"A lead with this <field> already exists — A unique field collides with an existing lead.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"message":"A lead with this email already exists","error":"DUPLICATE_LEAD","suggestion":"Try updating the existing lead or use different contact information"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]},"get":{"operationId":"LeadsController_getLeads","summary":"List leads","description":"Lists leads with filtering, sorting and paging — the pipeline list view.\n\n#### Signature\n\n```http\nGET /crm/leads/detail (pipeline?: string, status?: string, priority?: string, source?: string, assignedTo?: string, search?: string, page?: integer, pageSize?: integer, sortField?: string, sortDirection?: string) -> A page of leads\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | OPERATION_FAILED | Failed to retrieve leads | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /crm/leads/detail/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"]},"example":"new"},{"name":"priority","required":false,"in":"query","schema":{"type":"string"},"example":"high"},{"name":"source","required":false,"in":"query","schema":{"type":"string"},"example":"facebook"},{"name":"assignedTo","required":false,"in":"query","description":"Filter to one owner.","schema":{"type":"string"},"example":"sales@acme.com"},{"name":"search","required":false,"in":"query","description":"Free-text search across name, email and company.","schema":{"type":"string"},"example":"lovelace"},{"name":"pipeline","required":false,"in":"query","schema":{"type":"string"},"description":"Pipeline id."},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50},{"name":"sortField","required":false,"in":"query","description":"Field to sort by.","schema":{"type":"string"},"example":"createdAt"},{"name":"sortDirection","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]},"example":"desc"},{"name":"includeArchived","required":true,"in":"query","schema":{"type":"string"}},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"responses":{"200":{"description":"A page of leads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}},"total":{"type":"integer","example":412}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to retrieve leads — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to retrieve leads","path":"/crm/leads/detail","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Leads"]}},"/crm/leads/detail/{id}":{"get":{"operationId":"LeadsController_getLead","summary":"Get a lead","description":"Fetches one lead with its full record, including score and pipeline position.\n\n#### Signature\n\n```http\nGET /crm/leads/detail/{id} (id: string) -> The lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/leads/detail/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"responses":{"200":{"description":"The lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/detail/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]},"put":{"operationId":"LeadsController_updateLead","summary":"Update a lead","description":"Updates a lead's fields. Use the dedicated lifecycle endpoints for qualification, conversion and assignment — those record the transition, this one just writes fields.\n\n#### Signature\n\n```http\nPUT /crm/leads/detail/{id} (id: string, body) -> The updated lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Setting `status` directly here bypasses the qualify/disqualify/convert endpoints and records no transition.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n| `500` | OPERATION_FAILED | Failed to update lead | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /crm/leads/qualify/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}},"example":{"phone":"+15551234567","company":"Analytical Engines Ltd","priority":"high"}}}},"responses":{"200":{"description":"The updated lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/detail/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to update lead — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to update lead","path":"/crm/leads/detail/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Leads"]},"delete":{"operationId":"LeadsController_deleteLead","summary":"Delete a lead","description":"Permanently deletes a lead. Disqualify it instead when you want to keep the record of why it went nowhere.\n\n#### Signature\n\n```http\nDELETE /crm/leads/detail/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | OPERATION_FAILED | Failed to delete lead | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /crm/leads/disqualify/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to delete lead — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to delete lead","path":"/crm/leads/detail/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Leads"]}},"/crm/leads/detail/{id}/archive":{"post":{"operationId":"LeadsController_archiveLead","summary":"Archive a lead: it leaves the board and lists, keeps its outcome and history. Restore brings it back.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Lead ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Leads"]}},"/crm/leads/detail/{id}/restore":{"post":{"operationId":"LeadsController_restoreLead","summary":"Restore an archived lead","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Lead ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Leads"]}},"/crm/leads/qualify/{id}":{"post":{"operationId":"LeadsController_qualifyLead","summary":"Qualify a lead","description":"Marks a lead as qualified — worth pursuing. Notes are recorded with the transition.\n\n#### Signature\n\n```http\nPOST /crm/leads/qualify/{id} (id: string, body) -> The qualified lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/disqualify/{id}`\n- `POST /crm/leads/convert/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"requestBody":{"description":"Optional qualification notes.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Recorded with the transition.","example":"Budget confirmed, decision maker identified"}}},"example":{"notes":"Budget confirmed, decision maker identified"}}}},"responses":{"201":{"description":"The qualified lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/qualify/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/disqualify/{id}":{"post":{"operationId":"LeadsController_disqualifyLead","summary":"Disqualify a lead","description":"Marks a lead as not worth pursuing, recording why. The record is kept, which is what makes source quality measurable later.\n\n#### Signature\n\n```http\nPOST /crm/leads/disqualify/{id} (id: string, body) -> The disqualified lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Prefer this to deleting — a disqualified lead with a reason is data; a deleted one is nothing.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/qualify/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"requestBody":{"description":"Why the lead was disqualified.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Recorded with the transition.","example":"No budget this financial year"}}},"example":{"reason":"No budget this financial year"}}}},"responses":{"201":{"description":"The disqualified lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/disqualify/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/convert/{id}":{"post":{"operationId":"LeadsController_convertLead","summary":"Convert a lead","description":"Converts a lead into a customer. Pass `customerId` to link it to an existing customer, or omit it to have one created.\n\n`conversionValue` records what the conversion was worth, which is what makes the analytics endpoint able to report value by source rather than just counts.\n\n#### Signature\n\n```http\nPOST /crm/leads/convert/{id} (id: string, body) -> The converted lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Always send `conversionValue` where you know it — without it, conversion analytics only counts leads, not revenue.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/leads/analytics`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"requestBody":{"description":"Conversion details.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"Existing customer to link to. Omit to create one.","example":"cus_4821"},"conversionValue":{"type":"number","description":"Value of the conversion, for reporting.","example":4500}}},"examples":{"newCustomer":{"summary":"Convert and create a customer","value":{"conversionValue":4500}},"existing":{"summary":"Link to an existing customer","value":{"customerId":"cus_4821","conversionValue":4500}}}}}},"responses":{"201":{"description":"The converted lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/convert/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/assign/{id}":{"post":{"operationId":"LeadsController_assignLead","summary":"Assign a lead","description":"Assigns a lead to a user, making it appear in their queue. Assigning an already-assigned lead reassigns it.\n\n#### Signature\n\n```http\nPOST /crm/leads/assign/{id} (id: string, body) -> The assigned lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/pipelines/{id}/route-unassigned`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"requestBody":{"description":"Who to assign it to.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["assignedTo"],"properties":{"assignedTo":{"type":"string","description":"User to own the lead.","example":"sales@acme.com"}}},"example":{"assignedTo":"sales@acme.com"}}}},"responses":{"201":{"description":"The assigned lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/assign/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/follow-up/{id}":{"post":{"operationId":"LeadsController_scheduleFollowUp","summary":"Schedule a follow-up","description":"Sets a follow-up date on a lead so it resurfaces at the right time. Recording *why* in `notes` is what makes the reminder useful when it arrives.\n\n#### Signature\n\n```http\nPOST /crm/leads/follow-up/{id} (id: string, body) -> The updated lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/activities/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"requestBody":{"description":"When to follow up, and why.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["followUpDate"],"properties":{"followUpDate":{"type":"string","format":"date-time","example":"2026-09-15T09:00:00.000Z"},"notes":{"type":"string","example":"Check whether the new budget was approved"}}},"example":{"followUpDate":"2026-09-15T09:00:00.000Z","notes":"Check whether the new budget was approved"}}}},"responses":{"201":{"description":"The updated lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/follow-up/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/forecast":{"get":{"operationId":"LeadsController_getForecast","summary":"Pipeline forecast","description":"A weighted forecast by expected close month and by owner. Open leads count at their stage's probability; a deal is a lead at a won stage. Months run from this month for `months` (1–24, default 6); earlier dates fall into `overdue`, later ones into `later`, undated into `unscheduled`. Totals flag leads with no value (`unpriced`) and stages with no probability.\n\n#### Signature\n\n```http\nGET /crm/leads/forecast (pipelineId?: string, months?: integer) -> { months, byMonth, byOwner, totals: { openCount, openValue, weighted, wonCount, wonValue, lostCount, unpriced, withoutProbability }, pipelines }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"pipelineId","required":false,"in":"query","schema":{"type":"string"}},{"name":"months","required":false,"in":"query","schema":{"type":"integer","default":6}},{"name":"endDate","required":false,"in":"query","description":"End date for analytics","schema":{}},{"name":"startDate","required":false,"in":"query","description":"Start date for analytics","schema":{}},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"responses":{"200":{"description":"{ months, byMonth, byOwner, totals: { openCount, openValue, weighted, wonCount, wonValue, lostCount, unpriced, withoutProbability }, pipelines }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/analytics":{"get":{"operationId":"LeadsController_getLeadAnalytics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — start of the range."},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date — end of the range."}],"responses":{"200":{"description":"Aggregate lead analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to retrieve lead analytics — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to retrieve lead analytics","path":"/crm/leads/analytics","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Leads"],"summary":"Get lead analytics","description":"Aggregate lead figures — volume by status and source, conversion rates and value. Conversion value is only meaningful where `conversionValue` was recorded at conversion time.\n\n#### Signature\n\n```http\nGET /crm/leads/analytics (startDate?: string, endDate?: string) -> Aggregate lead analytics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | OPERATION_FAILED | Failed to retrieve lead analytics | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /crm/leads/convert/{id}`"}},"/crm/leads/enrich/batch":{"post":{"operationId":"LeadsController_enrichLeadsBatch","summary":"Enrich several leads","description":"Enriches many leads in one call. Enrichment usually costs money per lead at the provider, so send only the leads that need it.\n\n#### Signature\n\n```http\nPOST /crm/leads/enrich/batch (body) -> Per-lead enrichment results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Usually billed per lead by the enrichment provider.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/enrich/auto`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"requestBody":{"description":"Which leads to enrich.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["leadIds"],"properties":{"leadIds":{"type":"array","items":{"type":"string"},"description":"Lead ids to enrich.","example":["LEAD-4821","LEAD-4822"]}}},"example":{"leadIds":["LEAD-4821","LEAD-4822"]}}}},"responses":{"201":{"description":"Per-lead enrichment results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/enrichment/status/{id}":{"get":{"operationId":"LeadsController_getLeadEnrichmentStatus","summary":"Get enrichment status","description":"Reports where a lead's enrichment has got to. Poll this after starting enrichment rather than assuming it completed synchronously.\n\n#### Signature\n\n```http\nGET /crm/leads/enrichment/status/{id} (id: string) -> The enrichment status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/enrich/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"responses":{"200":{"description":"The enrichment status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/enrichment/status/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/enrich/auto":{"post":{"operationId":"LeadsController_autoEnrichLeads","summary":"Enrich leads automatically","description":"Runs enrichment across leads that qualify for it automatically, rather than naming them individually. Like the batch form, this can incur per-lead provider costs.\n\n#### Signature\n\n```http\nPOST /crm/leads/enrich/auto (limit?: string, body) -> The enrichment result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Selects leads on its own — check what it would touch before running it on a large org.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/enrich/batch`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"limit","required":false,"in":"query","description":"Maximum rows.","schema":{"type":"string"}},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"responses":{"201":{"description":"The enrichment result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"],"requestBody":{"description":"Optional enrichment settings.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/crm/leads/enrich/{id}":{"post":{"operationId":"LeadsController_enrichLead","summary":"Enrich a lead","description":"Fills in missing detail on a lead from external data sources — the counterpart to the deliberately thin creation rules. Capture what you have, then enrich.\n\n#### Signature\n\n```http\nPOST /crm/leads/enrich/{id} (id: string) -> The enrichment result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Enrichment may run asynchronously — poll `GET /crm/leads/enrichment/status/{id}` rather than assuming the response is final.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/leads/enrichment/status/{id}`\n- `POST /crm/leads/enrich/batch`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"},{"name":"orgId","required":true,"in":"query","description":"Organization ID","schema":{}}],"responses":{"201":{"description":"The enrichment result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/enrich/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/pipelines":{"post":{"operationId":"LeadsController_createPipeline","summary":"Create a lead pipeline","description":"Creates a pipeline — the ordered stages a lead moves through. Stages can be added, reordered and removed afterwards.\n\n#### Signature\n\n```http\nPOST /crm/leads/pipelines (body) -> The created pipeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | OPERATION_FAILED | Failed to create pipeline | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `POST /crm/leads/pipelines/stages/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The pipeline to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Initial stages, in order."}}},"example":{"name":"Inbound sales","stages":[{"name":"New"},{"name":"Contacted"},{"name":"Demo booked"}]}}}},"responses":{"201":{"description":"The created pipeline","content":{"application/json":{"schema":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to create pipeline — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to create pipeline","path":"/crm/leads/pipelines","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Pipelines"]},"get":{"operationId":"LeadsController_getPipelines","summary":"List lead pipelines","description":"All lead pipelines in the org, with their stages.\n\n#### Signature\n\n```http\nGET /crm/leads/pipelines () -> The org's pipelines\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | OPERATION_FAILED | Failed to retrieve pipelines | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /crm/leads/pipelines/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The org's pipelines","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to retrieve pipelines — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to retrieve pipelines","path":"/crm/leads/pipelines","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Pipelines"]}},"/crm/leads/pipelines/default":{"get":{"operationId":"LeadsController_getDefaultPipeline","summary":"Get the default pipeline","description":"Returns the pipeline new leads land on when none is given and the board opens on: the pipeline marked isDefault, else the one holding the most leads, else the first. 404 when the organization has no pipeline.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM - Leads"]}},"/crm/leads/pipelines/{id}":{"get":{"operationId":"LeadsController_getPipeline","summary":"Get a lead pipeline","description":"Fetches one pipeline with its ordered stages.\n\n#### Signature\n\n```http\nGET /crm/leads/pipelines/{id} (id: string) -> The pipeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n| `500` | OPERATION_FAILED | Failed to retrieve pipeline | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /crm/leads/pipelines/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"}],"responses":{"200":{"description":"The pipeline","content":{"application/json":{"schema":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to retrieve pipeline — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to retrieve pipeline","path":"/crm/leads/pipelines/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Pipelines"]},"put":{"operationId":"LeadsController_updatePipeline","summary":"Update a lead pipeline","description":"Updates a pipeline's own fields. Use the stage endpoints to change its stages.\n\n#### Signature\n\n```http\nPUT /crm/leads/pipelines/{id} (id: string, body) -> The updated pipeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n| `500` | OPERATION_FAILED | Failed to update pipeline | An unexpected failure in the leads service. | Retry with backoff. The message is fixed text and does not indicate what went wrong. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `PUT /crm/leads/pipelines/stages/{id}/{stageId}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Inbound sales (EMEA)"}}}},"responses":{"200":{"description":"The updated pipeline","content":{"application/json":{"schema":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to update pipeline — An unexpected failure in the leads service.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to update pipeline","path":"/crm/leads/pipelines/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["CRM · Pipelines"]},"delete":{"operationId":"LeadsController_deletePipeline","summary":"Delete a lead pipeline","description":"Deletes a pipeline. **A pipeline still holding leads cannot be deleted** — move or delete those leads first, so none are left pointing at a stage that no longer exists.\n\n#### Signature\n\n```http\nDELETE /crm/leads/pipelines/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n| `400` | PIPELINE_IN_USE | Cannot delete pipeline with existing leads | Leads are still assigned to this pipeline. | Move the leads to another pipeline first, or delete them. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/leads/detail`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Cannot delete pipeline with existing leads — Leads are still assigned to this pipeline.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Cannot delete pipeline with existing leads","path":"/crm/leads/pipelines/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Pipelines"]}},"/crm/leads/pipelines/{id}/route-unassigned":{"post":{"operationId":"LeadsController_routeUnassignedInPipeline","summary":"Route unassigned leads in a pipeline","description":"Distributes the pipeline's unassigned leads across owners according to its routing rules — the bulk alternative to assigning them one at a time.\n\n#### Signature\n\n```http\nPOST /crm/leads/pipelines/{id}/route-unassigned (id: string) -> The routing result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/assign/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"}],"responses":{"201":{"description":"The routing result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/{id}/route-unassigned","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Pipelines"]}},"/crm/leads/pipelines/stages/{id}":{"post":{"operationId":"LeadsController_addPipelineStage","summary":"Add a stage to a pipeline","description":"Appends a stage to a pipeline. Use the reorder endpoint to place it somewhere other than the end.\n\n#### Signature\n\n```http\nPOST /crm/leads/pipelines/stages/{id} (id: string, body) -> The updated pipeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/leads/pipelines/stages/reorder/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"}],"requestBody":{"description":"The stage to add.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Proposal sent"}}},"example":{"name":"Proposal sent"}}}},"responses":{"201":{"description":"The updated pipeline","content":{"application/json":{"schema":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/stages/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Pipelines"]}},"/crm/leads/pipelines/stages/{id}/{stageId}":{"put":{"operationId":"LeadsController_updatePipelineStage","summary":"Update a pipeline stage","description":"Updates one stage within a pipeline.\n\n#### Signature\n\n```http\nPUT /crm/leads/pipelines/stages/{id}/{stageId} (id: string, stageId: string, body) -> The updated pipeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/leads/pipelines/stages/{id}/{stageId}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"},{"name":"stageId","required":true,"in":"path","description":"Stage id within the pipeline.","schema":{"type":"string"},"example":"STG-2"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Proposal sent (v2)"}}}},"responses":{"200":{"description":"The updated pipeline","content":{"application/json":{"schema":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/stages/{id}/{stageId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Pipelines"]},"delete":{"operationId":"LeadsController_deletePipelineStage","summary":"Delete a pipeline stage","description":"Removes a stage from a pipeline. Move any leads sitting in it first — nothing here relocates them, and a lead pointing at a deleted stage falls out of the board.\n\n#### Signature\n\n```http\nDELETE /crm/leads/pipelines/stages/{id}/{stageId} (id: string, stageId: string) -> The updated pipeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Leads in the deleted stage are not moved — check the stage is empty first.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/leads/pipelines/stages/reorder/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"},{"name":"stageId","required":true,"in":"path","description":"Stage id within the pipeline.","schema":{"type":"string"},"example":"STG-2"}],"responses":{"200":{"description":"The updated pipeline","content":{"application/json":{"schema":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/stages/{id}/{stageId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Pipelines"]}},"/crm/leads/pipelines/stages/reorder/{id}":{"put":{"operationId":"LeadsController_reorderPipelineStages","summary":"Reorder pipeline stages","description":"Changes the order of a pipeline's stages. Send the stage ids in the order you want them.\n\n#### Signature\n\n```http\nPUT /crm/leads/pipelines/stages/reorder/{id} (id: string, body) -> The reordered pipeline\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Send every stage — an omitted one may lose its position.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PIPELINE_NOT_FOUND | Pipeline not found | No pipeline in the org has that id. | List pipelines with `GET /crm/leads/pipelines`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/pipelines/stages/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Pipeline id.","schema":{"type":"string"},"example":"PIPE-4821"}],"requestBody":{"description":"The stages in their new order.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"stageIds":{"type":"array","items":{"type":"string"},"description":"Stage ids in the intended order.","example":["STG-1","STG-3","STG-2"]}}},"example":{"stageIds":["STG-1","STG-3","STG-2"]}}}},"responses":{"200":{"description":"The reordered pipeline","content":{"application/json":{"schema":{"type":"object","description":"A lead pipeline.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"Inbound sales"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Ordered stages."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Pipeline not found — No pipeline in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Pipeline not found","path":"/crm/leads/pipelines/stages/reorder/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Pipelines"]}},"/crm/leads/activities/{id}":{"post":{"operationId":"LeadsController_addActivity","summary":"Add an activity to a lead","description":"Records something that happened with a lead — a call, an email, a meeting. This is the interaction history a salesperson reads before picking up the phone.\n\n#### Signature\n\n```http\nPOST /crm/leads/activities/{id} (id: string, body) -> The recorded activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/leads/activities/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"}],"requestBody":{"description":"The activity to record.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"type":{"type":"string","description":"What kind of interaction.","example":"call"},"notes":{"type":"string","example":"Discussed pricing, sending a proposal"},"date":{"type":"string","format":"date-time"}}},"example":{"type":"call","notes":"Discussed pricing, sending a proposal","date":"2026-08-29T14:00:00.000Z"}}}},"responses":{"201":{"description":"The recorded activity","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/activities/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]},"get":{"operationId":"LeadsController_getActivities","summary":"Get a lead's activities","description":"The full interaction history for a lead.\n\n#### Signature\n\n```http\nGET /crm/leads/activities/{id} (id: string) -> The lead's activities\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/activities/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"}],"responses":{"200":{"description":"The lead's activities","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/activities/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/score/{id}":{"post":{"operationId":"LeadsController_calculateScore","summary":"Calculate a lead score","description":"Scores one lead. Pass a rules array to score against specific criteria, or omit it to use the org's configured rules.\n\n#### Signature\n\n```http\nPOST /crm/leads/score/{id} (id: string, body) -> The lead with its computed score\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The body is a bare array, not an object wrapping one.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | LEAD_NOT_FOUND | Lead not found | No lead in the org has that id. | Check the id with `GET /crm/leads/detail`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/score/batch`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Lead id.","schema":{"type":"string"},"example":"LEAD-4821"}],"requestBody":{"description":"Scoring rules. Omit to use the configured ones.","required":false,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Rules to score against."},"example":[{"field":"company","condition":"exists","points":10}]}}},"responses":{"201":{"description":"The lead with its computed score","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lead not found — No lead in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Lead not found","path":"/crm/leads/score/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/score/batch":{"post":{"operationId":"LeadsController_batchCalculateScores","summary":"Score all leads","description":"Recomputes scores across **every** lead in the org. Run it after changing scoring rules; it is a heavy operation, not something to call per page view.\n\n#### Signature\n\n```http\nPOST /crm/leads/score/batch (body) -> The batch scoring result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Touches every lead in the org — treat it as an administrative operation.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/score/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Scoring rules. Omit to use the configured ones.","required":false,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}},"example":[{"field":"company","condition":"exists","points":10}]}}},"responses":{"201":{"description":"The batch scoring result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/import/facebook":{"post":{"operationId":"LeadsController_importFromFacebook","summary":"Import leads from Facebook","description":"Queues a sync of Facebook lead-ad submissions into the CRM.\n\n**The work is queued, not performed.** The response confirms the job was accepted — `{ success: true, message: \"Facebook lead sync queued\" }` — and says nothing about how many leads arrived. Check the lead list afterwards.\n\n#### Signature\n\n```http\nPOST /crm/leads/import/facebook (body) -> Confirmation that the sync was queued\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Asynchronous — a `200` means queued, not imported.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/import/contacts`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Optional import settings.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}},"responses":{"200":{"description":"Facebook leads imported successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"leadsImported":{"type":"number"},"details":{"type":"array"}}}}}},"201":{"description":"Confirmation that the sync was queued","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Facebook lead sync queued"}}},"example":{"success":true,"message":"Facebook lead sync queued"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/import/contacts":{"post":{"operationId":"LeadsController_importFromContacts","summary":"Import leads from contacts","description":"Turns existing CRM contacts into leads, optionally dropping them straight into a pipeline stage.\n\nSet `skipDuplicates` to leave contacts that are already leads alone — without it, importing the same contacts twice can produce duplicates.\n\n#### Signature\n\n```http\nPOST /crm/leads/import/contacts (body) -> The import result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Omitting `contactIds` imports every contact — check the scope before running it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/bulk-import/contacts`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"Which contacts to import, and where to put them.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string"},"description":"Contacts to import. Omit to import all.","example":["cus_4821"]},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-1"},"source":{"type":"string","description":"Recorded as the lead source.","example":"contact-import"},"skipDuplicates":{"type":"boolean","default":false,"description":"Skip contacts that are already leads.","example":true}}},"example":{"contactIds":["cus_4821","cus_4822"],"pipelineId":"PIPE-4821","stageId":"STG-1","source":"contact-import","skipDuplicates":true}}}},"responses":{"201":{"description":"The import result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/convert/contact/{contactId}":{"post":{"operationId":"LeadsController_convertContactToLead","summary":"Convert one contact into a lead","description":"Creates a lead from a single existing contact — the one-at-a-time counterpart to the import endpoints, for when someone in the contact book turns into an opportunity.\n\n#### Signature\n\n```http\nPOST /crm/leads/convert/contact/{contactId} (contactId: string, body) -> The created lead\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/import/contacts`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"contactId","required":true,"in":"path","description":"Contact id.","schema":{"type":"string"},"example":"cus_4821"}],"requestBody":{"description":"Where to place the new lead.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-1"},"source":{"type":"string","example":"referral"}}},"example":{"pipelineId":"PIPE-4821","stageId":"STG-1","source":"referral"}}}},"responses":{"201":{"description":"The created lead","content":{"application/json":{"schema":{"type":"object","description":"A lead (`crm_lead`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","description":"Validated **only when supplied** — a lead may have none.","example":"ada@example.com"},"phone":{"type":"string","example":"+15551234567"},"company":{"type":"string","example":"Analytical Engines Ltd"},"status":{"type":"string","enum":["new","contacted","qualified","disqualified","converted"],"description":"Defaults to `new` when not supplied.","example":"new"},"priority":{"type":"string","description":"Lead priority.","example":"high"},"source":{"type":"string","description":"Where the lead came from.","example":"facebook"},"assignedTo":{"type":"string","description":"User the lead is assigned to.","example":"sales@acme.com"},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-2"},"score":{"type":"number","description":"Computed by the scoring endpoints.","example":72},"conversionValue":{"type":"number","description":"Recorded at conversion.","example":4500},"followUpDate":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/leads/bulk-import/contacts":{"post":{"operationId":"LeadsController_bulkImportContacts","summary":"Bulk import contacts as leads","description":"The bulk form of the contact import, for larger sets. `contactIds` is required here rather than optional, so it cannot accidentally import the whole contact book.\n\n#### Signature\n\n```http\nPOST /crm/leads/bulk-import/contacts (body) -> The import result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/leads/import/contacts`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The contacts to import.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["contactIds"],"properties":{"contactIds":{"type":"array","items":{"type":"string"},"description":"Contacts to import. Required.","example":["cus_4821","cus_4822"]},"pipelineId":{"type":"string","example":"PIPE-4821"},"stageId":{"type":"string","example":"STG-1"},"source":{"type":"string","example":"contact-import"}}},"example":{"contactIds":["cus_4821","cus_4822"],"pipelineId":"PIPE-4821","stageId":"STG-1"}}}},"responses":{"201":{"description":"The import result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Leads"]}},"/crm/events/get/{id}":{"get":{"operationId":"EventsController_getEvents","summary":"Get CRM events","description":"Fetches one CRM event by id, or lists them when the segment is omitted.\n\n#### Signature\n\n```http\nGET /crm/events/get/{id} (id: string) -> Events\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/events/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Event id. Omit to list.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Events"]}},"/crm/events/delete/{id}":{"delete":{"operationId":"EventsController_deleteEvent","summary":"Delete a CRM event","description":"Deletes a CRM event.\n\n#### Signature\n\n```http\nDELETE /crm/events/delete/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/events/get/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Record id.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Events"]}},"/crm/events/create":{"post":{"operationId":"EventsController_createEvent","summary":"Create a CRM event","description":"Creates an event as a draft (publish separately). `data.title` and `data.startTime` (ISO date-time, in the future) are required; `data.endTime` is when it ends. The server sets the event number, `name`, `slug` (from the title), status `draft`, and `startDate` / `endDate` from the times. Fields may be sent flat or under `data`. Attendees in `data.attendees[]` are emailed an invitation.\n\n#### Signature\n\n```http\nPOST /crm/events/create (body) -> The created event\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/events/update`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The event to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"data":{"title":"Quarterly customer webinar","type":"webinar","startTime":"2026-11-14T10:00:00-06:00","endTime":"2026-11-14T14:00:00-06:00","timezone":"America/Chicago"}}}}},"responses":{"201":{"description":"The created event","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Events"]}},"/crm/events/update":{"post":{"operationId":"EventsController_updateEvent","summary":"Update a CRM event","description":"Updates an existing CRM event. Include its `sk`.\n\n#### Signature\n\n```http\nPOST /crm/events/update (body) -> The updated event\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/events/delete/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The event to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sk":"66f1a2b3c4d5e6f708192a3b","data":{"title":"Quarterly customer webinar (rescheduled)"}}}}},"responses":{"201":{"description":"The updated event","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Events"]}},"/crm/reservations/definitions":{"get":{"operationId":"ReservationsController_getReservationDefinitions","summary":"Get reservation definitions","description":"The reservation types the org offers, with their schemas — read this to build a booking form generically rather than hard-coding appointment types.\n\n#### Signature\n\n```http\nGET /crm/reservations/definitions () -> Reservation definitions\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/slots`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Reservation definitions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/definitions","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/slots":{"post":{"operationId":"ReservationsController_generateAppointmentSlots","summary":"Generate appointment slots","description":"Computes the bookable slots for a period from the service point's availability and existing reservations.\n\nSlots are calculated, not reserved — one returned here can be taken by someone else before you book it.\n\nThe definition record must be datatype **`reservation_definition`**. Creating it as `crm_reservation_definition` succeeds and then every slot request answers \"Reservation Definition not found\", because the generator looks in the other collection.\n\nSlot times come back in UTC with `businessTimezone` alongside. Format for display in the business timezone, not the visitor's — a customer abroad shown their own local time books an appointment nobody turns up to.\n\n#### Signature\n\n```http\nPOST /crm/reservations/slots (body) -> An object containing the selected reservationDefinition and service, and a slots array. Closed or inactive definitions return an empty slots array with an explanatory flag.\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- No hold is placed. Handle the race between showing a slot and booking it.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The criteria to generate slots for.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["reservationDefinitionId","serviceDate"],"properties":{"reservationDefinitionId":{"type":"string","description":"REQUIRED — the `sk` of a `reservation_definition` record. Omitting it fails with 400 \"reservationDefinitionId required.\"","example":"6aa798c44f3cf920a2c64b07"},"serviceName":{"type":"string","description":"Must match a `services[].name` on the definition. Defaults to the first service.","example":"consultation"},"serviceDate":{"type":"string","description":"REQUIRED — the day to generate slots for.","example":"2026-09-16"},"slotIncrementMinutes":{"type":"integer","description":"Interval increment when the definition uses interval slot generation; duration and buffer come from its configured service.","example":5},"startDate":{"type":"string","description":"Legacy alias for serviceDate; prefer serviceDate as the business-local calendar day.","example":"2026-10-22"}}},"example":{"reservationDefinitionId":"6acb4561d685f653775b8772","serviceName":"Room planning","serviceDate":"2026-10-22"}}}},"responses":{"201":{"description":"An object containing the selected reservationDefinition and service, and a slots array. Closed or inactive definitions return an empty slots array with an explanatory flag.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"slots":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/by-email/{email}/{reservationNumber}":{"get":{"operationId":"ReservationsController_getReservationByEmail","summary":"Get reservations by email","description":"A customer's reservations, keyed on their email address rather than an account — the self-service \"my bookings\" read.\n\n#### Signature\n\n```http\nGET /crm/reservations/by-email/{email}/{reservationNumber} (email: string, reservationNumber: string) -> The customer's reservations\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Keyed on email alone.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/reservations/cancel/{email}/{reservationNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"reservationNumber","required":true,"in":"path","description":"Reservation number. Omit to list all for the email.","schema":{"type":"string"},"example":"RES-4821"},{"name":"email","required":true,"in":"path","description":"Customer email address.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"The customer's reservations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A reservation (`reservation`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"reservationNumber":{"type":"string","example":"RES-4821"},"email":{"type":"string","example":"ada@example.com"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"servicePointId":{"type":"string","example":"sp_t7"},"status":{"type":"string","example":"confirmed"}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/cancel/{email}/{reservationNumber}":{"delete":{"operationId":"ReservationsController_cancelReservationEntry","summary":"Cancel a reservation","description":"Cancels a customer's reservation, matched on both email and reservation number so one alone is not enough. Prefer this to deletion — it frees the slot while keeping the record.\n\n#### Signature\n\n```http\nDELETE /crm/reservations/cancel/{email}/{reservationNumber} (email: string, reservationNumber: string) -> Cancellation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/reservations/delete/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"reservationNumber","required":true,"in":"path","description":"Reservation number.","schema":{"type":"string"},"example":"RES-4821"},{"name":"email","required":true,"in":"path","description":"Customer email address.","schema":{"type":"string"},"example":"ada@example.com"}],"responses":{"200":{"description":"Cancellation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/cancel/{id}":{"post":{"operationId":"ReservationsController_cancelReservationByStaff","summary":"Cancel reservation (staff)","description":"Staff only. Cancels a booking by id. Body: reason? — kept as cancelReason; notify? (default true) — false cancels silently, nothing sent. Same effects as the customer cancel: status cancelled, cancelledAt/cancelledBy (the signed-in staff member) stamped, scheduled reminders removed, cancellation notice sent.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Reservation ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/{id}/attended":{"post":{"operationId":"ReservationsController_markAttended","summary":"Mark attended (staff)","description":"Staff only. The session took place: status used, usedAt and attendedBy (the signed-in staff member) stamped — no service point needed. From new, pending, confirmed or rescheduled; a cancelled or no-show booking answers 409 (reason \"not_attendable\"). Returns the booking.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Reservation ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/{id}/archive":{"post":{"operationId":"ReservationsController_archiveReservation","summary":"Archive or unarchive a booking (staff)","description":"Staff only. Takes the booking off the Reservations board (body archived: true, the default) or puts it back (archived: false). The booking state becomes archived (archivedAt, archivedBy and the state it had are kept); putting it back restores that state. Status, reminders and the customer are untouched: nothing is sent. Returns the booking.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Reservation ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/mine":{"get":{"operationId":"ReservationsController_getMyHostedReservations","summary":"My hosted bookings","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Paged reservations (`{ data, total }`)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized — No signed-in user.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/mine","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"],"description":"Reservations the signed-in staff member hosts — directly, or through a service they host. Up to 1000.\n\n#### Signature\n\n```http\nGET /crm/reservations/mine () -> Paged reservations (`{ data, total }`)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in user. | — |\n\nPlus the standard platform errors: `403`, `429`, `500`."}},"/crm/reservations/get/{id}":{"get":{"operationId":"ReservationsController_getReservationEntries","summary":"Get reservations","description":"Fetches one reservation by id, or lists them when the segment is omitted.\n\n#### Signature\n\n```http\nGET /crm/reservations/get/{id} (id: string) -> The reservation, or all reservations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/reservations/by-email/{email}/{reservationNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Reservation id. Omit to list.","schema":{"type":"string"},"example":"RES-4821"}],"responses":{"200":{"description":"The reservation, or all reservations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A reservation (`reservation`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"reservationNumber":{"type":"string","example":"RES-4821"},"email":{"type":"string","example":"ada@example.com"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"servicePointId":{"type":"string","example":"sp_t7"},"status":{"type":"string","example":"confirmed"}}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/get/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/delete/{id}":{"delete":{"operationId":"ReservationsController_deleteReservationEntry","summary":"Delete a reservation","description":"Deletes a reservation outright. Cancelling instead keeps the record and notifies the customer.\n\n#### Signature\n\n```http\nDELETE /crm/reservations/delete/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/reservations/cancel/{email}/{reservationNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Reservation id.","schema":{"type":"string"},"example":"RES-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/delete/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/create":{"post":{"operationId":"ReservationsController_createReservationEntry","summary":"Create a reservation","description":"Books a reservation. Availability is not held between generating slots and creating one, so a slot can be lost in between — handle a conflict on create.\n\n#### Signature\n\n```http\nPOST /crm/reservations/create (body) -> The created reservation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The `reservation_definition` it books against needs `workDays` as CAPITALISED full day names — `[\"Monday\",\"Tuesday\"]`. Lower-case or abbreviated names match nothing and that day silently generates no slots.\n- REQUIRES AUTH, unlike the rest of the booking flow. `definitions`, `slots`, `by-email` and `cancel` all answer anonymously; this returns 401 without a credential. A public page can therefore SHOW availability but cannot take a booking — call it through the browser runtime on a hosted page, or through your own server. Never by putting an operator token in a page.\n- Pass the slot's `startTime` and `endTime` back exactly as `slots` returned them. Rebuilding them from a local Date reintroduces the timezone the generator already resolved, and the booking lands an hour out twice a year.\n- A customer record is created from the `customer` object when the email is new, and reused when it is not.\n- Confirmation email is billed. An org without credit still books the reservation and sends nothing.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/update`\n- `POST /crm/reservations/slots`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The reservation to create.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"string","example":"ada@example.com"},"servicePointId":{"type":"string","example":"sp_t7"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}}}}},"example":{"data":{"email":"ada@example.com","servicePointId":"sp_t7","startDate":"2026-09-01T10:00:00.000Z","endDate":"2026-09-01T10:30:00.000Z"}}}}},"responses":{"201":{"description":"The created reservation","content":{"application/json":{"schema":{"type":"object","description":"A reservation (`reservation`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"reservationNumber":{"type":"string","example":"RES-4821"},"email":{"type":"string","example":"ada@example.com"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"servicePointId":{"type":"string","example":"sp_t7"},"status":{"type":"string","example":"confirmed"}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/book":{"post":{"operationId":"ReservationsController_bookFromSite","summary":"Book from the website","description":"A visitor books a slot without signing in. The contact details on the booking become its customer, and this device is linked to them.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/update":{"post":{"operationId":"ReservationsController_updateReservationEntry","summary":"Update a reservation","description":"Updates a reservation's details — customer, party size, notes, status. Include the record `sk`. To move it to another time use `POST /crm/reservations/reschedule/{id}`.\n\n#### Signature\n\n```http\nPOST /crm/reservations/update (body) -> The updated reservation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A time sent here by staff is saved as given — no capacity check, no record of the old time, and the customer gets the generic \"updated\" message. Reschedule instead.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/reschedule/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The reservation to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sk":"66f1a2b3c4d5e6f708192a3b","data":{"startDate":"2026-09-02T10:00:00.000Z"}}}}},"responses":{"201":{"description":"The updated reservation","content":{"application/json":{"schema":{"type":"object","description":"A reservation (`reservation`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"reservationNumber":{"type":"string","example":"RES-4821"},"email":{"type":"string","example":"ada@example.com"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"servicePointId":{"type":"string","example":"sp_t7"},"status":{"type":"string","example":"confirmed"}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/availability":{"post":{"operationId":"ReservationsController_getAvailability","summary":"Availability across a run of days","description":"What is open for a service over up to 31 days, in one call — the question a caller asks (\"anything Friday or Saturday?\").\n\nUnlike `slots`, full slots are returned too (`spotsAvailable: 0`), so a screen can show the shape of each day rather than a list with holes in it. A slot already past, or inside a blocked time, is not a slot and is left out. A day outside `workDays` comes back `closed: true` with no slots.\n\nCapacity is the definition's `spots`: how many bookings one slot holds. Any live booking that overlaps the slot at all takes a spot.\n\nTimes are UTC; format them in the returned `timezone` (the business's), not the viewer's.\n\n#### Signature\n\n```http\nPOST /crm/reservations/availability (body) -> Per-day slots, plus the first open one\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- No hold is placed. Handle the race between showing a slot and booking it.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/reschedule/{id}`\n- `POST /crm/reservations/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Per-day slots, plus the first open one","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reservationDefinitionId":"6aa798c44f3cf920a2c64b07","service":{"name":"consultation","duration":30,"price":0},"timezone":"America/New_York","from":"2026-09-21","to":"2026-09-27","nextAvailable":{"date":"2026-09-21","startTime":"2026-09-21T18:00:00.000Z","endTime":"2026-09-21T18:30:00.000Z","spotsTotal":2,"spotsAvailable":1},"days":[{"date":"2026-09-21","weekday":"Monday","closed":false,"openSlots":5,"slots":[{"startTime":"2026-09-21T18:00:00.000Z","endTime":"2026-09-21T18:30:00.000Z","spotsTotal":2,"spotsAvailable":1}]}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"],"requestBody":{"description":"What to look for.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reservationDefinitionId"],"properties":{"reservationDefinitionId":{"type":"string","description":"REQUIRED — the `sk` of a `reservation_definition` record.","example":"6aa798c44f3cf920a2c64b07"},"serviceName":{"type":"string","description":"A `services[].name` on the definition. Defaults to the first service.","example":"consultation"},"from":{"type":"string","description":"First day, as a calendar date at the business. Defaults to today; a past date is read as today.","example":"2026-09-21"},"days":{"type":"integer","description":"How many days, 1–31. Default 7.","example":7},"excludeReservationId":{"type":"string","description":"When moving a booking: its `sk`, so the seat it already holds reads as free.","example":"66f1a2b3c4d5e6f708192a3b"},"slotIncrementMinutes":{"type":"integer","description":"Interval-mode definitions only. Default 5.","example":15}}},"example":{"reservationDefinitionId":"6aa798c44f3cf920a2c64b07","serviceName":"consultation","from":"2026-09-21","days":7}}}}}},"/crm/reservations/stats":{"get":{"operationId":"ReservationsController_getReservationStats","summary":"Reservation figures","description":"Header figures for the Reservations screen, computed on the server: `total`, `today` (bookings on the current day in each booking's own business timezone), `upcoming` (live bookings still ahead) and `revenue` (sum of live bookings' price). Cancelled and no-show bookings count toward neither upcoming nor revenue. Staff only: a customer credential answers 401.\n\n#### Signature\n\n```http\nGET /crm/reservations/stats ()\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":""},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/slot-bookings":{"post":{"operationId":"ReservationsController_getSlotBookings","summary":"Bookings in a slot","description":"Who holds a slot — the live bookings that overlap the given time, earliest first, with the slot's capacity. Staff only: it names customers, so a customer credential answers 401.\n\n#### Signature\n\n```http\nPOST /crm/reservations/slot-bookings (body) -> `{ spotsTotal, spotsAvailable, bookings[] }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/availability`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"`{ spotsTotal, spotsAvailable, bookings[] }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/slot-bookings","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"],"requestBody":{"description":"The slot, as `availability` returned it.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reservationDefinitionId","startTime","endTime"],"properties":{"reservationDefinitionId":{"type":"string","example":"6aa798c44f3cf920a2c64b07"},"startTime":{"type":"string","format":"date-time","example":"2026-09-25T22:30:00.000Z"},"endTime":{"type":"string","format":"date-time","example":"2026-09-25T23:00:00.000Z"}}},"example":{"reservationDefinitionId":"6aa798c44f3cf920a2c64b07","startTime":"2026-09-25T22:30:00.000Z","endTime":"2026-09-25T23:00:00.000Z"}}}}}},"/crm/reservations/reschedule/{email}/{reservationNumber}":{"post":{"operationId":"ReservationsController_rescheduleReservationByEmail","summary":"Reschedule reservation by email","description":"The customer moves their own booking, found like the customer cancel: by the email (or phone) on it and its reservation number. Body: startTime, service?, reason?. Same checks as a reschedule; answers 409 with reason \"slot_unavailable\" and problems[] when the time cannot take it.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"email","required":true,"in":"path","description":"Customer email","schema":{"type":"string"}},{"name":"reservationNumber","required":true,"in":"path","description":"Reservation number","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/reschedule/{id}":{"post":{"operationId":"ReservationsController_rescheduleReservationEntry","summary":"Reschedule a reservation","description":"Moves a booking to another time. The end time is derived — the booking keeps its length, or takes the new service's duration when `service` changes with the move.\n\nThe new time is checked: not past, inside opening hours on a working day, not blocked, and with a spot free (the booking's own seat does not count against it). The move is appended to `data.rescheduleHistory` (from/to, when, who, reason), the customer is sent `reservation-rescheduled` showing old → new with a fresh calendar invite, and the reminders are re-cut for the new time.\n\nThe status is not changed — a moved booking is still pending or confirmed.\n\n#### Signature\n\n```http\nPOST /crm/reservations/reschedule/{id} (id: string, body) -> The moved reservation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A time that cannot take the booking answers 409 with `reason: \"slot_unavailable\"`, `problems: [{ code, message }]` (codes: `past`, `closed`, `outside_hours`, `blocked`, `full`) and `canOverride`. Show the message; staff may resend with `override: true`.\n- A customer may only move their own booking; anyone else's answers 404.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/availability`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Reservation `sk`.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The moved reservation","content":{"application/json":{"schema":{"type":"object","description":"A reservation (`reservation`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"reservationNumber":{"type":"string","example":"RES-4821"},"email":{"type":"string","example":"ada@example.com"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"servicePointId":{"type":"string","example":"sp_t7"},"status":{"type":"string","example":"confirmed"}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/reservations/reschedule/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"],"requestBody":{"description":"Where to move it.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["startTime"],"properties":{"startTime":{"type":"string","format":"date-time","description":"REQUIRED — pass a slot's `startTime` back exactly as `availability` returned it.","example":"2026-09-25T22:30:00.000Z"},"service":{"type":"string","description":"Change the service with the move.","example":"consultation"},"reason":{"type":"string","description":"Shown to the customer and kept on the history entry.","example":"Customer called — running late from work"},"notify":{"type":"boolean","description":"Default true. False moves it silently.","example":true},"override":{"type":"boolean","description":"Staff only. Place the booking even though the time is full, blocked, closed or past. Ignored for a customer.","example":false}}},"example":{"startTime":"2026-09-25T22:30:00.000Z","reason":"Customer called — running late from work"}}}}}},"/crm/reservations/waitlist":{"post":{"operationId":"ReservationsController_joinWaitlist","summary":"Join the waitlist for a day","description":"A full day or class: ask to be told when a time opens. Body: reservationDefinitionId, date (YYYY-MM-DD in the business zone), service?, host?, customer { name, email?, phone? } (a signed-in customer is used as is). Saved as a reservation in status \"waitlist\", which holds no time; when a booking of that type on that day is cancelled, everyone waiting is emailed and texted. Leave it with the customer cancel.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/membership-cover":{"get":{"operationId":"ReservationsController_membershipCover","summary":"Would my membership cover this class?","description":"Query: typeId. { covered, plan, title, left (null = unlimited), dropIn, classType }. Signed out, or no membership with places left: covered false, and the drop-in price is paid at booking.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"typeId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings":{"get":{"operationId":"ReservationsController_teamBookings","summary":"My calendar (team)","description":"Query: from? (YYYY-MM-DD, business zone, default today), days? (1–62, default 7). Returns { me, timezone, types, bookings } — bookings with the client, intake, team notes, charges, policy; blocks have data.kind \"block\"; waitlist requests have status \"waitlist\".","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"from","required":true,"in":"query","schema":{"type":"string"}},{"name":"days","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Reservations"]},"post":{"operationId":"ReservationsController_teamCreateBooking","summary":"Book a client in (team)","description":"A walk-in or phone booking with me. Body: reservationDefinitionId, service?, startTime? (now when walkIn), walkIn?, customer { name, email?, phone? }, notes?, intake? (the trade questions, as an online booking keeps them). Confirmed on the spot, paid at check-out.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings/{id}":{"get":{"operationId":"ReservationsController_teamBooking","summary":"One of my bookings (team)","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings/{id}/status":{"post":{"operationId":"ReservationsController_teamSetStatus","summary":"Confirm, check in, no-show or cancel (team)","description":"Body: status (confirmed | used | no_show | cancelled), reason?, waiveFee? (no-show). A no-show carries the type's no-show fee; a team cancel refunds what was paid up front.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings/{id}/reschedule":{"post":{"operationId":"ReservationsController_teamReschedule","summary":"Move a booking or block (team)","description":"Body: startTime, service?, override? (place it into a closed or full time on my own calendar), notify? (default true).","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings/{id}/notes":{"post":{"operationId":"ReservationsController_teamNote","summary":"Add a team note to a booking (team)","description":"Body: text. Never shown to the client.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings/{id}/checkout":{"post":{"operationId":"ReservationsController_teamCheckout","summary":"Check out with a tip (team)","description":"Body: tip?, amount? (the bill, default the price), method (card | cash). Card raises one payment request (bill less what was paid up front, plus tip) paid through client-data/pay/:requestId; cash is recorded on the booking. Marks it attended.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/blocks":{"post":{"operationId":"ReservationsController_teamBlock","summary":"Block time or take time off (team)","description":"Body: startTime, endTime, label?, allDay? (startTime/endTime then are YYYY-MM-DD, both inclusive). Makes me busy in every type I host.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/blocks/{id}":{"delete":{"operationId":"ReservationsController_teamDeleteBlock","summary":"Remove a block (team)","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/clients":{"get":{"operationId":"ReservationsController_teamClients","summary":"My clients (team)","description":"Query: q? (name, email or phone), page?, pageSize? (default 50). Everyone booked with my types: { data: [{ key, name, email, phone, visits, lastVisit, nextVisit, noShows, spent }], total }. key opens GET team/clients/:key.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"q","required":true,"in":"query","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"string"}},{"name":"pageSize","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings/{id}/checkout/intent":{"post":{"operationId":"ReservationsController_teamCheckoutIntent","summary":"Take the check-out by card on my device (team)","description":"After POST team/bookings/:id/checkout (card): a Stripe PaymentIntent for what is owed, with the client as the payer. Returns { requestId, clientSecret, paymentIntentId, publishableKey, amount, currency }, or { alreadySettled }.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/bookings/{id}/checkout/confirm":{"post":{"operationId":"ReservationsController_teamCheckoutConfirm","summary":"Record the card check-out taken on my device (team)","description":"Body: paymentIntentId. Checked with Stripe and settled on the check-out request; the client is the payer and gets the receipt; I am recorded as takenBy.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/clients/{key}":{"get":{"operationId":"ReservationsController_teamClient","summary":"A client and their visits with me (team)","description":"Param: the client's email, phone or customer id.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/summary":{"get":{"operationId":"ReservationsController_teamSummary","summary":"My numbers (team)","description":"Query: from?, days? (default 30). Booked, completed, no-shows, cancellations, booked value, taken, owed, fees, tips, by service.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"from","required":true,"in":"query","schema":{"type":"string"}},{"name":"days","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/team/types/{id}":{"post":{"operationId":"ReservationsController_teamUpdateType","summary":"My hours on a booking type (team)","description":"Body: officeHours { startTime, endTime }?, workDays?, blockedTime [{ startTime, endTime, label }]?, services [{ name, duration?, price?, breakAfter?, enabled? }]? (only when I am its only host).","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Reservations"]}},"/crm/reservations/service-point/get/{id}":{"get":{"operationId":"ReservationsController_getServicePoints","summary":"Get service points","description":"The bookable service points — rooms, chairs, desks, staff. Omit `id` to list them all.\n\n#### Signature\n\n```http\nGET /crm/reservations/service-point/get/{id} (id: string) -> Service points\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/service-point/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":false,"in":"header","schema":{"type":"string"},"description":"Client context, used to tailor which service points are returned.","example":"kiosk/1.0"},{"name":"id","required":true,"in":"path","description":"Service point id. Omit to list.","schema":{"type":"string"},"example":"sp_t7"}],"responses":{"200":{"description":"Service points","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/service-point/delete/{id}":{"delete":{"operationId":"ReservationsController_deleteServicePoint","summary":"Delete a service point","description":"Deletes a service point. Reservations already booked against it are not moved or cancelled — check for them first, or they become unreachable.\n\n#### Signature\n\n```http\nDELETE /crm/reservations/service-point/delete/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Orphans any reservation still pointing at it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/reservations/service-point/get/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Service point id.","schema":{"type":"string"},"example":"sp_t7"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/service-point/create":{"post":{"operationId":"ReservationsController_createServicePoint","summary":"Create a service point","description":"Creates a bookable service point. A named bookable resource (chair, room, table). Booking slots come from the reservation definition (hours, services, spots), not from service points.\n\n#### Signature\n\n```http\nPOST /crm/reservations/service-point/create (body) -> The created service point\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/service-point/update`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The service point to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"data":{"name":"Consulting room 2","capacity":1}}}}},"responses":{"201":{"description":"The created service point","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/service-point/update":{"post":{"operationId":"ReservationsController_updateServicePoint","summary":"Update a service point","description":"Updates a service point. Changing its availability affects future slot generation but does not move reservations already booked against it.\n\n#### Signature\n\n```http\nPOST /crm/reservations/service-point/update (body) -> The updated service point\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Existing reservations are not revalidated against new availability rules.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/reservations/service-point/delete/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The service point to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sk":"66f1a2b3c4d5e6f708192a3b","data":{"name":"Consulting room 2 (accessible)"}}}}},"responses":{"201":{"description":"The updated service point","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/meeting/token":{"get":{"operationId":"ReservationsController_getMeetingToken","summary":"Get a meeting token","description":"Issues a token for the caller to join a video meeting. Staff get the host (moderator) token. Anyone else passes `meetingId` and must be the booker or an invitee of a booking whose meeting link is that room — signed in as that customer, or with `email` + `reservationNumber` — and gets a join-only token for that one room (403 otherwise). Tokens are short-lived — fetch one when joining rather than storing it.\n\n#### Signature\n\n```http\nGET /crm/reservations/meeting/token (meetingId?: string, email?: string, reservationNumber?: string) -> A meeting token\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- The token grants meeting access — treat it as a credential.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/meeting/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"meetingId","required":false,"in":"query","schema":{"type":"string"},"example":"abcd-efgh-ijkl"},{"name":"email","required":false,"in":"query","schema":{"type":"string"},"example":"ada@example.com"},{"name":"reservationNumber","required":false,"in":"query","schema":{"type":"string"},"example":"RES-4821"}],"responses":{"200":{"description":"A meeting token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/meeting/create":{"post":{"operationId":"ReservationsController_createMeeting","summary":"Create a meeting room","description":"Creates a video meeting room, typically for a reservation that is held remotely.\n\n#### Signature\n\n```http\nPOST /crm/reservations/meeting/create (body) -> The created meeting\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/reservations/meeting/validate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The meeting to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Consultation with Ada","reservationId":"RES-4821"}}}},"responses":{"201":{"description":"The created meeting","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/meeting/validate":{"post":{"operationId":"ReservationsController_validateMeeting","summary":"Validate a meeting","description":"Checks that a meeting exists and the caller may join it — the pre-flight before showing a join button.\n\n#### Signature\n\n```http\nPOST /crm/reservations/meeting/validate (body) -> Whether the meeting is valid and joinable\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/reservations/meeting/token`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The meeting to validate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"meetingId":"MTG-4821"}}}},"responses":{"201":{"description":"Whether the meeting is valid and joinable","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/reservations/send-reminder/{reservationId}":{"post":{"operationId":"ReservationsController_sendReservationReminder","summary":"Send a reservation reminder","description":"Sends the customer a reminder about an upcoming reservation. Sends on every call — there is no once-only guard, so repeated calls repeat the reminder.\n\n#### Signature\n\n```http\nPOST /crm/reservations/send-reminder/{reservationId} (reservationId: string) -> Dispatch result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/reservations/get/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"reservationId","required":true,"in":"path","description":"Reservation id.","schema":{"type":"string"},"example":"RES-4821"}],"requestBody":{"required":false,"description":"Notification details (optional - uses reservation definition notifications if not provided)","content":{"application/json":{"schema":{"type":"object","properties":{"notificationIndex":{"type":"number","description":"Index of notification to send from reservation definition (default: 0)"}}}}}},"responses":{"201":{"description":"Dispatch result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Reservations"]}},"/crm/tickets/chat-request":{"post":{"operationId":"TicketsController_createChatRequest","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"authorization","required":true,"in":"header","schema":{"type":"string"},"description":"Bearer guest token from the chat widget."}],"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A name, valid email, message and widget are required — The guest has no name or valid email, or `description` / `configId` is missing or too long.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A name, valid email, message and widget are required","path":"/crm/tickets/chat-request","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Guest authentication is required — No Bearer token (\"Guest authentication is invalid or expired\" when it does not verify).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Guest authentication is required","path":"/crm/tickets/chat-request","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This guest does not belong to this organization — The token is not a guest customer of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This guest does not belong to this organization","path":"/crm/tickets/chat-request","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"summary":"Leave a request from the chat widget","description":"For a chat widget that is away: turns the visitor's message into a ticket. Only a **guest** session token from the widget is accepted (`Authorization: Bearer <guest token>`, a guest customer of this org). Name, email and phone come from the guest session; the caller can only send `data.description` and `data.configId`, and the widget must have its away form (`offline.showForm`) switched on. The ticket is created `new`, priority `medium`, source `chat-widget`.\n\n#### Signature\n\n```http\nPOST /crm/tickets/chat-request (body) -> The created ticket\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | GUEST_REQUIRED | Guest authentication is required | No Bearer token (\"Guest authentication is invalid or expired\" when it does not verify). | — |\n| `403` | WRONG_ORG | This guest does not belong to this organization | The token is not a guest customer of this org. | — |\n| `400` | FIELDS_REQUIRED | A name, valid email, message and widget are required | The guest has no name or valid email, or `description` / `configId` is missing or too long. | — |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"description":{"type":"string","maxLength":10000},"configId":{"type":"string"},"reportedByEmail":{"type":"string","description":"Optional; must equal the guest email."}}}}},"example":{"data":{"description":"Do you deliver on Sundays?","configId":"support-widget"}}}}}}},"/crm/tickets/collections":{"get":{"operationId":"TicketsController_getTicketCollections","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Ticket collection definitions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/tickets/collections","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"summary":"Get ticket collections","description":"The ticket collection definitions for the org — the categories and schemas tickets are filed under. Read this to build a ticket form generically.\n\n#### Signature\n\n```http\nGET /crm/tickets/collections () -> Ticket collection definitions\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/create`"}},"/crm/tickets/list":{"get":{"operationId":"TicketsController_listForStaff","summary":"List tickets (staff)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"One status or a comma-separated list."},{"name":"priority","required":false,"in":"query","schema":{"type":"string"}},{"name":"assignTo","required":false,"in":"query","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"inWorkflow","required":false,"in":"query","schema":{"type":"string","enum":["true","1"]}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":25},"description":"Max 200."}],"responses":{"200":{"description":"{ data, total, page, pageSize }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Authentication for this organization is required — The caller is not a user or customer of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Authentication for this organization is required","path":"/crm/tickets/list","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"A signed-in customer is required — A customer or guest calls a staff route (the message is the platform's; staff routes refuse every non-user).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"A signed-in customer is required","path":"/crm/tickets/list","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"description":"Staff only. Tickets newest first, paged and filtered by the server, each with `workflowInfo` (its workflow, stage and task) when it is on one. `search` matches name, title, reporter, reporter email and description. `inWorkflow=true` keeps tickets that have a workflow task.\n\n#### Signature\n\n```http\nGET /crm/tickets/list (status?: string, priority?: string, assignTo?: string, search?: string, inWorkflow?: string, page?: integer, pageSize?: integer) -> { data, total, page, pageSize }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | ORG_AUTH_REQUIRED | Authentication for this organization is required | The caller is not a user or customer of this org. | — |\n| `403` | STAFF_ONLY | A signed-in customer is required | A customer or guest calls a staff route (the message is the platform's; staff routes refuse every non-user). | — |\n\nPlus the standard platform errors: `429`, `500`."}},"/crm/tickets/workflows":{"get":{"operationId":"TicketsController_workflowsOverview","summary":"Ticket workflows","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"{ data, total, resolves }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Authentication for this organization is required — The caller is not a user or customer of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Authentication for this organization is required","path":"/crm/tickets/workflows","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"A signed-in customer is required — A customer or guest calls a staff route (the message is the platform's; staff routes refuse every non-user).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"A signed-in customer is required","path":"/crm/tickets/workflows","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"description":"Staff only. The workflows tickets run through, each with what is in flight in it, plus `resolves` — how the org decides which workflow a new ticket takes.\n\n#### Signature\n\n```http\nGET /crm/tickets/workflows () -> { data, total, resolves }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | ORG_AUTH_REQUIRED | Authentication for this organization is required | The caller is not a user or customer of this org. | — |\n| `403` | STAFF_ONLY | A signed-in customer is required | A customer or guest calls a staff route (the message is the platform's; staff routes refuse every non-user). | — |\n\nPlus the standard platform errors: `429`, `500`."}},"/crm/tickets/workflow/{id}":{"get":{"operationId":"TicketsController_workflowFor","summary":"Where a ticket stands in its workflow","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket sk."}],"responses":{"200":{"description":"Workflow info, or null","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Authentication for this organization is required — The caller is not a user or customer of this org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Authentication for this organization is required","path":"/crm/tickets/workflow/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"A signed-in customer is required — A customer or guest calls a staff route (the message is the platform's; staff routes refuse every non-user).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"A signed-in customer is required","path":"/crm/tickets/workflow/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Ticket not found — No ticket with that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/workflow/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"description":"Staff only. The ticket's workflow position (workflow, stage, task, stage history), or `null` when it is on none.\n\n#### Signature\n\n```http\nGET /crm/tickets/workflow/{id} (id: string) -> Workflow info, or null\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | ORG_AUTH_REQUIRED | Authentication for this organization is required | The caller is not a user or customer of this org. | — |\n| `403` | STAFF_ONLY | A signed-in customer is required | A customer or guest calls a staff route (the message is the platform's; staff routes refuse every non-user). | — |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket with that id. | — |\n\nPlus the standard platform errors: `429`, `500`."}},"/crm/tickets/get-by-email/{email}/{number}":{"get":{"operationId":"TicketsController_getTicketByEmail","summary":"Get tickets by email","description":"Fetches a customer's tickets by their email address rather than through their account — how a support portal shows someone their tickets when they have no login.\n\nThe email is the only key, so anyone who knows an address can list that person's tickets. Rate-limit any public surface built on it.\n\n#### Signature\n\n```http\nGET /crm/tickets/get-by-email/{email}/{number} (email: string, number: string) -> The customer's tickets\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Keyed on email alone — treat the address as the credential it effectively is.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/email/create/{email}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"email","required":true,"in":"path","description":"Customer email address.","schema":{"type":"string"},"example":"ada@example.com"},{"name":"number","required":true,"in":"path","description":"Ticket number. Omit to list all for the email.","schema":{"type":"string"},"example":"TKT-4821"}],"responses":{"200":{"description":"The customer's tickets","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/email/create/{email}":{"post":{"operationId":"TicketsController_createTicketByEmail","summary":"Create a ticket for an email address","description":"Raises a ticket attributed to an email address rather than to a signed-in account — the intake path for a contact form or an inbound support email.\n\n#### Signature\n\n```http\nPOST /crm/tickets/email/create/{email} (email: string, body) -> The created ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/tickets/delete-by-email/{email}/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Customer email address.","example":"ada@example.com"}],"requestBody":{"description":"The ticket to raise.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}},"example":{"data":{"title":"Cannot log in after password reset","description":"Reset link works but sign-in still fails"}}}}},"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/delete-by-email/{email}/{id}":{"delete":{"operationId":"TicketsController_deleteTicketByEmail","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Customer email address.","example":"ada@example.com"},{"name":"id","in":"path","required":true,"description":"Ticket id.","schema":{"type":"string"},"example":"TKT-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"summary":"Delete a ticket by email","description":"Deletes a ticket belonging to an email address. Both must match, so an id alone is not enough to delete someone else's ticket through this route.\n\n#### Signature\n\n```http\nDELETE /crm/tickets/delete-by-email/{email}/{id} (email: string, id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/tickets/get-by-email/{email}/{number}`"}},"/crm/tickets/get/{number}":{"get":{"operationId":"TicketsController_getTickets","summary":"Get tickets","description":"Fetches one ticket by number, or lists them all when the segment is omitted. Scoped to what the caller may see.\n\n#### Signature\n\n```http\nGET /crm/tickets/get/{number} (number: string, status?: string, enrich?: boolean) -> The ticket, or all tickets\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/tickets/get-by-email/{email}/{number}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"number","required":true,"in":"path","description":"Ticket number. Omit to list.","schema":{"type":"string"},"example":"TKT-4821"},{"name":"status","required":false,"in":"query","description":"Filter by status.","schema":{"type":"string"}},{"name":"enrich","required":false,"in":"query","description":"true to resolve linked records.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"The ticket, or all tickets","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/tickets/get/{number}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/delete/{id}":{"delete":{"operationId":"TicketsController_deleteTickets","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","in":"path","required":true,"description":"Ticket id.","schema":{"type":"string"},"example":"TKT-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/tickets/delete/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"summary":"Delete a ticket","description":"Deletes a ticket and its history. Closing it instead preserves the record of what was asked and how it was resolved.\n\n#### Signature\n\n```http\nDELETE /crm/tickets/delete/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `PATCH /crm/tickets/status/{ticketId}`"}},"/crm/tickets/create":{"post":{"operationId":"TicketsController_createTicket","summary":"Create a ticket","description":"Raises a support ticket on behalf of the signed-in caller. `title` is the one required field — everything else can be filled in later.\n\nTwo further create endpoints exist: `POST /crm/tickets/create-ticket` and `POST /crm/tickets/email/create/{email}`. They differ in who the ticket is attributed to.\n\n#### Signature\n\n```http\nPOST /crm/tickets/create (body) -> The created ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n| `400` | TITLE_REQUIRED | title is required | `title` is missing from the ticket data. | Every ticket needs a title; the rest is optional. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/create-ticket`\n- `POST /crm/tickets/email/create/{email}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The ticket to raise.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}},"required":["title"]}}},"example":{"data":{"title":"Cannot log in after password reset","description":"Reset link works but sign-in still fails","priority":"high"}}}}},"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"400":{"description":"title is required — `title` is missing from the ticket data.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"title is required","path":"/crm/tickets/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/tickets/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/talk-to-sales":{"post":{"operationId":"TicketsController_talkToSales","summary":"Talk to sales","description":"Sends an Enterprise / sales request from the signed-in organization to the platform team.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Tickets"]}},"/crm/tickets/report-ide-issue":{"post":{"operationId":"TicketsController_reportIDEIssue","summary":"Report an IDE issue","description":"Raises a ticket from the IDE integration, tagged so these reports can be triaged separately from ordinary support traffic.\n\n#### Signature\n\n```http\nPOST /crm/tickets/report-ide-issue (body) -> The created ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The issue report.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}},"example":{"data":{"title":"Autocomplete stops responding on large files","description":"Reproduces on files over 5k lines"}}}}},"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/tickets/report-ide-issue","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/create-ticket":{"post":{"operationId":"TicketsController_createTicketPost","summary":"Create a ticket (alternate)","description":"A second create endpoint, taking the ticket body without the request context the primary `create` uses. Prefer `POST /crm/tickets/create` unless you specifically need this one.\n\n#### Signature\n\n```http\nPOST /crm/tickets/create-ticket (body) -> The created ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The ticket to raise.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}},"example":{"data":{"title":"Cannot log in","priority":"high"}}}}},"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/tickets/create-ticket","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/update":{"post":{"operationId":"TicketsController_updateTickets","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The updated ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized — No signed-in customer or user could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Unauthorized","path":"/crm/tickets/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"summary":"Update a ticket","description":"Updates a ticket's fields. Status, assignment and priority each have a dedicated endpoint that records the change properly — use those rather than writing the field here.\n\n#### Signature\n\n```http\nPOST /crm/tickets/update (body) -> The updated ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Setting `status` here bypasses the resolution capture that `PATCH status/{ticketId}` performs.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | UNAUTHORIZED | Unauthorized | No signed-in customer or user could be resolved. | Sign in. These routes are scoped to the caller. |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `PATCH /crm/tickets/status/{ticketId}`","requestBody":{"description":"The ticket to update, including its `sk`.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sk":"66f1a2b3c4d5e6f708192a3b","data":{"description":"Updated with reproduction steps"}}}}}}},"/crm/tickets/reply/{ticketId}":{"post":{"operationId":"TicketsController_replyToTicket","summary":"Reply to a ticket","description":"Sends a reply on a ticket, by email. `to` is required — a reply with no recipient is refused rather than silently recorded.\n\nSet `isStaffReply` to mark it as coming from support rather than the customer. Use `templateId` to send a templated reply instead of raw `html` or `text`.\n\n#### Signature\n\n```http\nPOST /crm/tickets/reply/{ticketId} (ticketId: string, body) -> The sent reply\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `to` is not defaulted from the ticket's reporter. Send it explicitly.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n| `400` | RECIPIENT_REQUIRED | Recipient (to) is required | `to` is missing. | A reply must name a recipient — it is not inferred from the ticket. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/tickets/messages/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket id.","example":"TKT-4821"}],"responses":{"201":{"description":"The sent reply","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Recipient (to) is required — `to` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Recipient (to) is required","path":"/crm/tickets/reply/{ticketId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/reply/{ticketId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"requestBody":{"description":"The reply to send.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Recipient(s). Required.","example":"ada@example.com"},"from":{"type":"string","description":"Sender address. Defaults to the org support address."},"subject":{"type":"string","example":"Re: Cannot log in after password reset"},"html":{"type":"string","description":"HTML body."},"text":{"type":"string","description":"Plain-text body."},"templateId":{"type":"string","description":"Send a templated reply instead of raw content.","example":"ticket-reply"},"deliveryType":{"type":"string","description":"Delivery channel.","example":"email"},"isStaffReply":{"type":"boolean","description":"Marks the reply as from support rather than the customer.","example":true}}},"examples":{"staff":{"summary":"Staff reply","value":{"to":"ada@example.com","subject":"Re: Cannot log in","html":"<p>Could you try clearing your cookies?</p>","isStaffReply":true}},"templated":{"summary":"Templated reply","value":{"to":"ada@example.com","templateId":"ticket-reply","isStaffReply":true}}}}}}}},"/crm/tickets/reply/{ticketId}/resend/{messageId}":{"post":{"operationId":"TicketsController_resendTicketMessage","summary":"Send a failed reply again","description":"Re-sends the same message record (no copy is made); its status moves to sent or failed","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"}},{"name":"messageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Tickets"]}},"/crm/tickets/messages/{ticketId}":{"get":{"operationId":"TicketsController_getTicketMessages","summary":"Get ticket messages","description":"The customer-facing conversation on a ticket — everything sent to and received from the reporter. Internal comments are separate.\n\n#### Signature\n\n```http\nGET /crm/tickets/messages/{ticketId} (ticketId: string) -> The ticket's messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/tickets/comments/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket id.","example":"TKT-4821"}],"responses":{"200":{"description":"The ticket's messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/messages/{ticketId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/comments/{ticketId}":{"post":{"operationId":"TicketsController_addInternalComment","summary":"Add an internal comment","description":"Adds a comment visible only to staff. This is the place for triage notes and internal discussion — unlike a reply, nothing is sent to the customer.\n\n#### Signature\n\n```http\nPOST /crm/tickets/comments/{ticketId} (ticketId: string, body) -> The added comment\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/reply/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket id.","example":"TKT-4821"}],"responses":{"201":{"description":"The added comment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/comments/{ticketId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"requestBody":{"description":"The comment.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Internal note. Not shown to the customer.","example":"Third report this week — likely the session cookie change"}}},"example":{"message":"Third report this week — likely the session cookie change"}}}}},"get":{"operationId":"TicketsController_getTicketComments","summary":"Get internal comments","description":"The staff-only comments on a ticket. Keep these out of any customer-facing view — they are separate from `messages` precisely so they are not shown.\n\n#### Signature\n\n```http\nGET /crm/tickets/comments/{ticketId} (ticketId: string) -> Internal comments\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/comments/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket id.","example":"TKT-4821"}],"responses":{"200":{"description":"Internal comments","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/comments/{ticketId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/tickets/status/{ticketId}":{"patch":{"operationId":"TicketsController_changeStatus","summary":"Change a ticket status","description":"Moves a ticket to a new status. When closing one, supply `resolution` — the summary and root cause are what makes a closed ticket useful later, and this is the only endpoint that captures them.\n\n#### Signature\n\n```http\nPATCH /crm/tickets/status/{ticketId} (ticketId: string, body) -> The updated ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `POST /crm/tickets/update` can also set a status, but does not capture a resolution — use this endpoint when closing.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PATCH /crm/tickets/assign/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket id.","example":"TKT-4821"}],"responses":{"200":{"description":"The updated ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/status/{ticketId}","method":"PATCH","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"requestBody":{"description":"The new status, and the resolution when closing.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"New status.","example":"resolved"},"resolution":{"type":"object","description":"Recorded when resolving.","properties":{"summary":{"type":"string","example":"Cleared stale session cookie"},"rootCause":{"type":"string","example":"Session cookie not invalidated on password reset"}}}}},"examples":{"resolve":{"summary":"Resolve with a root cause","value":{"status":"resolved","resolution":{"summary":"Cleared stale session cookie","rootCause":"Session cookie not invalidated on password reset"}}},"reopen":{"summary":"Reopen","value":{"status":"open"}}}}}}}},"/crm/tickets/assign/{ticketId}":{"patch":{"operationId":"TicketsController_reassignTicket","summary":"Reassign a ticket","description":"Assigns a ticket to a different agent, with an optional handover note.\n\n#### Signature\n\n```http\nPATCH /crm/tickets/assign/{ticketId} (ticketId: string, body) -> The updated ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PATCH /crm/tickets/priority/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket id.","example":"TKT-4821"}],"responses":{"200":{"description":"The updated ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/assign/{ticketId}","method":"PATCH","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"requestBody":{"description":"Who to assign it to.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["assignTo"],"properties":{"assignTo":{"type":"string","example":"support@acme.com"},"note":{"type":"string","description":"Handover note, recorded on the ticket.","example":"Needs someone from the auth team"}}},"example":{"assignTo":"support@acme.com","note":"Needs someone from the auth team"}}}}}},"/crm/tickets/priority/{ticketId}":{"patch":{"operationId":"TicketsController_changePriority","summary":"Change a ticket priority","description":"Sets a ticket's priority, which drives queue ordering and any SLA attached to it.\n\n#### Signature\n\n```http\nPATCH /crm/tickets/priority/{ticketId} (ticketId: string, body) -> The updated ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TICKET_NOT_FOUND | Ticket not found | No ticket has that id. | Check the id with `GET /crm/tickets/get`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/bulk-update`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"},"description":"Ticket id.","example":"TKT-4821"}],"responses":{"200":{"description":"The updated ticket","content":{"application/json":{"schema":{"type":"object","description":"A support ticket (`ticket`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"number":{"type":"string","description":"Human ticket number.","example":"TKT-4821"},"title":{"type":"string","description":"Required on create.","example":"Cannot log in after password reset"},"description":{"type":"string"},"status":{"type":"string","example":"open"},"priority":{"type":"string","example":"high"},"assignedTo":{"type":"string","example":"support@acme.com"},"email":{"type":"string","description":"Reporter email — the key the by-email routes use.","example":"ada@example.com"},"resolution":{"type":"object","description":"Filled in when the ticket is closed.","properties":{"summary":{"type":"string"},"rootCause":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found — No ticket has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Ticket not found","path":"/crm/tickets/priority/{ticketId}","method":"PATCH","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"requestBody":{"description":"The new priority.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["priority"],"properties":{"priority":{"type":"string","example":"urgent"}}},"example":{"priority":"urgent"}}}}}},"/crm/tickets/escalate/{ticketId}":{"post":{"operationId":"TicketsController_escalateTicket","summary":"Escalate ticket","description":"Raise the priority one step and record the escalation (who, when, why)","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Tickets"]}},"/crm/tickets/bulk-update":{"post":{"operationId":"TicketsController_bulkUpdate","summary":"Update several tickets","description":"Applies the same status, priority or assignment to many tickets at once — for clearing a queue or handing over a shift.\n\nBecause it goes through the bulk path, no resolution is captured: closing tickets this way records the status but not why.\n\n#### Signature\n\n```http\nPOST /crm/tickets/bulk-update (body) -> The bulk update result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- No resolution is recorded. Close tickets individually where the root cause matters.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PATCH /crm/tickets/status/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The bulk update result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"],"requestBody":{"description":"Which tickets, and what to change.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["ticketIds"],"properties":{"ticketIds":{"type":"array","items":{"type":"string"},"example":["TKT-4821","TKT-4822"]},"status":{"type":"string","example":"closed"},"priority":{"type":"string","example":"low"},"assignTo":{"type":"string","example":"support@acme.com"}}},"examples":{"reassign":{"summary":"Hand a queue to another agent","value":{"ticketIds":["TKT-4821","TKT-4822"],"assignTo":"support@acme.com"}},"closeOut":{"summary":"Close a batch","value":{"ticketIds":["TKT-4821","TKT-4822"],"status":"closed"}}}}}}}},"/crm/tickets/canned-responses":{"get":{"operationId":"TicketsController_getCannedResponses","summary":"Get canned responses","description":"The saved reply templates available to agents, for answering common questions consistently.\n\n#### Signature\n\n```http\nGET /crm/tickets/canned-responses () -> Canned responses\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/tickets/reply/{ticketId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Canned responses","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Tickets"]}},"/crm/communications/sms":{"get":{"operationId":"CommunicationsController_getSmsMessages","summary":"List SMS messages","description":"SMS messages sent and received. Distinct from `twilio-sms`, which reads from the provider directly.\n\n#### Signature\n\n```http\nGET /crm/communications/sms (startDate?: string, endDate?: string) -> SMS messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/twilio-sms`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"offset","required":false,"in":"query","description":"Offset for pagination","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"type":"number"}},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-31"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-01"},{"name":"status","required":false,"in":"query","description":"Filter by status (sent, delivered, failed)","schema":{}},{"name":"to","required":false,"in":"query","description":"Filter by recipient phone number","schema":{}},{"name":"from","required":false,"in":"query","description":"Filter by sender phone number","schema":{}}],"responses":{"200":{"description":"SMS messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/recordings":{"get":{"operationId":"CommunicationsController_getVoiceRecordings","summary":"List call recordings","description":"The recordings held for calls.\n\nCall recordings are personal data and in many jurisdictions require consent from both parties. Restrict access and retention accordingly — this endpoint enforces neither.\n\n#### Signature\n\n```http\nGET /crm/communications/recordings (startDate?: string, endDate?: string) -> Call recordings\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Recordings are sensitive personal data. No consent or retention policy is applied here.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/recordings/{recordingSid}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"offset","required":false,"in":"query","description":"Offset for pagination","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"type":"number"}},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-31"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-01"},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{}},{"name":"reference","required":false,"in":"query","description":"Filter by call SID reference","schema":{}}],"responses":{"200":{"description":"Call recordings","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/twilio-sms":{"get":{"operationId":"CommunicationsController_getSmsMessagesLive","summary":"List SMS from Twilio","description":"Reads SMS records **directly from Twilio** rather than from the platform store. Use it to reconcile — to see what the provider recorded independently of what was saved here.\n\nThis is a live provider call and counts against Twilio's rate limits.\n\n#### Signature\n\n```http\nGET /crm/communications/twilio-sms (startDate?: string, endDate?: string) -> SMS records as Twilio holds them\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The shape is Twilio's, not the platform's.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/sms`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"type":"number"}},{"name":"to","required":false,"in":"query","description":"Filter by recipient phone number","schema":{}},{"name":"from","required":false,"in":"query","description":"Filter by sender phone number","schema":{}},{"name":"number","required":false,"in":"query","description":"Phone number — merges inbound + outbound","schema":{}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"SMS records as Twilio holds them","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/voicemails":{"get":{"operationId":"CommunicationsController_getVoicemails","summary":"List voicemails","description":"Voicemail messages left for the org.\n\n#### Signature\n\n```http\nGET /crm/communications/voicemails (startDate?: string, endDate?: string) -> Voicemails\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/recordings`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"type":"number"}},{"name":"callSid","required":false,"in":"query","description":"Filter by call SID","schema":{}},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Voicemails","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/recordings/{recordingSid}":{"get":{"operationId":"CommunicationsController_getRecording","summary":"Get a call recording","description":"Metadata for one recording — duration, participants and whether it has been transcribed.\n\n#### Signature\n\n```http\nGET /crm/communications/recordings/{recordingSid} (recordingSid: string) -> Recording metadata\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Recording not found | No recording has that id. | Check the id against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/recordings/{recordingSid}/audio`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"recordingSid","required":true,"in":"path","description":"Provider recording id.","schema":{"type":"string"},"example":"RE9k2m4h1p7q"}],"responses":{"200":{"description":"Recording metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Recording not found — No recording has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Recording not found","path":"/crm/communications/recordings/{recordingSid}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/recordings/{recordingSid}/audio":{"get":{"operationId":"CommunicationsController_getRecordingAudio","summary":"Get recording audio","description":"Streams the audio of a call recording. Handle it as sensitive personal data — do not cache it in a shared location or expose the URL more widely than the recording itself.\n\n#### Signature\n\n```http\nGET /crm/communications/recordings/{recordingSid}/audio (recordingSid: string) -> The recording audio\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Recording not found | No recording has that id. | Check the id against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/communications/recordings/transcribe`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"recordingSid","required":true,"in":"path","description":"Provider recording id.","schema":{"type":"string"},"example":"RE9k2m4h1p7q"}],"responses":{"200":{"description":"The recording audio","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Recording not found — No recording has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Recording not found","path":"/crm/communications/recordings/{recordingSid}/audio","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/calls":{"get":{"operationId":"CommunicationsController_getCallLogs","summary":"List call logs","description":"Inbound and outbound call records, with duration and outcome.\n\n#### Signature\n\n```http\nGET /crm/communications/calls (startDate?: string, endDate?: string) -> Call logs\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/recordings`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"type":"number"}},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-31"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-01"},{"name":"status","required":false,"in":"query","description":"Filter by call status","schema":{}},{"name":"to","required":false,"in":"query","description":"Filter by recipient phone number","schema":{}},{"name":"from","required":false,"in":"query","description":"Filter by caller phone number","schema":{}}],"responses":{"200":{"description":"Call logs","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications":{"get":{"operationId":"CommunicationsController_getAllCommunications","summary":"List all communications","description":"Every communication across channels — SMS, calls and voicemails together. The unified telephony view.\n\n#### Signature\n\n```http\nGET /crm/communications (startDate?: string, endDate?: string, page?: integer, pageSize?: integer) -> Communications\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/stats`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"offset","required":false,"in":"query","description":"Offset for pagination","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"type":"number"}},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-31"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-01"},{"name":"to","required":false,"in":"query","description":"Filter by recipient phone number","schema":{}},{"name":"from","required":false,"in":"query","description":"Filter by sender phone number","schema":{}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"Communications","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/stats":{"get":{"operationId":"CommunicationsController_getCommunicationStats","summary":"Get communication statistics","description":"Messages on every channel (sent, received, failed, waiting — by channel and over time, with the latest failures) and phone calls (inbound, outbound, answered, missed, talk time, answered by AI, recorded, transcribed, the latest missed), counted from the org's own records for the period, with what needs attention. Each section answers on its own (`{ error }`).\n\n#### Signature\n\n```http\nGET /crm/communications/stats (period?: string) -> Communication statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"period","required":false,"in":"query","description":"7d, 30d (default), 90d or 12m","schema":{"type":"string"},"example":"30d"}],"responses":{"200":{"description":"Communication statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/recordings/transcribe":{"post":{"operationId":"CommunicationsController_requestTranscription","summary":"Request a transcription","description":"Requests a transcription of a call recording. Transcription is asynchronous and usually billed per minute — request it deliberately rather than for every call.\n\n#### Signature\n\n```http\nPOST /crm/communications/recordings/transcribe (body) -> The transcription request result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Asynchronous — poll the recording for the finished transcript rather than expecting it in this response.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Recording not found | No recording has that id. | Check the id against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/recordings/{recordingSid}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which recording to transcribe.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["recordingSid"],"properties":{"recordingSid":{"type":"string","example":"RE9k2m4h1p7q"}}},"example":{"recordingSid":"RE9k2m4h1p7q"}}}},"responses":{"201":{"description":"The transcription request result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Recording not found — No recording has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Recording not found","path":"/crm/communications/recordings/transcribe","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/twilio/setup":{"post":{"operationId":"CommunicationsController_setupTwilioNumber","summary":"Set up a Twilio number","description":"Configures a phone number for the org — either claiming one you already hold, or **purchasing a new one** when `purchaseNew` is set.\n\nPurchasing incurs a real, recurring charge from Twilio. Use `GET /crm/communications/twilio/available-numbers` to see what is available first, and set `purchaseNew` deliberately.\n\n#### Signature\n\n```http\nPOST /crm/communications/twilio/setup (body) -> The configured number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `purchaseNew: true` spends money and creates an ongoing monthly cost.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/twilio/available-numbers`\n- `GET /crm/communications/twilio/verify`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which number to configure, or whether to buy one.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","description":"An existing number to configure.","example":"+15551234567"},"purchaseNew":{"type":"boolean","default":false,"description":"**Buys a new number**, incurring a recurring charge.","example":false},"areaCode":{"type":"string","description":"Preferred area code when purchasing.","example":"415"}}},"examples":{"existing":{"summary":"Configure a number you already have","value":{"phoneNumber":"+15551234567"}},"purchase":{"summary":"Buy a new number","description":"Incurs a recurring charge.","value":{"purchaseNew":true,"areaCode":"415"}}}}}},"responses":{"200":{"description":"Successfully setup Twilio phone number","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"phoneNumber":{"type":"string"},"webhooksConfigured":{"type":"boolean"},"message":{"type":"string"}}}}}},"201":{"description":"The configured number","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/twilio/verify":{"get":{"operationId":"CommunicationsController_verifyTwilioSetup","summary":"Verify Twilio setup","description":"Checks that the org's Twilio configuration is complete and working. Run this after setup, and first when messages or calls stop arriving.\n\n#### Signature\n\n```http\nGET /crm/communications/twilio/verify () -> Verification result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/communications/twilio/setup`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/twilio/available-numbers":{"get":{"operationId":"CommunicationsController_getAvailablePhoneNumbers","summary":"List available phone numbers","description":"Numbers available to purchase from Twilio, optionally filtered by area code. Listing costs nothing — buying happens through `twilio/setup`.\n\n#### Signature\n\n```http\nGET /crm/communications/twilio/available-numbers (areaCode?: string, country?: string, exclude?: string, batch?: number) -> Available numbers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Read-only — no number is reserved by listing it, so one shown here can be taken before you buy it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/communications/twilio/setup`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"batch","required":false,"in":"query","description":"Which \"show other numbers\" request this is (1, 2, …), used with `exclude`.","schema":{"type":"number"},"example":2},{"name":"exclude","required":false,"in":"query","description":"Numbers already shown, comma-separated. Answers with other numbers for the same search (Twilio repeats its first numbers otherwise); empty when there are no others.","schema":{"type":"string"},"example":"+19455550101,+19455550102"},{"name":"limit","required":false,"in":"query","description":"Number of results to return (default: 20)","schema":{"type":"number"}},{"name":"contains","required":false,"in":"query","description":"Numbers containing specific digits (e.g., \"555\")","schema":{}},{"name":"state","required":false,"in":"query","description":"State/region code to search in (e.g., \"TX\", \"CA\", \"NY\")","schema":{}},{"name":"zipCode","required":false,"in":"query","description":"ZIP/Postal code to search in (e.g., \"75252\", \"10001\")","schema":{}},{"name":"city","required":false,"in":"query","description":"City name to search in (e.g., \"Plano\", \"Austin\")","schema":{}},{"name":"areaCode","required":false,"in":"query","description":"Preferred area code.","schema":{"type":"string"},"example":"415"},{"name":"countryCode","required":false,"in":"query","description":"Country code (default: US)","schema":{}},{"name":"country","in":"query","required":false,"description":"ISO country code.","schema":{"type":"string"},"example":"US"}],"responses":{"200":{"description":"Available numbers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/communications/twilio/system-phone":{"get":{"operationId":"CommunicationsController_getSystemPhone","summary":"Get the system phone number","description":"The platform-level phone number, as opposed to the org's own. Used where a message must come from the platform rather than the tenant.\n\n#### Signature\n\n```http\nGET /crm/communications/twilio/system-phone () -> The system phone number\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/communications/twilio/verify`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The system phone number","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Communications"]}},"/crm/message-template/whatsapp/submit/{templateId}":{"post":{"operationId":"MessageTemplateWhatsAppController_submit","summary":"Submit a template for WhatsApp approval","description":"Builds Twilio Content from the template (body with {{1}} variables, data.whatsapp header/footer/buttons) and asks WhatsApp to approve it. Saves data.whatsapp.contentSid and approval {status: pending}. A changed template gets new Content and goes back to pending; an unchanged pending/approved one is left as is. Optional body `samples` = {\"1\": \"Ada\"} gives Meta sample values. Returns the data.whatsapp block.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"templateId","required":true,"in":"path","description":"message_template sk","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["CRM - Message Templates"]}},"/crm/message-template/whatsapp/status/{templateId}":{"get":{"operationId":"MessageTemplateWhatsAppController_status","summary":"WhatsApp approval status of a template","description":"Asks Twilio, saves and returns data.whatsapp.approval {status draft|pending|approved|rejected, reason, updatedAt}.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"templateId","required":true,"in":"path","description":"message_template sk","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM - Message Templates"]}},"/crm/ads/campaigns":{"post":{"operationId":"AdsController_createCampaign","parameters":[],"responses":{"201":{"description":"The created campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"The ad platform rejected the request. — The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The ad platform rejected the request.","path":"/crm/ads/campaigns","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create an ad campaign","description":"Creates a campaign. It starts as a draft — creating does not spend money or push anything to a platform; `POST /crm/ads/campaigns/launch/{campaignId}` does that.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns (body) -> The created campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Creating is free — nothing reaches a platform until it is launched.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PLATFORM_ERROR | The ad platform rejected the request. | The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec. | The platform's own message is passed through. Check the integration is still connected with `GET /crm/ads/integrations/status`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/launch/{campaignId}`","tags":["CRM · Ads"],"requestBody":{"description":"The campaign to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}},"example":{"name":"Summer sale — retargeting","platforms":["facebook","instagram"],"budget":5000,"objective":"conversions","startDate":"2026-09-01T00:00:00.000Z","endDate":"2026-09-30T23:59:59.000Z"}}}}},"get":{"operationId":"AdsController_getCampaigns","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"]},"example":"active"},{"name":"platform","required":false,"in":"query","schema":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"example":"facebook"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","default":20},"description":"Page size. Note this is `limit`, not `pageSize` as elsewhere on the platform.","example":20}],"responses":{"200":{"description":"A page of campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}},"total":{"type":"integer","example":24}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List ad campaigns","description":"Lists campaigns with optional filters and paging.\n\n#### Signature\n\n```http\nGET /crm/ads/campaigns (status?: string, platform?: string, page?: integer, limit?: integer) -> A page of campaigns\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Paging uses `limit`, not the platform-standard `pageSize`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/campaigns/{campaignId}`","tags":["CRM · Ads"]}},"/crm/ads/campaigns/{campaignId}":{"get":{"operationId":"AdsController_getCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/{campaignId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an ad campaign","description":"Fetches one campaign with its budget, targeting and current status.\n\n#### Signature\n\n```http\nGET /crm/ads/campaigns/{campaignId} (campaignId: string) -> The campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/campaigns/metrics/{campaignId}`","tags":["CRM · Ads"]},"put":{"operationId":"AdsController_updateCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"200":{"description":"The updated campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/{campaignId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update an ad campaign","description":"Updates a campaign's settings. Changes to a live campaign are pushed to the platform, where some fields cannot be edited once running — the platform decides, and rejects with a `400` if not.\n\n#### Signature\n\n```http\nPUT /crm/ads/campaigns/{campaignId} (campaignId: string, body) -> The updated campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Pause a running campaign before making structural changes — many platforms refuse edits to an active campaign.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/pause/{campaignId}`","tags":["CRM · Ads"],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}},"example":{"budget":7500}}}}},"delete":{"operationId":"AdsController_deleteCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/{campaignId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete an ad campaign","description":"Deletes a campaign. Pause it first if it is running — deleting does not guarantee the platform stops serving immediately.\n\n#### Signature\n\n```http\nDELETE /crm/ads/campaigns/{campaignId} (campaignId: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Historical spend and metrics may be lost with the campaign — export analytics first if you need them.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/pause/{campaignId}`","tags":["CRM · Ads"]}},"/crm/ads/campaigns/launch/{campaignId}":{"post":{"operationId":"AdsController_launchCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"201":{"description":"The launched campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/launch/{campaignId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Launch a campaign","description":"Pushes a campaign to its platforms and starts it running.\n\n**This starts spending money.** From here the budget is consumed by the ad platforms, and stopping it requires an explicit pause.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/launch/{campaignId} (campaignId: string) -> The launched campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Spend begins immediately. A campaign that is rejected on one platform may still run on the others — check the result per platform.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/pause/{campaignId}`\n- `POST /crm/ads/campaigns/schedule/{campaignId}`","tags":["CRM · Ads"]}},"/crm/ads/campaigns/pause/{campaignId}":{"post":{"operationId":"AdsController_pauseCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"201":{"description":"The paused campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/pause/{campaignId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Pause a campaign","description":"Stops a running campaign from serving and spending. The campaign and its history are kept, and it can be resumed.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/pause/{campaignId} (campaignId: string) -> The paused campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Platforms may take a few minutes to stop serving after a pause is accepted.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/resume/{campaignId}`","tags":["CRM · Ads"]}},"/crm/ads/campaigns/resume/{campaignId}":{"post":{"operationId":"AdsController_resumeCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"201":{"description":"The resumed campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/resume/{campaignId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Resume a campaign","description":"Restarts a paused campaign. Spending resumes against the remaining budget.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/resume/{campaignId} (campaignId: string) -> The resumed campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/pause/{campaignId}`","tags":["CRM · Ads"]}},"/crm/ads/campaigns/schedule/{campaignId}":{"post":{"operationId":"AdsController_scheduleCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"201":{"description":"The scheduled campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/schedule/{campaignId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Schedule a campaign","description":"Sets a campaign to start automatically at a future date rather than launching it now. Give an `endDate` to have it stop on its own.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/schedule/{campaignId} (campaignId: string, body) -> The scheduled campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Without an `endDate` the campaign runs until it is paused or the budget runs out.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/scheduled`","tags":["CRM · Ads"],"requestBody":{"description":"When the campaign should run.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["startDate"],"properties":{"startDate":{"type":"string","format":"date-time","description":"When the campaign starts.","example":"2026-09-01T00:00:00.000Z"},"endDate":{"type":"string","format":"date-time","description":"When it stops. Omit to run until paused or the budget is exhausted.","example":"2026-09-30T23:59:59.000Z"}}},"example":{"startDate":"2026-09-01T00:00:00.000Z","endDate":"2026-09-30T23:59:59.000Z"}}}}}},"/crm/ads/campaigns/duplicate/{campaignId}":{"post":{"operationId":"AdsController_duplicateCampaign","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"}],"responses":{"201":{"description":"The new draft campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/duplicate/{campaignId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Duplicate a campaign","description":"Copies a campaign into a new draft, optionally onto different platforms, with a different name or budget. The fast path for running a proven campaign again or extending it to another channel.\n\nThe duplicate is a **draft** — it does not inherit the original's running state.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/duplicate/{campaignId} (campaignId: string, body) -> The new draft campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- The copy starts as a draft and must be launched separately.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/from-template/{templateId}`","tags":["CRM · Ads"],"requestBody":{"description":"What to change in the copy.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Platforms for the copy. Defaults to the original's.","example":["tiktok"]},"name":{"type":"string","description":"Name for the copy.","example":"Summer sale — retargeting (TikTok)"},"budget":{"type":"number","example":2500},"modifications":{"type":"object","additionalProperties":true,"description":"Other fields to override."}}},"examples":{"sameSetup":{"summary":"Straight copy","value":{}},"newPlatform":{"summary":"Extend to another platform","value":{"platforms":["tiktok"],"name":"Summer sale — retargeting (TikTok)","budget":2500}}}}}}}},"/crm/ads/campaigns/bulk/launch":{"post":{"operationId":"AdsController_bulkLaunchCampaigns","parameters":[],"responses":{"201":{"description":"Per-campaign launch results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Launch several campaigns","description":"Launches many campaigns in one call.\n\n**This starts spending on every campaign named.** Individual failures are reported per campaign rather than failing the batch, so check the response — a `200` means the batch ran, not that everything launched.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/bulk/launch (body) -> Per-campaign launch results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Starts real spend across every campaign in the list. Inspect each result.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/bulk/pause`","tags":["CRM · Ads"],"requestBody":{"description":"Which campaigns to launch.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaignIds"],"properties":{"campaignIds":{"type":"array","items":{"type":"string"},"example":["CAMP-4821","CAMP-4822"]}}},"example":{"campaignIds":["CAMP-4821","CAMP-4822"]}}}}}},"/crm/ads/campaigns/bulk/pause":{"post":{"operationId":"AdsController_bulkPauseCampaigns","parameters":[],"responses":{"201":{"description":"Per-campaign pause results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Pause several campaigns","description":"Pauses many campaigns at once — the emergency stop when spend needs to halt across the board. Results are reported per campaign.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/bulk/pause (body) -> Per-campaign pause results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Check every result — a campaign that failed to pause is still spending.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/bulk/launch`","tags":["CRM · Ads"],"requestBody":{"description":"Which campaigns to pause.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaignIds"],"properties":{"campaignIds":{"type":"array","items":{"type":"string"},"example":["CAMP-4821","CAMP-4822"]}}},"example":{"campaignIds":["CAMP-4821","CAMP-4822"]}}}}}},"/crm/ads/campaigns/metrics/{campaignId}":{"get":{"operationId":"AdsController_getCampaignMetrics","parameters":[{"name":"campaignId","required":true,"in":"path","schema":{"type":"string"},"description":"Campaign id.","example":"CAMP-4821"},{"name":"startDate","in":"query","required":false,"description":"Start of the reporting period.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","in":"query","required":false,"description":"End of the reporting period.","schema":{"type":"string"},"example":"2026-08-31"},{"name":"platforms","in":"query","required":false,"description":"Restrict to specific platforms. Repeat the parameter for several.","schema":{"type":"string"},"example":"facebook"},{"name":"groupBy","in":"query","required":false,"description":"How results are aggregated.","schema":{"type":"string","enum":["platform","date","campaign"]},"example":"platform"},{"name":"metrics","in":"query","required":false,"description":"Which metrics to return. Repeat for several.","schema":{"type":"string"},"example":"impressions"}],"responses":{"200":{"description":"Campaign metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Campaign not found — No campaign in the org has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Campaign not found","path":"/crm/ads/campaigns/metrics/{campaignId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get campaign metrics","description":"Live performance figures for one campaign, pulled from its platforms — impressions, clicks, spend and conversions.\n\n#### Signature\n\n```http\nGET /crm/ads/campaigns/metrics/{campaignId} (campaignId: string, startDate?: string, endDate?: string, platforms?: string, groupBy?: string, metrics?: string) -> Campaign metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Figures come from the ad platforms and lag real time — most report on their own delay.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | CAMPAIGN_NOT_FOUND | Campaign not found | No campaign in the org has that id. | Check the id with `GET /crm/ads/campaigns`. **Note this is a `400`, not a `404`** — this controller never returns 404. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/analytics/overview`","tags":["CRM · Ads"]}},"/crm/ads/analytics/overview":{"get":{"operationId":"AdsController_getAnalyticsOverview","parameters":[{"name":"startDate","in":"query","required":false,"description":"Start of the reporting period.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","in":"query","required":false,"description":"End of the reporting period.","schema":{"type":"string"},"example":"2026-08-31"},{"name":"platforms","in":"query","required":false,"description":"Restrict to specific platforms. Repeat the parameter for several.","schema":{"type":"string"},"example":"facebook"},{"name":"groupBy","in":"query","required":false,"description":"How results are aggregated.","schema":{"type":"string","enum":["platform","date","campaign"]},"example":"platform"},{"name":"metrics","in":"query","required":false,"description":"Which metrics to return. Repeat for several.","schema":{"type":"string"},"example":"impressions"}],"responses":{"200":{"description":"Overview metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get an advertising overview","description":"Headline advertising figures across every campaign and platform for a period — total spend, reach and conversions.\n\n#### Signature\n\n```http\nGET /crm/ads/analytics/overview (startDate?: string, endDate?: string, platforms?: string, groupBy?: string, metrics?: string) -> Overview metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/analytics/performance`","tags":["CRM · Ads"]}},"/crm/ads/analytics/performance":{"get":{"operationId":"AdsController_getPerformanceAnalytics","parameters":[{"name":"startDate","in":"query","required":false,"description":"Start of the reporting period.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","in":"query","required":false,"description":"End of the reporting period.","schema":{"type":"string"},"example":"2026-08-31"},{"name":"platforms","in":"query","required":false,"description":"Restrict to specific platforms. Repeat the parameter for several.","schema":{"type":"string"},"example":"facebook"},{"name":"groupBy","in":"query","required":false,"description":"How results are aggregated.","schema":{"type":"string","enum":["platform","date","campaign"]},"example":"platform"},{"name":"metrics","in":"query","required":false,"description":"Which metrics to return. Repeat for several.","schema":{"type":"string"},"example":"impressions"}],"responses":{"200":{"description":"Performance analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get performance analytics","description":"Detailed performance breakdown — cost per result, conversion rates and efficiency by whatever `groupBy` selects.\n\n#### Signature\n\n```http\nGET /crm/ads/analytics/performance (startDate?: string, endDate?: string, platforms?: string, groupBy?: string, metrics?: string) -> Performance analytics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/analytics/comparison`","tags":["CRM · Ads"]}},"/crm/ads/analytics/comparison":{"get":{"operationId":"AdsController_getPlatformComparison","parameters":[{"name":"startDate","in":"query","required":false,"description":"Start of the reporting period.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","in":"query","required":false,"description":"End of the reporting period.","schema":{"type":"string"},"example":"2026-08-31"},{"name":"platforms","in":"query","required":false,"description":"Restrict to specific platforms. Repeat the parameter for several.","schema":{"type":"string"},"example":"facebook"},{"name":"groupBy","in":"query","required":false,"description":"How results are aggregated.","schema":{"type":"string","enum":["platform","date","campaign"]},"example":"platform"},{"name":"metrics","in":"query","required":false,"description":"Which metrics to return. Repeat for several.","schema":{"type":"string"},"example":"impressions"}],"responses":{"200":{"description":"Platform comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Compare platforms","description":"Puts platforms side by side over the same period — the read behind \"is TikTok outperforming Facebook for us\".\n\n#### Signature\n\n```http\nGET /crm/ads/analytics/comparison (startDate?: string, endDate?: string, platforms?: string, groupBy?: string, metrics?: string) -> Platform comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Platforms define metrics like a conversion differently, so treat cross-platform comparisons as directional.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/analytics/trends`","tags":["CRM · Ads"]}},"/crm/ads/analytics/trends":{"get":{"operationId":"AdsController_getTrends","parameters":[{"name":"startDate","in":"query","required":false,"description":"Start of the reporting period.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","in":"query","required":false,"description":"End of the reporting period.","schema":{"type":"string"},"example":"2026-08-31"},{"name":"platforms","in":"query","required":false,"description":"Restrict to specific platforms. Repeat the parameter for several.","schema":{"type":"string"},"example":"facebook"},{"name":"groupBy","in":"query","required":false,"description":"How results are aggregated.","schema":{"type":"string","enum":["platform","date","campaign"]},"example":"platform"},{"name":"metrics","in":"query","required":false,"description":"Which metrics to return. Repeat for several.","schema":{"type":"string"},"example":"impressions"}],"responses":{"200":{"description":"Trend data","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get advertising trends","description":"Performance over time, for spotting drift in cost or effectiveness before it shows up in a monthly total.\n\n#### Signature\n\n```http\nGET /crm/ads/analytics/trends (startDate?: string, endDate?: string, platforms?: string, groupBy?: string, metrics?: string) -> Trend data\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/analytics/overview`","tags":["CRM · Ads"]}},"/crm/ads/campaigns/cross-platform":{"post":{"operationId":"AdsController_createCrossPlatformCampaign","parameters":[],"responses":{"201":{"description":"The created cross-platform campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"400":{"description":"The ad platform rejected the request. — The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The ad platform rejected the request.","path":"/crm/ads/campaigns/cross-platform","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a cross-platform campaign","description":"Creates one campaign that runs across several platforms with a split budget and platform-specific settings.\n\n`platformSpecific` holds the per-platform overrides, keyed by platform name; `distribution.budgetSplit` divides the budget between them, and `distribution.priority` orders which platforms are set up first.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/cross-platform (body) -> The created cross-platform campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- `budgetSplit` is not validated against the total budget — the two can disagree.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PLATFORM_ERROR | The ad platform rejected the request. | The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec. | The platform's own message is passed through. Check the integration is still connected with `GET /crm/ads/integrations/status`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns`","tags":["CRM · Ads"],"requestBody":{"description":"The cross-platform campaign definition.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"platformSpecific":{"type":"object","additionalProperties":true,"description":"Per-platform settings, keyed by platform name."},"distribution":{"type":"object","properties":{"budgetSplit":{"type":"object","additionalProperties":{"type":"number"},"description":"Budget share per platform, keyed by platform name."},"priority":{"type":"array","items":{"type":"string"},"description":"Order in which platforms are set up.","example":["facebook","tiktok"]}}}}},"example":{"name":"Summer sale — cross platform","budget":10000,"platformSpecific":{"facebook":{"objective":"conversions"},"tiktok":{"objective":"traffic"}},"distribution":{"budgetSplit":{"facebook":6000,"tiktok":4000},"priority":["facebook","tiktok"]}}}}}}},"/crm/ads/templates":{"post":{"operationId":"AdsController_createCampaignTemplate","parameters":[],"responses":{"201":{"description":"The created template","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a campaign template","description":"Saves a reusable campaign setup, so a recurring campaign shape does not have to be rebuilt each time.\n\n#### Signature\n\n```http\nPOST /crm/ads/templates (body) -> The created template\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/from-template/{templateId}`","tags":["CRM · Ads"],"requestBody":{"description":"The template to save.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","defaultSettings"],"properties":{"name":{"type":"string","example":"Seasonal retargeting"},"description":{"type":"string","example":"Standard retargeting setup for seasonal sales"},"defaultSettings":{"type":"object","additionalProperties":true,"description":"Settings applied to campaigns created from this template."},"category":{"type":"string","description":"Grouping, used by the list filter.","example":"retargeting"}}},"example":{"name":"Seasonal retargeting","description":"Standard retargeting setup","category":"retargeting","defaultSettings":{"objective":"conversions","platforms":["facebook","instagram"]}}}}}},"get":{"operationId":"AdsController_getCampaignTemplates","parameters":[{"name":"category","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by category.","example":"retargeting"}],"responses":{"200":{"description":"Campaign templates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List campaign templates","description":"The saved campaign templates, optionally filtered by category.\n\n#### Signature\n\n```http\nGET /crm/ads/templates (category?: string) -> Campaign templates\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/templates`","tags":["CRM · Ads"]}},"/crm/ads/campaigns/from-template/{templateId}":{"post":{"operationId":"AdsController_createCampaignFromTemplate","parameters":[{"name":"templateId","required":true,"in":"path","schema":{"type":"string"},"description":"Template id.","example":"TPL-4821"}],"responses":{"201":{"description":"The created draft campaign","content":{"application/json":{"schema":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a campaign from a template","description":"Builds a new draft campaign from a saved template. Like duplication, the result is a draft and must be launched separately.\n\n#### Signature\n\n```http\nPOST /crm/ads/campaigns/from-template/{templateId} (templateId: string, body) -> The created draft campaign\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/templates`","tags":["CRM · Ads"],"requestBody":{"description":"Overrides for the template defaults.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Autumn sale — retargeting","budget":3000}}}}}},"/crm/ads/accounts":{"get":{"operationId":"AdsController_getAdAccounts","parameters":[{"name":"platform","required":false,"in":"query","schema":{"type":"string"},"description":"Ad platform key, e.g. `facebook`."}],"responses":{"200":{"description":"Connected ad accounts","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List connected ad accounts","description":"The ad accounts connected to this org across platforms — what campaigns can actually be published to.\n\n#### Signature\n\n```http\nGET /crm/ads/accounts (platform?: string) -> Connected ad accounts\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/accounts/sync`","tags":["CRM · Ads"]}},"/crm/ads/accounts/sync":{"post":{"operationId":"AdsController_syncAdAccounts","parameters":[],"responses":{"201":{"description":"The sync result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The ad platform rejected the request. — The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The ad platform rejected the request.","path":"/crm/ads/accounts/sync","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Sync ad accounts","description":"Refreshes the connected account list from the platforms, picking up accounts added or removed on their side since the last sync.\n\n#### Signature\n\n```http\nPOST /crm/ads/accounts/sync () -> The sync result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PLATFORM_ERROR | The ad platform rejected the request. | The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec. | The platform's own message is passed through. Check the integration is still connected with `GET /crm/ads/integrations/status`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/accounts`","tags":["CRM · Ads"]}},"/crm/ads/creatives":{"post":{"operationId":"AdsController_uploadCreative","parameters":[],"responses":{"201":{"description":"The registered creative","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The ad platform rejected the request. — The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The ad platform rejected the request.","path":"/crm/ads/creatives","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Upload a creative","description":"Registers an ad creative — an image, video or copy variant — for use across the named platforms. Supply either a `url` or an uploaded `file`.\n\n#### Signature\n\n```http\nPOST /crm/ads/creatives (body) -> The registered creative\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Platforms enforce their own size and aspect-ratio rules — a creative accepted here can still be rejected at launch.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PLATFORM_ERROR | The ad platform rejected the request. | The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec. | The platform's own message is passed through. Check the integration is still connected with `GET /crm/ads/integrations/status`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/creatives`","tags":["CRM · Ads"],"requestBody":{"description":"The creative to register.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["platforms"],"properties":{"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Platforms this creative is for.","example":["facebook","instagram"]},"url":{"type":"string","description":"Where the asset lives. Use this or `file`.","example":"https://cdn.appmint.io/ads/summer-hero.jpg"},"file":{"type":"object","additionalProperties":true,"description":"Uploaded asset. Use this or `url`."},"metadata":{"type":"object","additionalProperties":true,"description":"Dimensions, format, alt text and the like."}}},"example":{"platforms":["facebook","instagram"],"url":"https://cdn.appmint.io/ads/summer-hero.jpg","metadata":{"width":1200,"height":628,"format":"jpg"}}}}}},"get":{"operationId":"AdsController_getCreatives","parameters":[{"name":"type","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by creative type.","example":"image"},{"name":"platform","required":false,"in":"query","schema":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"example":"facebook"}],"responses":{"200":{"description":"Creatives","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List creatives","description":"The registered ad creatives, optionally filtered by type or platform.\n\n#### Signature\n\n```http\nGET /crm/ads/creatives (type?: string, platform?: string) -> Creatives\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/creatives`","tags":["CRM · Ads"]}},"/crm/ads/audiences":{"post":{"operationId":"AdsController_createAudience","parameters":[],"responses":{"201":{"description":"The created audience","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The ad platform rejected the request. — The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The ad platform rejected the request.","path":"/crm/ads/audiences","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create an audience","description":"Defines a targeting audience and pushes it to the named platforms, so the same definition can be reused across campaigns instead of being rebuilt per campaign.\n\n#### Signature\n\n```http\nPOST /crm/ads/audiences (body) -> The created audience\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Platforms impose minimum audience sizes and may reject one that is too small to protect privacy.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PLATFORM_ERROR | The ad platform rejected the request. | The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec. | The platform's own message is passed through. Check the integration is still connected with `GET /crm/ads/integrations/status`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/audiences`","tags":["CRM · Ads"],"requestBody":{"description":"The audience to create.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","platforms","targetingCriteria"],"properties":{"name":{"type":"string","example":"Cart abandoners — 30 days"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"example":["facebook","instagram"]},"targetingCriteria":{"type":"object","additionalProperties":true,"description":"Who is in the audience."}}},"example":{"name":"Cart abandoners — 30 days","platforms":["facebook","instagram"],"targetingCriteria":{"event":"cart_abandoned","withinDays":30}}}}}},"get":{"operationId":"AdsController_getAudiences","parameters":[{"name":"platform","required":false,"in":"query","schema":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"example":"facebook"}],"responses":{"200":{"description":"Audiences","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List audiences","description":"The defined targeting audiences, optionally filtered by platform.\n\n#### Signature\n\n```http\nGET /crm/ads/audiences (platform?: string) -> Audiences\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/audiences`","tags":["CRM · Ads"]}},"/crm/ads/automation/rules":{"post":{"operationId":"AdsController_createAutomationRule","parameters":[],"responses":{"201":{"description":"The created rule","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create an automation rule","description":"Defines a rule that acts on campaigns automatically — pausing one whose cost per result climbs too high, or shifting budget toward a performer.\n\nA rule is a `trigger` (what to watch), `conditions` (when it applies) and `actions` (what to do). Because the actions change live campaigns and therefore spend, test a rule on one campaign before applying it broadly.\n\n#### Signature\n\n```http\nPOST /crm/ads/automation/rules (body) -> The created rule\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Rules act on live campaigns without confirmation. A badly-scoped rule can pause everything you are running.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/automation/rules`","tags":["CRM · Ads"],"requestBody":{"description":"The rule to create.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","trigger","conditions","actions","platforms"],"properties":{"name":{"type":"string","example":"Pause on high CPA"},"trigger":{"type":"object","additionalProperties":true,"description":"What the rule watches."},"conditions":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"When it fires."},"actions":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"What it does. These change live campaigns."},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"example":["facebook"]}}},"example":{"name":"Pause on high CPA","platforms":["facebook"],"trigger":{"metric":"cpa","check":"hourly"},"conditions":[{"metric":"cpa","operator":">","value":50}],"actions":[{"type":"pause_campaign"}]}}}}},"get":{"operationId":"AdsController_getAutomationRules","parameters":[],"responses":{"200":{"description":"Automation rules","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List automation rules","description":"The automation rules configured for this org — worth checking first when a campaign changed state without anyone doing it.\n\n#### Signature\n\n```http\nGET /crm/ads/automation/rules () -> Automation rules\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/automation/rules`","tags":["CRM · Ads"]}},"/crm/ads/reports/generate":{"post":{"operationId":"AdsController_generateReport","parameters":[],"responses":{"201":{"description":"The generated report, or a handle to it","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate an advertising report","description":"Builds a report over a period and set of campaigns. Reports are retrieved afterwards from `GET /crm/ads/reports`.\n\n#### Signature\n\n```http\nPOST /crm/ads/reports/generate (body) -> The generated report, or a handle to it\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Generation may be asynchronous — check the reports list rather than assuming the response is the finished report.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/reports`","tags":["CRM · Ads"],"requestBody":{"description":"What the report should cover.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"startDate":"2026-08-01","endDate":"2026-08-31","platforms":["facebook","tiktok"],"groupBy":"platform"}}}}}},"/crm/ads/reports":{"get":{"operationId":"AdsController_getReports","parameters":[],"responses":{"200":{"description":"Reports","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List advertising reports","description":"The reports generated for this org.\n\n#### Signature\n\n```http\nGET /crm/ads/reports () -> Reports\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/reports/generate`","tags":["CRM · Ads"]}},"/crm/ads/activity":{"get":{"operationId":"AdsController_getAdsActivity","parameters":[{"name":"platform","required":false,"in":"query","schema":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"example":"facebook"},{"name":"type","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by activity type.","example":"pause"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","default":50},"example":50},{"name":"offset","required":false,"in":"query","schema":{"type":"integer","default":0},"description":"Offset paging — this endpoint uses `offset`, not `page`.","example":0}],"responses":{"200":{"description":"Activity entries","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get advertising activity","description":"The activity log across advertising — launches, pauses, edits and automation-rule firings. The audit trail for \"why did this campaign stop\".\n\n#### Signature\n\n```http\nGET /crm/ads/activity (platform?: string, type?: string, limit?: integer, offset?: integer) -> Activity entries\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Paging is offset-based here, unlike the campaign list which pages by number.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/automation/rules`","tags":["CRM · Ads"]}},"/crm/ads/integrations/status":{"get":{"operationId":"AdsController_getIntegrationsStatus","parameters":[],"responses":{"200":{"description":"Integration status per platform","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"platform":{"type":"string","example":"facebook"},"connected":{"type":"boolean","example":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get platform integration status","description":"Whether each ad platform integration is connected and healthy. Check this first when campaigns fail to launch — an expired token presents as a platform error at launch time.\n\n#### Signature\n\n```http\nGET /crm/ads/integrations/status () -> Integration status per platform\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/integrations/test/{platform}`","tags":["CRM · Ads"]}},"/crm/ads/integrations/test/{platform}":{"post":{"operationId":"AdsController_testIntegration","parameters":[{"name":"platform","required":true,"in":"path","schema":{"type":"string"},"description":"Platform to test — one of `facebook`, `instagram`, `google`, `tiktok`, `linkedin`, `twitter`.","example":"facebook"}],"responses":{"201":{"description":"The test result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The ad platform rejected the request. — The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The ad platform rejected the request.","path":"/crm/ads/integrations/test/{platform}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Test a platform integration","description":"Makes a live call to one platform to confirm the credentials still work. Nothing is published — this only verifies the connection.\n\n#### Signature\n\n```http\nPOST /crm/ads/integrations/test/{platform} (platform: string) -> The test result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n- Read-only against the platform — safe to run at any time.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PLATFORM_ERROR | The ad platform rejected the request. | The upstream ad platform returned an error — a policy rejection, an expired token, or an invalid targeting spec. | The platform's own message is passed through. Check the integration is still connected with `GET /crm/ads/integrations/status`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/ads/integrations/status`","tags":["CRM · Ads"]}},"/crm/ads/scheduled":{"get":{"operationId":"AdsController_getScheduledCampaigns","parameters":[],"responses":{"200":{"description":"Scheduled campaigns","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"An ad campaign (`crm_ads_campaign`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"campaignId":{"type":"string","example":"CAMP-4821"},"name":{"type":"string","example":"Summer sale — retargeting"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","failed"],"example":"active"},"platforms":{"type":"array","items":{"type":"string","enum":["facebook","instagram","google","tiktok","linkedin","twitter"]},"description":"Where the campaign runs.","example":["facebook","instagram"]},"budget":{"type":"number","example":5000},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"objective":{"type":"string","description":"What the campaign optimises for.","example":"conversions"},"targeting":{"type":"object","additionalProperties":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List scheduled campaigns","description":"Campaigns waiting to start automatically — what is about to begin spending, and when.\n\n#### Signature\n\n```http\nGET /crm/ads/scheduled () -> Scheduled campaigns\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- This controller takes **no `orgid` header**. The organization comes from `user.orgId` on the authenticated token, so a token scoped to the wrong org silently operates on the wrong data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/ads/campaigns/schedule/{campaignId}`","tags":["CRM · Ads"]}},"/crm/promotions/{name}/subscribe":{"post":{"operationId":"PromotionController_subscribe","summary":"Subscribe to a promotion","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Promotion name.","schema":{"type":"string"},"example":"summer-newsletter"}],"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Subscribes someone to a promotion or mailing list. Either `email` or `phone` identifies them, and `channel` decides how they are contacted.\n\n**`consentText` records what the person actually agreed to.** Store the exact wording shown at the point of signup — it is the evidence of consent, and a generic value undermines it. The UTM fields capture where the signup came from.\n\n#### Signature\n\n```http\nPOST /crm/promotions/{name}/subscribe (name: string, body) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Depending on the promotion, a confirmation email may follow — see `GET /crm/promotions/confirm/{token}`.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /crm/promotions/confirm/{token}`\n- `POST /crm/promotions/{name}/unsubscribe`","requestBody":{"description":"Who is subscribing, and what they consented to.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Required unless `phone` is given.","example":"ada@example.com"},"phone":{"type":"string","description":"Required unless `email` is given.","example":"+15551234567"},"name":{"type":"string","example":"Ada Lovelace"},"channel":{"type":"string","enum":["email","sms"],"description":"How they will be contacted.","example":"email"},"source":{"type":"string","description":"Where the signup happened.","example":"footer-form"},"sourceUrl":{"type":"string","example":"https://shop.example.com/"},"utmSource":{"type":"string","example":"newsletter"},"utmMedium":{"type":"string","example":"email"},"utmCampaign":{"type":"string","example":"summer-2026"},"consentText":{"type":"string","description":"The exact wording the person agreed to. Store it verbatim.","example":"I agree to receive marketing emails from Acme Retail. Unsubscribe any time."}}},"example":{"email":"ada@example.com","name":"Ada Lovelace","channel":"email","source":"footer-form","consentText":"I agree to receive marketing emails from Acme Retail. Unsubscribe any time."}}}}}},"/crm/promotions/{name}/public":{"get":{"operationId":"PromotionController_publicPromotion","summary":"What a public sign-up page shows for a promotion","description":"Title, description, type and whether it takes sign-ups now (`open`, with `reason` when not). Never the incentive itself.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","description":"Promotion name","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Promotions"]}},"/crm/promotions/confirm/{token}":{"get":{"operationId":"PromotionController_confirmSubscription","summary":"Confirm a subscription","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"token","required":true,"in":"path","description":"Confirmation token from the email.","schema":{"type":"string"},"example":"cnf_9k2m4h1p7q"}],"responses":{"200":{"description":"The confirmation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Confirms a double opt-in subscription from the link in a confirmation email. The token is single-purpose and identifies the subscriber, so treat the link as a credential.\n\n#### Signature\n\n```http\nGET /crm/promotions/confirm/{token} (token: string) -> The confirmation result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Public by necessity — the recipient clicks it from their inbox without signing in.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/promotions/{name}/subscribe`"}},"/crm/promotions/{name}/unsubscribe":{"post":{"operationId":"PromotionController_unsubscribe","summary":"Unsubscribe from a promotion","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Promotion name.","schema":{"type":"string"},"example":"summer-newsletter"}],"responses":{"201":{"description":"The unsubscribe result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Removes someone from a promotion. Honour this promptly and completely — an unsubscribe that keeps sending is a compliance problem, not just a bug.\n\n#### Signature\n\n```http\nPOST /crm/promotions/{name}/unsubscribe (name: string, body) -> The unsubscribe result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /crm/promotions/preferences`","requestBody":{"description":"Who is unsubscribing.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","example":"ada@example.com"},"phone":{"type":"string"}}},"example":{"email":"ada@example.com"}}}}}},"/crm/promotions/preferences":{"get":{"operationId":"PromotionController_getPreferences","summary":"Get subscription preferences","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"email","required":false,"in":"query","schema":{"type":"string"},"description":"Subscriber email."},{"name":"phone","required":false,"in":"query","schema":{"type":"string"},"description":"Subscriber phone."}],"responses":{"200":{"description":"Subscription preferences","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"A subscriber's current preferences across promotions — which lists someone is on. Staff only: it returns the stored subscriber records.\n\n#### Signature\n\n```http\nGET /crm/promotions/preferences (email?: string, phone?: string) -> Subscription preferences\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/promotions/{name}/unsubscribe`"}},"/crm/promotions":{"post":{"operationId":"PromotionController_createPromotion","summary":"Create a promotion","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The created promotion","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Creates a promotion or mailing list that people can subscribe to.\n\n#### Signature\n\n```http\nPOST /crm/promotions (body) -> The created promotion\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/promotions`","requestBody":{"description":"The promotion to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","example":"summer-newsletter"},"title":{"type":"string","example":"Summer Newsletter"},"incentive":{"type":"object","additionalProperties":true}}},"example":{"name":"summer-newsletter","title":"Summer Newsletter"}}}}},"get":{"operationId":"PromotionController_listPromotions","summary":"List promotions","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by status."},{"name":"type","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by type."}],"responses":{"200":{"description":"Promotions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"The promotions defined for the org.\n\n#### Signature\n\n```http\nGET /crm/promotions (status?: string, type?: string) -> Promotions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/promotions/{name}`"}},"/crm/promotions/{name}":{"get":{"operationId":"PromotionController_getPromotion","summary":"Get a promotion","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Promotion name.","example":"summer-newsletter"}],"responses":{"200":{"description":"The promotion","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Promotion not found — No promotion has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Promotion not found","path":"/crm/promotions/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Fetches one promotion by name.\n\n#### Signature\n\n```http\nGET /crm/promotions/{name} (name: string) -> The promotion\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Promotion not found | No promotion has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/promotions/{name}`"},"put":{"operationId":"PromotionController_updatePromotion","summary":"Update a promotion","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Promotion name.","example":"summer-newsletter"}],"responses":{"200":{"description":"The updated promotion","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Promotion not found — No promotion has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Promotion not found","path":"/crm/promotions/{name}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Updates a promotion's details. Changing the consent wording here does not alter what existing subscribers agreed to — their recorded `consentText` stands.\n\n#### Signature\n\n```http\nPUT /crm/promotions/{name} (name: string, body) -> The updated promotion\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Promotion not found | No promotion has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/promotions/{name}`","requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"title":"Summer Newsletter 2026"}}}}},"delete":{"operationId":"PromotionController_deletePromotion","summary":"Delete a promotion","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Promotion name.","example":"summer-newsletter"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Promotion not found — No promotion has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Promotion not found","path":"/crm/promotions/{name}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Deletes a promotion. Its subscriber list goes with it, including the consent records — export them first if you need to prove consent later.\n\n#### Signature\n\n```http\nDELETE /crm/promotions/{name} (name: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Consent evidence is deleted along with the subscribers.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Promotion not found | No promotion has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/promotions/{name}/subscribers`"}},"/crm/promotions/{name}/subscribers":{"get":{"operationId":"PromotionController_listSubscribers","summary":"List promotion subscribers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Promotion name.","example":"summer-newsletter"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Filter by status."},{"name":"page","required":false,"in":"query","schema":{"type":"string"},"description":"Page number (1-based)."},{"name":"pageSize","required":false,"in":"query","schema":{"type":"string"},"description":"Rows per page."}],"responses":{"200":{"description":"Subscribers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Everyone subscribed to a promotion, with their consent record and where they signed up from.\n\n#### Signature\n\n```http\nGET /crm/promotions/{name}/subscribers (name: string, status?: string, page?: string, pageSize?: string) -> Subscribers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Contains personal data and consent evidence — restrict access accordingly.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/promotions/{name}/subscribe`"}},"/crm/promotions/{name}/incentive-claimed":{"post":{"operationId":"PromotionController_markIncentiveClaimed","summary":"Record an incentive claim","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Promotion name.","example":"summer-newsletter"}],"responses":{"201":{"description":"The claim result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Promotions"],"description":"Records that a subscriber claimed the promotion's incentive — the discount code or freebie offered for signing up — so it is not given twice.\n\n#### Signature\n\n```http\nPOST /crm/promotions/{name}/incentive-claimed (name: string, body) -> The claim result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/promotions/{name}/subscribers`","requestBody":{"description":"Who claimed it.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","example":"ada@example.com"}}},"example":{"email":"ada@example.com"}}}}}},"/crm/merchant-customers/dashboard":{"get":{"operationId":"MerchantCustomerController_getDashboard","summary":"Get merchant dashboard metrics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Cross-merchant dashboard metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Headline figures across every merchant account — total credit extended, outstanding balance and overdue exposure.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/dashboard () -> Cross-merchant dashboard metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/balances/outstanding`"}},"/crm/merchant-customers/invoices/all":{"get":{"operationId":"MerchantCustomerController_getAllInvoices","summary":"Get all invoices across merchants","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","description":"Filter by invoice status.","schema":{"type":"string"},"example":"overdue"},{"name":"page","required":false,"in":"query","schema":{"type":"string"},"description":"Page number (1-based)."},{"name":"pageSize","required":false,"in":"query","schema":{"type":"string"},"description":"Rows per page."}],"responses":{"200":{"description":"Invoices across all merchants","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"A merchant invoice.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"invoiceNumber":{"type":"string","example":"MINV-00412"},"amount":{"type":"number","description":"The invoice total: what its lines add up to (charges less credits).","example":4200},"amountPaid":{"type":"number","description":"Received so far, one entry per payment in `payments`.","example":1500},"amountDue":{"type":"number","description":"Still owed on it.","example":2700},"status":{"type":"string","description":"`draft`, `sent`, `paid-partial`, `paid`, `overdue` or `cancelled`.","example":"paid-partial"},"dueDate":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Every merchant invoice in the org, for a consolidated receivables view.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/invoices/all (page?: string, pageSize?: string, status?: string) -> Invoices across all merchants\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/reports/aging`"}},"/crm/merchant-customers/transactions/all":{"get":{"operationId":"MerchantCustomerController_getAllTransactions","summary":"Get all transactions across merchants","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"type","required":false,"in":"query","description":"Filter by type.","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start of the period.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"End of the period.","schema":{"type":"string"},"example":"2026-08-31"},{"name":"page","required":false,"in":"query","schema":{"type":"string"},"description":"Page number (1-based)."},{"name":"pageSize","required":false,"in":"query","schema":{"type":"string"},"description":"Rows per page."}],"responses":{"200":{"description":"Transactions across all merchants","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Every charge and credit across all merchant accounts — the consolidated ledger.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/transactions/all (type?: string, page?: string, pageSize?: string, startDate?: string, endDate?: string) -> Transactions across all merchants\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/transactions/{id}`"}},"/crm/merchant-customers/balances/outstanding":{"get":{"operationId":"MerchantCustomerController_getOutstandingBalances","summary":"Get outstanding balances","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Outstanding balance per merchant","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"What every merchant currently owes — the \"who owes what\" list, ordered so the largest exposures are visible first.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/balances/outstanding () -> Outstanding balance per merchant\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/reports/aging`"}},"/crm/merchant-customers/reports/aging":{"get":{"operationId":"MerchantCustomerController_getAgingReport","summary":"Get the accounts receivable aging report","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Receivables bucketed by age","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Buckets outstanding receivables by how overdue they are — the standard 30 / 60 / 90 day aging report finance uses to judge collectability.\n\nAges are measured against each invoice's due date, which comes from the account's `paymentTermsDays`.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/reports/aging () -> Receivables bucketed by age\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/reminders/bulk`"}},"/crm/merchant-customers/reminders/{merchantId}/{invoiceId}":{"post":{"operationId":"MerchantCustomerController_sendPaymentReminder","summary":"Send a payment reminder","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"merchantId","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"invoiceId","required":true,"in":"path","description":"Invoice id.","schema":{"type":"string"},"example":"MINV-00412"}],"responses":{"201":{"description":"Dispatch result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/reminders/{merchantId}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Sends a reminder to one merchant about one overdue invoice.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/reminders/{merchantId}/{invoiceId} (merchantId: string, invoiceId: string) -> Dispatch result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Sends every time it is called — there is no once-per-day guard.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/reminders/bulk`"}},"/crm/merchant-customers/reminders/bulk":{"post":{"operationId":"MerchantCustomerController_sendBulkPaymentReminders","summary":"Send reminders for all overdue invoices","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"What was sent, per merchant","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Sends a payment reminder for **every** overdue invoice across every merchant.\n\nThis mails customers in bulk with no dry-run and no per-recipient throttle. Check the aging report first to see who it will reach.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/reminders/bulk () -> What was sent, per merchant\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Org-wide mailing. Running it twice in a day chases every merchant twice.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/reports/aging`"}},"/crm/merchant-customers/statements/{merchantId}":{"get":{"operationId":"MerchantCustomerController_generateStatement","summary":"Generate an account statement","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"merchantId","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"startDate","required":true,"in":"query","description":"Start of the period.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":true,"in":"query","description":"End of the period.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"The account statement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/statements/{merchantId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Builds a statement of account for a merchant over a period — the charges, credits and invoices that make up their balance. Both dates are required.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/statements/{merchantId} (merchantId: string, startDate?: string, endDate?: string) -> The account statement\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/statements/{merchantId}/send`"}},"/crm/merchant-customers/statements/{merchantId}/send":{"post":{"operationId":"MerchantCustomerController_sendStatement","summary":"Generate and send an account statement","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"merchantId","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"Dispatch result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/statements/{merchantId}/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Builds the statement for a period and emails it to the merchant. Unlike the read, the period is supplied in the body.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/statements/{merchantId}/send (merchantId: string, body) -> Dispatch result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The read takes the period as query parameters; this one takes it in the body.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/statements/{merchantId}`","requestBody":{"description":"The period to cover.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["startDate","endDate"],"properties":{"startDate":{"type":"string","example":"2026-08-01"},"endDate":{"type":"string","example":"2026-08-31"}}},"example":{"startDate":"2026-08-01","endDate":"2026-08-31"}}}}}},"/crm/merchant-customers/invoices/generate-all":{"post":{"operationId":"MerchantCustomerController_generateBulkInvoices","summary":"Generate invoices for all merchants","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The invoices generated, per merchant","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Raises invoices across **every** merchant with unbilled charges — the month-end billing run.\n\nThis creates real invoices for real money across the whole book. Check the response for what it produced before sending them.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/invoices/generate-all () -> The invoices generated, per merchant\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Org-wide. Invoices are created as drafts — sending them is a separate step.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/invoices/send-all`"}},"/crm/merchant-customers/invoices/send-all":{"post":{"operationId":"MerchantCustomerController_sendAllDraftInvoices","summary":"Send all draft invoices","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"What was sent, per merchant","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Sends every draft invoice across all merchants, starting the payment-terms clock on each. The companion to the bulk generation step — review the drafts before running it.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/invoices/send-all () -> What was sent, per merchant\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Mails every merchant with a draft invoice. There is no dry run — inspect the drafts first.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/invoices/generate-all`"}},"/crm/merchant-customers/detail":{"post":{"operationId":"MerchantCustomerController_createMerchant","summary":"Create a merchant account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The account to open.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer","companyName"],"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}},"example":{"customer":"cus_4821","companyName":"Analytical Engines Ltd","accountType":"trade","spendingLimit":25000,"paymentTermsDays":30,"billingCycleDay":1,"autoInvoice":true,"invoiceTrigger":"period_end"}}}},"responses":{"201":{"description":"The created merchant account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Customer ID is required to create a merchant account — `customer` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Customer ID is required to create a merchant account","path":"/crm/merchant-customers/detail","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Customer not found — The `customer` id does not resolve.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Customer not found","path":"/crm/merchant-customers/detail","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This customer already has a merchant account — The customer already holds one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This customer already has a merchant account","path":"/crm/merchant-customers/detail","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Opens a trade-credit account for an existing customer. The customer must already exist — this attaches credit terms to them rather than creating a new party.\n\n`customer` and `companyName` are both required, and a customer can only hold one merchant account.\n\nThis endpoint returns a coded error body — `{ message, code, ... }` — rather than the platform's standard envelope. Branch on `code`; it is stable, and the message is not.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/detail (body) -> The created merchant account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_CUSTOMER | Customer ID is required to create a merchant account | `customer` is missing. | Create the customer first, then open the account against them. |\n| `404` | CUSTOMER_NOT_FOUND | Customer not found | The `customer` id does not resolve. | The body echoes the `customerId` it tried. Check it exists. |\n| `409` | ACCOUNT_EXISTS | This customer already has a merchant account | The customer already holds one. | Look it up with `GET /crm/merchant-customers/by-customer/{customerId}` and update that instead. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/approve/{id}`\n- `GET /crm/merchant-customers/by-customer/{customerId}`"},"get":{"operationId":"MerchantCustomerController_getMerchants","summary":"List merchant accounts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","active","suspended","closed"]},"example":"active"},{"name":"accountType","required":false,"in":"query","schema":{"type":"string"},"example":"trade"},{"name":"search","required":false,"in":"query","schema":{"type":"string"},"description":"Free-text search across company name and contact.","example":"analytical"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"A page of merchant accounts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}},"total":{"type":"integer","example":37}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Lists merchant accounts with filtering, search and paging.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/detail (status?: string, accountType?: string, search?: string, page?: integer, pageSize?: integer) -> A page of merchant accounts\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/detail/{id}`"}},"/crm/merchant-customers/detail/{id}":{"get":{"operationId":"MerchantCustomerController_getMerchant","summary":"Get a merchant account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"200":{"description":"The merchant account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/detail/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/detail/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Fetches one merchant account with its limits, balance, terms and authorized users.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/detail/{id} (id: string) -> The merchant account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/stats/{id}`"},"put":{"operationId":"MerchantCustomerController_updateMerchant","summary":"Update a merchant account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"companyName":"Analytical Engines Ltd (EMEA)"}}}},"responses":{"200":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/detail/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/detail/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Updates an account's general fields. Status changes, limits and payment terms each have their own endpoint, which record the change properly.\n\n#### Signature\n\n```http\nPUT /crm/merchant-customers/detail/{id} (id: string, body) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/merchant-customers/spending-limit/{id}`"}},"/crm/merchant-customers/by-customer/{customerId}":{"get":{"operationId":"MerchantCustomerController_getMerchantByCustomer","summary":"Get a merchant account by customer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"customerId","required":true,"in":"path","description":"Customer id.","schema":{"type":"string"},"example":"cus_4821"}],"responses":{"200":{"description":"The customer's merchant account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/by-customer/{customerId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Finds the merchant account belonging to a customer. Use this when you hold the customer id and need to know whether they trade on credit.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/by-customer/{customerId} (customerId: string) -> The customer's merchant account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/detail`"}},"/crm/merchant-customers/approve/{id}":{"post":{"operationId":"MerchantCustomerController_approveMerchant","summary":"Approve a merchant account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The approved account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/approve/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/approve/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Activates a pending account so it can be charged against. This is the credit decision — nothing can be charged before it.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/approve/{id} (id: string, body) -> The approved account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/suspend/{id}`","requestBody":{"description":"Optional approval notes.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"notes":{"type":"string","example":"Credit check passed, limit set at 25k"}}},"example":{"notes":"Credit check passed"}}}}}},"/crm/merchant-customers/suspend/{id}":{"post":{"operationId":"MerchantCustomerController_suspendMerchant","summary":"Suspend a merchant account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The suspended account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/suspend/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/suspend/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Suspends an account so nothing further can be charged to it. The outstanding balance stands and remains collectable — suspension stops new credit, it does not forgive existing debt.\n\nA `reason` is required, and a closed account cannot be suspended.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/suspend/{id} (id: string, body) -> The suspended account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/reactivate/{id}`","requestBody":{"description":"Why the account is being suspended.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Recorded on the account.","example":"Invoices 60 days overdue"}}},"example":{"reason":"Invoices 60 days overdue"}}}}}},"/crm/merchant-customers/reactivate/{id}":{"post":{"operationId":"MerchantCustomerController_reactivateMerchant","summary":"Reactivate a merchant account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The reactivated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/reactivate/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/reactivate/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Lifts a suspension and returns the account to active, restoring its ability to be charged. The counterpart to suspend; a closed account cannot be reactivated.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/reactivate/{id} (id: string, body) -> The reactivated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/suspend/{id}`","requestBody":{"description":"Optional notes.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"notes":{"type":"string","example":"Arrears cleared"}}},"example":{"notes":"Arrears cleared"}}}}}},"/crm/merchant-customers/close/{id}":{"post":{"operationId":"MerchantCustomerController_closeMerchant","summary":"Close a merchant account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The closed account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/close/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/close/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Closes an account permanently. Unlike suspension there is no reopen — closure is terminal, so suspend instead where the relationship might resume.\n\nA `reason` is required.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/close/{id} (id: string, body) -> The closed account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Terminal. Closing does not settle an outstanding balance — collect it before or after, but closure does not write it off.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/suspend/{id}`","requestBody":{"description":"Why the account is being closed.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","example":"Customer ceased trading"}}},"example":{"reason":"Customer ceased trading"}}}}}},"/crm/merchant-customers/spending-limit/{id}":{"put":{"operationId":"MerchantCustomerController_setSpendingLimit","summary":"Set a spending limit","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"200":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/spending-limit/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/spending-limit/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Sets the maximum credit the account may carry. `availableCredit` is this figure minus the current balance, and a charge that would exceed it is refused.\n\nLowering the limit below the current balance does not claw anything back; it simply leaves no available credit until the balance comes down.\n\n#### Signature\n\n```http\nPUT /crm/merchant-customers/spending-limit/{id} (id: string, body) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/merchant-customers/payment-terms/{id}`","requestBody":{"description":"The new limit.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["limit"],"properties":{"limit":{"type":"number","description":"Maximum outstanding credit.","example":25000},"notes":{"type":"string","example":"Raised after two years of clean payment history"}}},"example":{"limit":25000,"notes":"Raised after two years of clean payment history"}}}}}},"/crm/merchant-customers/payment-terms/{id}":{"put":{"operationId":"MerchantCustomerController_setPaymentTerms","summary":"Set payment terms","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"200":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/payment-terms/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/payment-terms/{id}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Sets how and when the account is invoiced.\n\n`invoiceTrigger` decides when an invoice is raised:\n\n- `period_end` — on the billing cycle day.\n- `limit_reached` — when the balance reaches the spending limit.\n- `either` — whichever comes first.\n- `manual` — never automatically; you raise invoices yourself.\n\n`paymentTermsDays` sets the due date relative to the invoice, and drives the aging report.\n\n#### Signature\n\n```http\nPUT /crm/merchant-customers/payment-terms/{id} (id: string, body) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/invoices/generate/{id}`","requestBody":{"description":"The terms to apply.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","description":"Raise invoices automatically.","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"example":"period_end"},"notes":{"type":"string"}}},"examples":{"monthly":{"summary":"Net 30, invoiced monthly","value":{"paymentTermsDays":30,"billingCycleDay":1,"autoInvoice":true,"invoiceTrigger":"period_end"}},"onLimit":{"summary":"Invoice when the limit is reached","value":{"paymentTermsDays":14,"autoInvoice":true,"invoiceTrigger":"limit_reached"}}}}}}}},"/crm/merchant-customers/users/{id}":{"post":{"operationId":"MerchantCustomerController_addUser","summary":"Add an authorized user","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/users/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/users/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Grants someone the right to charge to the account. Give them their own `spendingLimit` to cap what they can commit — a purchasing clerk and a finance director on the same account need different ceilings.\n\n`enabledServices` restricts what they may charge for.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/users/{id} (id: string, body) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /crm/merchant-customers/users/{id}/{customerId}`","requestBody":{"description":"Who to authorize, and with what powers.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer"],"properties":{"customer":{"type":"string","description":"Customer id of the person being authorized.","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","default":false,"description":"Whether they may approve others' charges.","example":false},"spendingLimit":{"type":"number","description":"Their own cap, within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What they may charge for. Omit for everything.","example":["catering"]}}},"example":{"customer":"cus_9912","canApproveTransactions":false,"spendingLimit":5000,"enabledServices":["catering"]}}}}}},"/crm/merchant-customers/users/{id}/{customerId}":{"put":{"operationId":"MerchantCustomerController_updateUser","summary":"Update an authorized user","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"customerId","required":true,"in":"path","description":"Customer id of the authorized user.","schema":{"type":"string"},"example":"cus_9912"}],"responses":{"200":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/users/{id}/{customerId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/users/{id}/{customerId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Changes an authorized user's limit, approval right or permitted services.\n\n#### Signature\n\n```http\nPUT /crm/merchant-customers/users/{id}/{customerId} (id: string, customerId: string, body) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /crm/merchant-customers/users/{id}/{customerId}`","requestBody":{"description":"What to change.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"canApproveTransactions":{"type":"boolean","example":true},"spendingLimit":{"type":"number","example":10000},"enabledServices":{"type":"array","items":{"type":"string"}}}},"example":{"spendingLimit":10000,"canApproveTransactions":true}}}}},"delete":{"operationId":"MerchantCustomerController_removeUser","summary":"Remove an authorized user","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"customerId","required":true,"in":"path","description":"Customer id of the authorized user.","schema":{"type":"string"},"example":"cus_9912"}],"responses":{"200":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/users/{id}/{customerId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/users/{id}/{customerId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Revokes someone's right to charge to the account. Charges they already made stand — this stops future ones only.\n\n#### Signature\n\n```http\nDELETE /crm/merchant-customers/users/{id}/{customerId} (id: string, customerId: string) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/authorized/{id}/{customerId}`"}},"/crm/merchant-customers/charge/{id}":{"post":{"operationId":"MerchantCustomerController_chargeToAccount","summary":"Charge to an account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/charge/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/charge/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Adds a charge to the account, increasing the balance and reducing available credit. This is how a purchase goes \"on account\" instead of being paid at the till.\n\n`id`, `type` and `amount` are all required, and the amount must be positive. Depending on the account's `invoiceTrigger`, a charge that reaches the spending limit can cause an invoice to be raised automatically.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/charge/{id} (id: string, body) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Not idempotent — nothing dedupes on the transaction `id`, so a retry charges twice.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/credit/{id}`\n- `GET /crm/merchant-customers/transactions/{id}`","requestBody":{"description":"The charge to record.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","amount"],"properties":{"id":{"type":"string","description":"Transaction id — your reference for this charge.","example":"TXN-99182"},"type":{"type":"string","description":"What kind of charge.","example":"order"},"amount":{"type":"number","description":"Must be greater than zero.","example":420},"reference":{"type":"string","description":"Related record, e.g. an order number.","example":"A7K2M9QX4"},"description":{"type":"string","example":"Catering order, 12 August"}}},"example":{"id":"TXN-99182","type":"order","amount":420,"reference":"A7K2M9QX4","description":"Catering order, 12 August"}}}}}},"/crm/merchant-customers/credit/{id}":{"post":{"operationId":"MerchantCustomerController_creditAccount","summary":"Credit an account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The updated account","content":{"application/json":{"schema":{"type":"object","description":"A merchant account (`crm_merchant_account`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"merchantId":{"type":"string","example":"MER-4821"},"customer":{"type":"string","description":"The customer record this account belongs to.","example":"cus_4821"},"companyName":{"type":"string","example":"Analytical Engines Ltd"},"accountType":{"type":"string","description":"Account classification.","example":"trade"},"status":{"type":"string","enum":["pending","active","suspended","closed"],"example":"active"},"spendingLimit":{"type":"number","description":"Maximum outstanding credit allowed.","example":25000},"currentBalance":{"type":"number","description":"Currently owed.","example":4200},"availableCredit":{"type":"number","description":"`spendingLimit` minus `currentBalance`.","example":20800},"paymentTermsDays":{"type":"number","description":"Days to pay after invoicing.","example":30},"billingCycleDay":{"type":"number","description":"Day of the month invoices are raised.","example":1},"autoInvoice":{"type":"boolean","example":true},"invoiceTrigger":{"type":"string","enum":["limit_reached","period_end","either","manual"],"description":"What causes an invoice to be raised.","example":"period_end"},"authorizedUsers":{"type":"array","description":"People allowed to charge to this account.","items":{"type":"object","properties":{"customer":{"type":"string","example":"cus_9912"},"canApproveTransactions":{"type":"boolean","example":false},"spendingLimit":{"type":"number","description":"Per-user cap within the account limit.","example":5000},"enabledServices":{"type":"array","items":{"type":"string"},"description":"What this user may charge for."}}}},"suspendedReason":{"type":"string"},"closedReason":{"type":"string"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/credit/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/credit/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Reduces the balance — a goodwill credit, a correction, or a returned order. A `reason` is required so the ledger explains itself.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/credit/{id} (id: string, body) -> The updated account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A credit is not a payment — record customer payments against an invoice with the payment endpoint so the invoice closes.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/invoices/payment/{id}/{invoiceId}`","requestBody":{"description":"The credit to apply.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","reason"],"properties":{"amount":{"type":"number","example":120},"reason":{"type":"string","description":"Recorded on the ledger entry.","example":"Returned two trays, credited"}}},"example":{"amount":120,"reason":"Returned two trays, credited"}}}}}},"/crm/merchant-customers/invoices/generate/{id}":{"post":{"operationId":"MerchantCustomerController_generateInvoice","summary":"Generate an invoice for an account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"201":{"description":"The generated invoice","content":{"application/json":{"schema":{"type":"object","description":"A merchant invoice.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"invoiceNumber":{"type":"string","example":"MINV-00412"},"amount":{"type":"number","description":"The invoice total: what its lines add up to (charges less credits).","example":4200},"amountPaid":{"type":"number","description":"Received so far, one entry per payment in `payments`.","example":1500},"amountDue":{"type":"number","description":"Still owed on it.","example":2700},"status":{"type":"string","description":"`draft`, `sent`, `paid-partial`, `paid`, `overdue` or `cancelled`.","example":"paid-partial"},"dueDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/invoices/generate/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/invoices/generate/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Raises an invoice for the account's unbilled charges. Use this when the account is on `manual` invoicing, or to bill early.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/invoices/generate/{id} (id: string) -> The generated invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/invoices/send/{id}/{invoiceId}`"}},"/crm/merchant-customers/invoices/send/{id}/{invoiceId}":{"post":{"operationId":"MerchantCustomerController_sendInvoice","summary":"Send an invoice","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"invoiceId","required":true,"in":"path","description":"Invoice id.","schema":{"type":"string"},"example":"MINV-00412"}],"responses":{"201":{"description":"The sent invoice","content":{"application/json":{"schema":{"type":"object","description":"A merchant invoice.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"invoiceNumber":{"type":"string","example":"MINV-00412"},"amount":{"type":"number","description":"The invoice total: what its lines add up to (charges less credits).","example":4200},"amountPaid":{"type":"number","description":"Received so far, one entry per payment in `payments`.","example":1500},"amountDue":{"type":"number","description":"Still owed on it.","example":2700},"status":{"type":"string","description":"`draft`, `sent`, `paid-partial`, `paid`, `overdue` or `cancelled`.","example":"paid-partial"},"dueDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/invoices/send/{id}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/invoices/send/{id}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Delivers a generated invoice to the merchant, moving it out of draft and starting the payment-terms clock.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/invoices/send/{id}/{invoiceId} (id: string, invoiceId: string) -> The sent invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/invoices/payment/{id}/{invoiceId}`"}},"/crm/merchant-customers/invoices/payment/{id}/{invoiceId}":{"post":{"operationId":"MerchantCustomerController_recordPayment","summary":"Record an invoice payment","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"invoiceId","required":true,"in":"path","description":"Invoice id.","schema":{"type":"string"},"example":"MINV-00412"}],"responses":{"201":{"description":"The updated invoice","content":{"application/json":{"schema":{"type":"object","description":"A merchant invoice.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"invoiceNumber":{"type":"string","example":"MINV-00412"},"amount":{"type":"number","description":"The invoice total: what its lines add up to (charges less credits).","example":4200},"amountPaid":{"type":"number","description":"Received so far, one entry per payment in `payments`.","example":1500},"amountDue":{"type":"number","description":"Still owed on it.","example":2700},"status":{"type":"string","description":"`draft`, `sent`, `paid-partial`, `paid`, `overdue` or `cancelled`.","example":"paid-partial"},"dueDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/invoices/payment/{id}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/invoices/payment/{id}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This payment is already recorded on the invoice — A payment with the same `transactionId` is already on the invoice.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This payment is already recorded on the invoice","path":"/crm/merchant-customers/invoices/payment/{id}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Records a payment against an invoice, reducing the account balance by it. A part payment leaves the invoice `paid-partial` with `amountDue` outstanding; the payment that covers it in full makes it `paid`.\n\nAn already-paid invoice, more than is due, or a `transactionId` already recorded on it is refused rather than double-credited.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/invoices/payment/{id}/{invoiceId} (id: string, invoiceId: string, body) -> The updated invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n| `409` | DUPLICATE_PAYMENT | This payment is already recorded on the invoice | A payment with the same `transactionId` is already on the invoice. | It was recorded the first time; read the invoice instead of retrying. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/invoices/mark-overdue/{id}/{invoiceId}`","requestBody":{"description":"The payment received.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"Must be greater than zero.","example":4200},"method":{"type":"string","example":"bank_transfer"},"transactionId":{"type":"string","description":"Reference for reconciliation.","example":"BACS-99182"},"notes":{"type":"string"}}},"example":{"amount":4200,"method":"bank_transfer","transactionId":"BACS-99182"}}}}}},"/crm/merchant-customers/invoices/mark-overdue/{id}/{invoiceId}":{"post":{"operationId":"MerchantCustomerController_markOverdue","summary":"Mark an invoice overdue","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"invoiceId","required":true,"in":"path","description":"Invoice id.","schema":{"type":"string"},"example":"MINV-00412"}],"responses":{"201":{"description":"The updated invoice","content":{"application/json":{"schema":{"type":"object","description":"A merchant invoice.","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","additionalProperties":true,"properties":{"invoiceNumber":{"type":"string","example":"MINV-00412"},"amount":{"type":"number","description":"The invoice total: what its lines add up to (charges less credits).","example":4200},"amountPaid":{"type":"number","description":"Received so far, one entry per payment in `payments`.","example":1500},"amountDue":{"type":"number","description":"Still owed on it.","example":2700},"status":{"type":"string","description":"`draft`, `sent`, `paid-partial`, `paid`, `overdue` or `cancelled`.","example":"paid-partial"},"dueDate":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/invoices/mark-overdue/{id}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/invoices/mark-overdue/{id}/{invoiceId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Flags an invoice as overdue, bringing it into the aging report and the bulk reminder run.\n\n#### Signature\n\n```http\nPOST /crm/merchant-customers/invoices/mark-overdue/{id}/{invoiceId} (id: string, invoiceId: string) -> The updated invoice\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/reports/aging`"}},"/crm/merchant-customers/stats/{id}":{"get":{"operationId":"MerchantCustomerController_getStats","summary":"Get account statistics","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"}],"responses":{"200":{"description":"Account statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/stats/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/stats/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Aggregate figures for one account — spend, payment history and outstanding balance.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/stats/{id} (id: string) -> Account statistics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/dashboard`"}},"/crm/merchant-customers/transactions/{id}":{"get":{"operationId":"MerchantCustomerController_getTransactions","summary":"Get an account's transaction history","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"page","required":false,"in":"query","schema":{"type":"string"},"description":"Page number (1-based)."},{"name":"pageSize","required":false,"in":"query","schema":{"type":"string"},"description":"Rows per page."}],"responses":{"200":{"description":"The account's transactions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/transactions/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/transactions/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"The charge and credit ledger for one account — what makes up the balance.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/transactions/{id} (id: string, page?: string, pageSize?: string) -> The account's transactions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/merchant-customers/transactions/all`"}},"/crm/merchant-customers/authorized/{id}/{customerId}":{"get":{"operationId":"MerchantCustomerController_checkAuthorized","summary":"Check whether a user is authorized","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Merchant account id.","schema":{"type":"string"},"example":"MER-4821"},{"name":"customerId","required":true,"in":"path","description":"Customer id of the authorized user.","schema":{"type":"string"},"example":"cus_9912"},{"name":"service","required":false,"in":"query","schema":{"type":"string"},"description":"Service key."}],"responses":{"200":{"description":"Authorization status and limits","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"authorized":{"type":"boolean","example":true},"spendingLimit":{"type":"number","example":5000}}}}}},"400":{"description":"Merchant ID is required — The merchant id path segment is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Merchant ID is required","path":"/crm/merchant-customers/authorized/{id}/{customerId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Merchant account not found — No merchant account has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Merchant account not found","path":"/crm/merchant-customers/authorized/{id}/{customerId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Merchant accounts"],"description":"Reports whether a customer may charge to an account, and under what limits. Call this before letting someone put something on account.\n\n#### Signature\n\n```http\nGET /crm/merchant-customers/authorized/{id}/{customerId} (id: string, customerId: string, service?: string) -> Authorization status and limits\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | MISSING_MERCHANT_ID | Merchant ID is required | The merchant id path segment is empty. | Supply the account id. |\n| `404` | MERCHANT_NOT_FOUND | Merchant account not found | No merchant account has that id. | List accounts with `GET /crm/merchant-customers/detail`. The body carries `code: \"MERCHANT_NOT_FOUND\"` and the `merchantId`. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/merchant-customers/charge/{id}`"}},"/crm/contact-form/post/{app}/{name}":{"post":{"operationId":"CrmFormController_saveContactFormPost","summary":"Submit a contact form (multipart)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"app","required":true,"in":"path","schema":{"type":"string"},"description":"Application the form belongs to.","example":"website"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name.","example":"contact-us"},{"name":"type","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"201":{"description":"The submission result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"],"description":"Public. Accepts a website contact form as `multipart/form-data`, so a plain HTML `<form method=\"post\" enctype=\"multipart/form-data\">` can post straight here. Uploaded files are stored under `form-data/{app}/{name}/` and replaced in the body by `{ originalName, mimeType, extension, size, path, signedUrl }`; the rest is handled as the JSON variant.\n\n#### Signature\n\n```http\nPOST /crm/contact-form/post/{app}/{name} (app: string, name: string, type?: string, body) -> The submission result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/contact-form/json/{app}/{name}`","requestBody":{"description":"The submitted values and files.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":true}}}}}},"/crm/contact-form/json/{app}/{name}":{"post":{"operationId":"CrmFormController_saveContactFormJSON","summary":"Submit a contact form as JSON","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"app","required":true,"in":"path","schema":{"type":"string"},"description":"Application the form belongs to.","example":"website"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name.","example":"contact-us"},{"name":"type","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"201":{"description":"The submission result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Error saving data: <reason> — The submission could not be stored.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Error saving data: <reason>","path":"/crm/contact-form/json/{app}/{name}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"],"description":"Public. The first post for a new `name` creates the `crm_form` (its schema generated from the body's shape) so later posts validate against it; each submission is stored in `form_submission`.\n\n#### Signature\n\n```http\nPOST /crm/contact-form/json/{app}/{name} (app: string, name: string, type?: string, body) -> The submission result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SAVE_FAILED | Error saving data: <reason> | The submission could not be stored. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/contact-form/post/{app}/{name}`","requestBody":{"description":"The submitted values.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Ada Lovelace","email":"ada@example.com","message":"When do you ship to Ireland?"}}}}}},"/crm/form/{name}":{"get":{"operationId":"CrmFormController_getCRMForm","summary":"Open a form","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name (or a publicly shared collection name).","example":"contact-us"},{"name":"code","required":false,"in":"query","schema":{"type":"string"},"description":"Access code or participant code."},{"name":"x-form-code","required":false,"in":"header","schema":{"type":"string"},"description":"Access code (alternative to `code`)."},{"name":"email","required":false,"in":"query","schema":{"type":"string"},"description":"For forms whose authenticationType is `email`."},{"name":"token","required":false,"in":"query","schema":{"type":"string"},"description":"Token from a magic link or one-time code email."},{"name":"x-form-token","required":false,"in":"header","schema":{"type":"string"},"description":"Link token (alternative to `token`)."},{"name":"sign","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ form, collection, schema, authenticationType, authentication, participant, submitter, session, displayName, logo }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"This form needs an access code. — authenticationType `code` with a shared `accessCode` and no code sent. Body `reason: \"code-required\"`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"This form needs an access code.","path":"/crm/form/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This form is not available for public access — An explicit `read` list leaves out Guest (a collection: \"This collection is not shared publicly\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This form is not available for public access","path":"/crm/form/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No form or collection found with name <name> — No crm_form and no collection by that name (a form bound to a missing collection: \"Collection not found\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No form or collection found with name <name>","path":"/crm/form/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"],"description":"Public. What a visitor needs to draw and send a form — never the internal record. The reply carries `form` (name, title, description, submitMessage, authenticationType, status, dates, schema, pages), `collection` for a collection-bound form, the `schema` to render, `authentication` (`{ required, type, satisfied }`), `participant`, `submitter`, `session` (the pending submission a link/code opened, with any saved `values`), `displayName` and `logo`.\n\nGates, in order: the form (or a collection shared under that name) must exist; an explicit `read` list must include `Guest` (a form with no `read` list is open; a collection never is unless shared); the form must be open (status and start/end dates); and its ONE access setting, `authenticationType`, must be met: `none` asks nothing, `code` needs the shared `accessCode` or a participant's own code (from their invitation link), `magic-link` the token from the emailed link or one-time code, `email` an address, `password` a signed-in customer. A non-empty `participants` list is the allow-list for `email` and `magic-link` too. Records still carrying the old `accessMode` `code`/`participants` read as `code`. Refusals carry `{ message, reason, title }` so the page can ask for the right thing.\n\n#### Signature\n\n```http\nGET /crm/form/{name} (name: string, code?: string, email?: string, token?: string) -> { form, collection, schema, authenticationType, authentication, participant, submitter, session, displayName, logo }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FORM_NOT_FOUND | No form or collection found with name <name> | No crm_form and no collection by that name (a form bound to a missing collection: \"Collection not found\"). | — |\n| `403` | NOT_PUBLIC | This form is not available for public access | An explicit `read` list leaves out Guest (a collection: \"This collection is not shared publicly\"). | — |\n| `401` | CODE_REQUIRED | This form needs an access code. | authenticationType `code` with a shared `accessCode` and no code sent. Body `reason: \"code-required\"`. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/form/submit/{name}/{email}`\n- `POST /crm/form/{name}/access`"}},"/crm/form/{name}/access":{"post":{"operationId":"CrmFormController_requestFormAccess","summary":"Ask for a form link or code","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name.","example":"grant-application"}],"responses":{"201":{"description":"{ sent: true, email, via, session }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid email address is required — `email` missing or has no @.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid email address is required","path":"/crm/form/{name}/access","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This form is by invitation. Open it from the link you were sent. — The form has `participants` and the address is not one of them (`reason: \"not-a-participant\"`).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This form is by invitation. Open it from the link you were sent.","path":"/crm/form/{name}/access","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No form named <name> — No crm_form with that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No form named <name>","path":"/crm/form/{name}/access","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"],"description":"Public. For a form whose authenticationType is `magic-link`: the person gives their email and a link (or one-time code) that opens a pending submission is emailed to them. When the form has `participants`, only a listed address is sent one. Nothing about the form is revealed by asking.\n\n#### Signature\n\n```http\nPOST /crm/form/{name}/access (name: string, body) -> { sent: true, email, via, session }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | EMAIL_REQUIRED | A valid email address is required | `email` missing or has no @. | — |\n| `404` | FORM_NOT_FOUND | No form named <name> | No crm_form with that name. | — |\n| `403` | BY_INVITATION | This form is by invitation. Open it from the link you were sent. | The form has `participants` and the address is not one of them (`reason: \"not-a-participant\"`). | — |\n\nPlus the standard platform errors: `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}}},"example":{"email":"ada@example.com"}}}}}},"/crm/form/submit/{name}/{email}":{"post":{"operationId":"CrmFormController_submitCRMForm","summary":"Submit a form","description":"Public. Submits a completed form. The same gates as `GET /crm/form/{name}` apply first; then the identity the form asks for is checked for submitting, an explicit `create` list must include `Guest` (only a collection shared on its own, with no form, must grant it — a collection bound to a CRM form needs no Guest permission; never add one), and the body is validated against the schema — missing required fields come back as \"Please fill in <field titles>.\" The access code may be sent as `accessCode` in the body, `x-form-code` or `?code=`; a link token as `token`, `x-form-token` or `?token=`.\n\n#### Signature\n\n```http\nPOST /crm/form/submit/{name}/{email} (name: string, email: string, body) -> The saved submission (form_submission, or a record of the bound collection)\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Notification email to the form's `data.emails` is billed. An org without credit still stores the submission but sends nothing, so do not rely on the email as your only signal.\n- Guard the client against double submission. Disabling the button is not enough; a second submit event produces a second record.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | FORM_DATA_REQUIRED | Form data is required | Empty body. | — |\n| `404` | FORM_NOT_FOUND | No form or collection found with name <name> | No crm_form and no collection by that name (a form bound to a missing collection: \"Collection not found\"). | — |\n| `403` | NOT_PUBLIC | This form is not available for public access | An explicit `read` list leaves out Guest (a collection: \"This collection is not shared publicly\"). | — |\n| `401` | CODE_REQUIRED | This form needs an access code. | authenticationType `code` with a shared `accessCode` and no code sent. Body `reason: \"code-required\"`. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /crm/form/{name}`\n- `POST /client/forms/{name}/submit`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name.","example":"contact-us"},{"name":"email","required":true,"in":"path","schema":{"type":"string"},"description":"Submitter email, when known (also read from `body.email`).","example":"ada@example.com"}],"requestBody":{"description":"The submitted values, as a flat object keyed by the schema's field names.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Ada Lovelace","email":"ada@example.com","message":"When do you ship to Ireland?"}}}},"responses":{"201":{"description":"The saved submission (form_submission, or a record of the bound collection)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Form data is required — Empty body.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Form data is required","path":"/crm/form/submit/{name}/{email}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"This form needs an access code. — authenticationType `code` with a shared `accessCode` and no code sent. Body `reason: \"code-required\"`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"This form needs an access code.","path":"/crm/form/submit/{name}/{email}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This form is not available for public access — An explicit `read` list leaves out Guest (a collection: \"This collection is not shared publicly\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This form is not available for public access","path":"/crm/form/submit/{name}/{email}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No form or collection found with name <name> — No crm_form and no collection by that name (a form bound to a missing collection: \"Collection not found\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No form or collection found with name <name>","path":"/crm/form/submit/{name}/{email}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"]}},"/crm/form/{name}/invite":{"post":{"operationId":"CrmFormController_inviteParticipants","summary":"Invite a form's participants","description":"Staff only. Emails each participant their own link and access code (a code is minted for anyone without one). Pass `emails` to send to those participants only; omit it for everyone. Safe to repeat: a resend is marked as a reminder and never changes a code, so a link already sent keeps working. Uses the form's `invitationTemplate`, else `form-invitation`. A `new` form becomes `sent`.\n\n**A form with a document to sign** (`data.signing` with a PDF) sends a signing request instead: each call without `emails` opens a new `signed_document` envelope for this send. Participants whose `role` is a signing role become its signers (one per role, in the signing order); anyone else listed gets the signed copy. Each signer gets their own link (`/form?form=<name>&sign=<token>`, template `signature-request`) — the first one now when signing is sequential, the next when the one before signs. With `emails` and an envelope still open, those signers are reminded. `context` (`{ datatype, id, label }`) links the envelope to the record it is for; without it, the first signer's contact is used when there is one.\n\n#### Signature\n\n```http\nPOST /crm/form/{name}/invite (name: string, body) -> { form, template, sent, failed, results: [{ email, sent, reminder, inviteCount, link }], participants } — for a signing form also `signing: true`, `envelope: { sk, status, signingOrder, expiresAt }`, and per result `role`, `queued` (emailed later) and `copyOnly`.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FORM_NOT_FOUND | No form named <name> | No crm_form with that name. | — |\n| `409` | NO_PARTICIPANTS | This form has no participants to invite. | The form lists no participants. | — |\n| `400` | BAD_DOCUMENT | The document “<name>” could not be read. | Signing form: a document is missing, not a PDF, or a spot sits on a page or document that does not exist. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name.","example":"grant-application"}],"responses":{"201":{"description":"{ form, template, sent, failed, results: [{ email, sent, reminder, inviteCount, link }], participants } — for a signing form also `signing: true`, `envelope: { sk, status, signingOrder, expiresAt }`, and per result `role`, `queued` (emailed later) and `copyOnly`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The document “<name>” could not be read. — Signing form: a document is missing, not a PDF, or a spot sits on a page or document that does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The document “<name>” could not be read.","path":"/crm/form/{name}/invite","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No form named <name> — No crm_form with that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No form named <name>","path":"/crm/form/{name}/invite","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This form has no participants to invite. — The form lists no participants.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This form has no participants to invite.","path":"/crm/form/{name}/invite","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Signing forms: the record the envelope is for."},"expiresInDays":{"type":"integer","description":"Signing forms: overrides the form's expiry."}}},"example":{"emails":["ada@example.com"]}}}}}},"/crm/forms/overview":{"get":{"operationId":"CrmFormController_getFormsOverview","summary":"Forms overview","description":"Staff only. Everything the Forms dashboard shows: totals (forms, public, open, collection-bound, on a workflow, in a workflow now, started-not-finished, submissions, submissions in the period, awaiting review), counts by status, a row per form with its own numbers, and the most recent submissions. Counts cover inline forms (`form_submission`) and collection-bound forms (records of the bound collection).\n\n#### Signature\n\n```http\nGET /crm/forms/overview (period?: string) -> { period, since, totals, byStatus, forms, recent }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"period","required":false,"in":"query","schema":{"type":"string","enum":["today","week","month","year"],"default":"week"}}],"responses":{"200":{"description":"{ period, since, totals, byStatus, forms, recent }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"]}},"/crm/forms/submissions":{"get":{"operationId":"CrmFormController_listAllSubmissions","summary":"All form submissions","description":"Staff only. Submissions across every form, newest first, paged. Each row carries the form it answers and, when it is on a workflow, `workflowInfo` (workflow, named stage, task, stage history).\n\n#### Signature\n\n```http\nGET /crm/forms/submissions (formId?: string, status?: string, email?: string, inWorkflow?: string, page?: integer, pageSize?: integer) -> { data, total, page, pageSize }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"formId","required":false,"in":"query","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string"}},{"name":"email","required":false,"in":"query","schema":{"type":"string"}},{"name":"inWorkflow","required":false,"in":"query","schema":{"type":"string","enum":["true"]}},{"name":"page","required":false,"in":"query","schema":{"type":"integer"}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"{ data, total, page, pageSize }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"]}},"/crm/collection-form/{number}/{demo}-email?":{"post":{"operationId":"CrmFormController_sendCRMForm","summary":"Send a form to its participants (legacy)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"number","required":true,"in":"path","schema":{"type":"string"},"description":"Ignored.","example":"4821"},{"name":"demo-email","required":true,"in":"path","schema":{"type":"string"}},{"name":"demo","in":"path","required":true,"description":"Ignored.","schema":{"type":"string"},"example":"ada"}],"responses":{"201":{"description":"Same as the invite route","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"form name is required — No form name in the body.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"form name is required","path":"/crm/collection-form/{number}/{demo}-email?","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"],"description":"Staff. Kept for older clients: takes the form name from `body.name` (or `body.form.data.name`) and does exactly what `POST /crm/form/{name}/invite` does, including `body.emails`. The path segments are ignored. The route is declared as `collection-form/:number/:demo-email?`, which Express reads as a parameter `demo` followed by the literal text `-email?` — prefer the invite route.\n\n#### Signature\n\n```http\nPOST /crm/collection-form/{number}/{demo}-email? (number: string, demo: string, body) -> Same as the invite route\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAME_REQUIRED | form name is required | No form name in the body. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/form/{name}/invite`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}}}},"example":{"name":"grant-application"}}}}}},"/crm/form/{id}":{"delete":{"operationId":"CrmFormController_deleteForm","summary":"Delete a form","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Forms"],"description":"Staff only. Deletes the form definition (`crm_form`). Its submissions are not deleted.\n\n#### Signature\n\n```http\nDELETE /crm/form/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `User`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/client/forms/{name}":{"get":{"operationId":"CrmFormClientController_getForm","summary":"Open a form (customer)","description":"The customer-facing twin of `GET /crm/form/{name}`: same gates and same reply. A signed-in customer is taken from the token (never from the request), which satisfies a `password` form and is the submitter.\n\n**Signing link** (`sign=<token>`): the envelope the token belongs to is the proof of who this is, so the form's own access setting and window do not apply. The reply carries only that signer's part of the form (fields marked with their `signerRole`, or unmarked fields for the first signer) and `signing`: the documents (`path` to read each PDF), the spots they fill (PDF points from the bottom-left of the page), others' spots, who else signs, the consent wording and the expiry. When it is not theirs to sign now, it answers `reason` sign-invalid (404), sign-waiting (409), or sign-signed / sign-completed / sign-declined / sign-cancelled / sign-voided / sign-expired (410) with `title`, `message` and, where there is something to show (a completed copy to download), `signing`.\n\n#### Signature\n\n```http\nGET /client/forms/{name} (name: string, code?: string, email?: string, token?: string, sign?: string) -> As `GET /crm/form/{name}`, plus `signing` on a signing link\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | FORM_NOT_FOUND | No form or collection found with name <name> | No crm_form and no collection by that name (a form bound to a missing collection: \"Collection not found\"). | — |\n| `403` | NOT_PUBLIC | This form is not available for public access | An explicit `read` list leaves out Guest (a collection: \"This collection is not shared publicly\"). | — |\n| `401` | CODE_REQUIRED | This form needs an access code. | authenticationType `code` with a shared `accessCode` and no code sent. Body `reason: \"code-required\"`. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /crm/form/{name}`\n- `POST /client/forms/{name}/submit`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name.","example":"contact-us"},{"name":"code","required":false,"in":"query","schema":{"type":"string"}},{"name":"x-form-code","required":false,"in":"header","schema":{"type":"string"}},{"name":"email","required":false,"in":"query","schema":{"type":"string"}},{"name":"token","required":false,"in":"query","schema":{"type":"string"}},{"name":"x-form-token","required":false,"in":"header","schema":{"type":"string"}},{"name":"sign","required":false,"in":"query","schema":{"type":"string"},"description":"A signer's token from their signing email."}],"responses":{"200":{"description":"As `GET /crm/form/{name}`, plus `signing` on a signing link","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"This form needs an access code. — authenticationType `code` with a shared `accessCode` and no code sent. Body `reason: \"code-required\"`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"This form needs an access code.","path":"/client/forms/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This form is not available for public access — An explicit `read` list leaves out Guest (a collection: \"This collection is not shared publicly\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This form is not available for public access","path":"/client/forms/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No form or collection found with name <name> — No crm_form and no collection by that name (a form bound to a missing collection: \"Collection not found\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No form or collection found with name <name>","path":"/client/forms/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Forms Client"]}},"/client/forms/{name}/access":{"post":{"operationId":"CrmFormClientController_requestAccess","summary":"Ask for a form link or code (customer)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name."}],"responses":{"201":{"description":"{ sent: true, email, via, session }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Forms Client"],"description":"Same as `POST /crm/form/{name}/access`.\n\n#### Signature\n\n```http\nPOST /client/forms/{name}/access (name: string, body) -> { sent: true, email, via, session }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/form/{name}/access`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}}}}}}}},"/client/forms/{name}/submit":{"post":{"operationId":"CrmFormClientController_submit","summary":"Submit a form (customer)","description":"Same as `POST /crm/form/submit/{name}/{email}`, with the submitter email as `?email=` instead of a path segment.\n\n**Signature fields** (`x-control: signature`) take `{ image?: PNG/JPEG data URL (about 300 KB at most), typedName?, consent: true }` and are checked by the e-signature rules (consent, something signed, image type and size, the field's `signatureModes`); a required one left unsigned is refused. A drawn image is stored as a **private file**; the submission keeps `data.signatures[]` — `{ role, name, email, typedName, method, file, consent, signedAt, ipAddress, userAgent }` — and only a summary in `values`, never the image.\n\n**Signing link** (`?sign=<token>`): also send `__signing: { consent: true, signature: { image? | typedName }, initials?: {...}, spots?: { [spotId]: { text } } }`. Every spot assigned to the signer must be covered (a spot linked to a field takes that answer or signature). It is all checked before anything is saved; then the submission is stored, the spots are filled, the next signer is emailed (sequential) or the signed PDF is made (last signature). The reply adds `signing: { envelopeId, envelopeStatus, signedAt, next }`.\n\n#### Signature\n\n```http\nPOST /client/forms/{name}/submit (name: string, email?: string, code?: string, token?: string, sign?: string, body) -> The saved submission (plus `signing` on a signing link)\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SIGNATURE_INVALID | “<field>” is required — please sign it (draw it or type your name). | A required signature field is empty, consent is missing, the image is not PNG/JPEG/SVG or too large, or the field asks for drawn/typed only. Body `errors` lists every problem. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/form/submit/{name}/{email}`\n- `GET /client/forms/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name."},{"name":"email","required":false,"in":"query","schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"}},{"name":"sign","in":"query","required":false,"description":"A signer's token.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"The saved submission (plus `signing` on a signing link)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"“<field>” is required — please sign it (draw it or type your name). — A required signature field is empty, consent is missing, the image is not PNG/JPEG/SVG or too large, or the field asks for drawn/typed only. Body `errors` lists every problem.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"“<field>” is required — please sign it (draw it or type your name).","path":"/client/forms/{name}/submit","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Forms Client"]}},"/client/forms/{name}/sign/{token}/decline":{"post":{"operationId":"CrmFormClientController_decline","summary":"Decline to sign (signing link)","description":"The signer declines with a reason (required). The envelope closes as declined; the sender and anyone already sent it are emailed.\n\n#### Signature\n\n```http\nPOST /client/forms/{name}/sign/{token}/decline (name: string, token: string, body) -> `{ status: \"declined\", envelopeId }`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SIGN_INVALID | This signing link is not valid. | The token is unknown or belongs to another form. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name."},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"The signer's token."}],"responses":{"201":{"description":"`{ status: \"declined\", envelopeId }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"This signing link is not valid. — The token is unknown or belongs to another form.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"This signing link is not valid.","path":"/client/forms/{name}/sign/{token}/decline","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Forms Client"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"The fee schedule is wrong"}}}}}},"/client/forms/{name}/sign/{token}/document":{"get":{"operationId":"CrmFormClientController_document","summary":"The document being signed (signing link)","description":"The private snapshot of the PDF the signer is signing, read with their token (`file` picks one of several, 0-based).\n\n#### Signature\n\n```http\nGET /client/forms/{name}/sign/{token}/document (name: string, token: string, file?: string) -> The PDF\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name."},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"The signer's token."},{"name":"file","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The PDF"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Forms Client"]}},"/client/forms/{name}/sign/{token}/download":{"get":{"operationId":"CrmFormClientController_download","summary":"The signed copy (signing link)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Form name."},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"The participant's token."}],"responses":{"200":{"description":"The PDF"},"409":{"description":"The signed copy is ready once everyone has signed. — Not everyone has signed yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"The signed copy is ready once everyone has signed.","path":"/client/forms/{name}/sign/{token}/download","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Forms Client"],"description":"Once everyone has signed: the signed PDF with its certificate of completion, for any participant of the envelope (signers and copy recipients). The link in the completion email opens the form page, which offers this download.\n\n#### Signature\n\n```http\nGET /client/forms/{name}/sign/{token}/download (name: string, token: string) -> The PDF\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `409` | NOT_COMPLETE | The signed copy is ready once everyone has signed. | Not everyone has signed yet. | — |\n\nPlus the standard platform errors: `429`, `500`."}},"/crm/signed-documents":{"get":{"operationId":"SignedDocumentController_list","summary":"List signed documents","description":"Every envelope sent for signature, newest first, **searched and paged on the server**. A form with a document (its `signing`) opens one envelope each time its participants are sent it (`POST /crm/form/{name}/invite`).\n\nEach row carries `data.summary` — `{ signers, signed, waitingOn[], needsAttention }` — and never the participants' tokens.\n\n#### Signature\n\n```http\nGET /crm/signed-documents (q?: string, status?: string, formId?: string, page?: string, pageSize?: string) -> `{ data, total, page, pageSize }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/signed-documents/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"q","required":false,"in":"query","schema":{"type":"string"},"description":"Searches the title, the form and every participant's name and email."},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"draft | sent | in_progress | completed | declined | cancelled | voided | expired; `open` (sent or in progress) or `needs-attention` (everyone signed but the PDF failed to build)."},{"name":"formId","required":false,"in":"query","schema":{"type":"string"},"description":"Only envelopes sent from this form (its sk or name)."},{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Rows per page (central default; held to the maximum).","schema":{"type":"string"}}],"responses":{"200":{"description":"`{ data, total, page, pageSize }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"]},"post":{"operationId":"SignedDocumentController_create","summary":"Create a signed document (draft)","description":"Creates an envelope without a form. It starts as a draft; `POST /crm/signed-documents/{id}/send` sends it. Most envelopes are opened by a form instead (`POST /crm/form/{name}/invite` on a form with a document).\n\nSpot positions are **PDF points (1/72 in) from the bottom-left of the page as shown**, the spot's bottom-left corner; `type` is signature | initials | date | name | text; `assignedTo` is a participant's `participantId`.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents (body) -> The draft envelope\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/{id}/send`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The draft envelope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"requestBody":{"description":"The envelope.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","example":"Storage agreement"},"files":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"PDFs: `{ path, name }` (copied privately and fingerprinted at send)."},"participants":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"`{ participantId?, name, email, role, order }`; role `cc` only gets the signed copy."},"signatureFields":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"`{ signatureId?, fileIndex, page, x, y, width, height, type, assignedTo, required?, label? }`"},"signingOrder":{"type":"string","enum":["parallel","sequential"]},"expiresAt":{"type":"string","format":"date-time"},"context":{"type":"object","description":"`{ datatype, id, label }` — the record it is for."}}},"example":{"title":"Storage agreement","files":[{"path":"docs/storage.pdf","name":"storage.pdf"}],"participants":[{"participantId":"p1","name":"Ada Lovelace","email":"ada@example.com","role":"client","order":1}],"signatureFields":[{"fileIndex":0,"page":1,"x":72,"y":96,"width":180,"height":40,"type":"signature","assignedTo":"p1"}],"signingOrder":"sequential"}}}}}},"/crm/signed-documents/context/{datatype}/{id}":{"get":{"operationId":"SignedDocumentController_listForContext","summary":"Get documents for a record","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"The record's datatype.","example":"customer"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Rows per page.","schema":{"type":"string"}}],"responses":{"200":{"description":"`{ data, total, page, pageSize }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"The envelopes sent for another record — a retainer on a contact, an offer letter on an employee. Paged like the list. A form's envelope is linked to its first signer's contact automatically, or to the `context` given when it was sent.\n\n#### Signature\n\n```http\nGET /crm/signed-documents/context/{datatype}/{id} (datatype: string, id: string, page?: string, pageSize?: string) -> `{ data, total, page, pageSize }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/form/{name}/invite`"}},"/crm/signed-documents/{id}":{"get":{"operationId":"SignedDocumentController_get","summary":"Get a signed document","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"One envelope: participants (each with their own `link`, status, and once signed their signature method, consent, IP and user agent), the spots and what was put in each, the documents' SHA-256 fingerprints, `merge` (building the signed PDF) and the full `auditEvents` trail. Tokens are never returned.\n\n#### Signature\n\n```http\nGET /crm/signed-documents/{id} (id: string) -> The envelope\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /crm/signed-documents/{id}/download`"},"delete":{"operationId":"SignedDocumentController_remove","summary":"Delete a signed document","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"Deletes an envelope and its audit trail. For anything sent or signed, **void it instead** — the signature record is legal evidence and deleting it destroys that.\n\n#### Signature\n\n```http\nDELETE /crm/signed-documents/{id} (id: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Destroys the signature audit trail. Use `void` for anything signed.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/{id}/void`"}},"/crm/signed-documents/{id}/download":{"get":{"operationId":"SignedDocumentController_download","summary":"Download the signed PDF (or an original)","description":"The signed PDF — every signature and value written in at the placed coordinates, followed by the **certificate of completion** (signers, emails, timestamps, IPs, the audit events and the SHA-256 of the original and of the signed document) — or, with `which=original&file=n`, the snapshot that was sent. The files are stored **privately**: this route and the participant's own token are the only ways to them.\n\n#### Signature\n\n```http\nGET /crm/signed-documents/{id}/download (id: string, which?: string, file?: string) -> The PDF\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n| `409` | — | There is no signed copy yet. | There is no signed copy yet (not everyone has signed, or the PDF is still being built). | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"which","required":false,"in":"query","schema":{"type":"string"},"description":"`final` (default) or `original`."},{"name":"file","required":false,"in":"query","schema":{"type":"string"},"description":"Which original, 0-based (envelopes can hold several PDFs)."}],"responses":{"200":{"description":"The PDF"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}/download","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"There is no signed copy yet. — There is no signed copy yet (not everyone has signed, or the PDF is still being built).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"There is no signed copy yet.","reason":"not-complete"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"]}},"/crm/signed-documents/{id}/update":{"post":{"operationId":"SignedDocumentController_update","summary":"Update a draft signed document","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The updated envelope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Cannot edit a sent document — cancel and recreate — The envelope was already sent.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Cannot edit a sent document — cancel and recreate"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"Changes a draft before it is sent. A sent envelope cannot be edited (409): cancel or void it and send again.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/{id}/update (id: string, body) -> The updated envelope\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n| `409` | — | Cannot edit a sent document — cancel and recreate | The envelope was already sent. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/{id}/void`","requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"title":"Storage agreement (2026)"}}}}}},"/crm/signed-documents/{id}/send":{"post":{"operationId":"SignedDocumentController_send","summary":"Send a draft for signature","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The sent envelope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This document was already sent. — It is not a draft.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This document was already sent."}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"Copies the PDFs privately (fingerprinting each), then emails the first signer (sequential) or every signer (parallel) their own link with the `signature-request` template. Later signers in a sequential envelope are emailed when the one before them signs.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/{id}/send (id: string) -> The sent envelope\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n| `409` | — | This document was already sent. | It is not a draft. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/{id}/remind`"}},"/crm/signed-documents/{id}/remind":{"post":{"operationId":"SignedDocumentController_remind","summary":"Remind signers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"`{ reminded: [emails], reminderCount }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}/remind","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This document is completed; there is no one to remind. — The envelope is closed, or everyone sent it has signed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This document is completed; there is no one to remind."}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"Emails the signing link again to everyone who has been sent it and has not signed — or only `participantId`. The link is the same one; it keeps working.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/{id}/remind (id: string, body) -> `{ reminded: [emails], reminderCount }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n| `409` | — | This document is completed; there is no one to remind. | The envelope is closed, or everyone sent it has signed. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/{id}/cancel`","requestBody":{"description":"Optional: one participant.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"participantId":{"type":"string"}}}}}}}},"/crm/signed-documents/{id}/cancel":{"post":{"operationId":"SignedDocumentController_cancel","summary":"Cancel a signature request","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The cancelled envelope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"Withdraws an envelope before it is complete. Every link stops working (the signer sees \"cancelled\"), and everyone already sent it is emailed (`signature-cancelled`). The record and its audit trail are kept.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/{id}/cancel (id: string, body) -> The cancelled envelope\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/{id}/void`","requestBody":{"description":"Why.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","example":"Sent the wrong version"}}}}}}}},"/crm/signed-documents/{id}/void":{"post":{"operationId":"SignedDocumentController_voidIt","summary":"Void a signed document","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The voided envelope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}/void","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"Marks an envelope — including a completed one — as no longer in force while **keeping the signature record intact**. Cancel applies before signature, delete destroys the evidence, void preserves it.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/{id}/void (id: string, body) -> The voided envelope\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/{id}/cancel`","requestBody":{"description":"Why.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/crm/signed-documents/{id}/retry-merge":{"post":{"operationId":"SignedDocumentController_retryMerge","summary":"Build the signed PDF again","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"`{ status, merge }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Document not found — No document has that identifier.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Document not found","path":"/crm/signed-documents/{id}/retry-merge","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Not everyone has signed yet. — Not everyone has signed, or it is already complete.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Not everyone has signed yet."}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"When everyone has signed but building the signed PDF failed, the envelope stays open (`merge.status: failed`), the owner is emailed, and the `signed-document-upkeep` job retries it. This retries it now.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/{id}/retry-merge (id: string) -> `{ status, merge }`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | NOT_FOUND | Document not found | No document has that identifier. | Check the identifier against the corresponding list endpoint. |\n| `409` | — | Not everyone has signed yet. | Not everyone has signed, or it is already complete. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/signed-documents/portal/{token}":{"get":{"operationId":"SignedDocumentController_getByToken","summary":"Signer view by token (no form)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"The participant's signing token (from their email).","example":"Xk2mH9…"}],"responses":{"200":{"description":"The signer view","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"The **public** read for an envelope sent without a form: the document list, the spots this participant fills, who else signs and where things stand (`state`: ready | waiting | signed | declined | completed | cancelled | voided | expired). The token is the only credential. Signers of a form's envelope open `GET /client/forms/{name}?sign={token}` instead.\n\n#### Signature\n\n```http\nGET /crm/signed-documents/portal/{token} (token: string) -> The signer view\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated. Treat signing links as secrets.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/portal/{token}/sign`"}},"/crm/signed-documents/portal/{token}/sign":{"post":{"operationId":"SignedDocumentController_sign","summary":"Sign by token (no form)","description":"Fills every spot assigned to this participant. The signature follows the e-signature rules: `consent: true`, a drawn PNG/JPEG data URL (about 300 KB at most) or a typed name. A drawn image is stored as a **private file**. Initials can be drawn or typed (typed initials default to the name's). Text and name spots take `spots[spotId].text`. Irreversible — a signed document can be voided but not unsigned.\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/portal/{token}/sign (token: string, body) -> `{ envelopeId, envelopeStatus, signedAt, next }`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | — | Tick the box to agree to sign electronically. | No consent, no signature, or a spot left empty. | — |\n| `409` | — | Someone else signs before you. | Not this signer's turn yet (sequential). | — |\n| `410` | — | The time to sign this document has passed. | Already signed, or the envelope is completed, declined, cancelled, voided or expired. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/portal/{token}/decline`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"Signing token.","example":"Xk2mH9…"}],"requestBody":{"description":"Consent and the signature.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"consent":{"type":"boolean","example":true},"signature":{"type":"object","properties":{"image":{"type":"string"},"typedName":{"type":"string"}}},"initials":{"type":"object","properties":{"image":{"type":"string"},"typedName":{"type":"string"}}},"spots":{"type":"object","additionalProperties":{"type":"object","properties":{"text":{"type":"string"}}}}}},"example":{"consent":true,"signature":{"typedName":"Ada Lovelace"},"spots":{"spot-name":{"text":"Ada Lovelace"}}}}}},"responses":{"201":{"description":"`{ envelopeId, envelopeStatus, signedAt, next }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Tick the box to agree to sign electronically. — No consent, no signature, or a spot left empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Tick the box to agree to sign electronically.","code":"SIGNATURE_INVALID","errors":["Tick the box to agree to sign electronically."]}}}},"409":{"description":"Someone else signs before you. — Not this signer's turn yet (sequential).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Someone else signs before you.","reason":"sign-waiting"}}}},"410":{"description":"The time to sign this document has passed. — Already signed, or the envelope is completed, declined, cancelled, voided or expired.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":410,"error":"The time to sign this document has passed.","reason":"sign-expired"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"]}},"/crm/signed-documents/portal/{token}/decline":{"post":{"operationId":"SignedDocumentController_decline","summary":"Decline to sign","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"Signing token.","example":"Xk2mH9…"}],"responses":{"201":{"description":"`{ status: \"declined\", envelopeId }`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Say why you are declining. — No reason given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Say why you are declining.","reason":"reason-required"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"Records that the signer declined, with their reason (required). The envelope closes as `declined`, nobody else can sign it, and the sender and anyone already sent it are emailed (`signature-declined`).\n\n#### Signature\n\n```http\nPOST /crm/signed-documents/portal/{token}/decline (token: string, body) -> `{ status: \"declined\", envelopeId }`\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | — | Say why you are declining. | No reason given. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /crm/signed-documents/portal/{token}/sign`","requestBody":{"description":"Why they declined.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","example":"The fee schedule is wrong"}}},"example":{"reason":"The fee schedule is wrong"}}}}}},"/crm/signed-documents/portal/{token}/document":{"get":{"operationId":"SignedDocumentController_document","summary":"The document being signed (by token)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"Signing token.","example":"Xk2mH9…"},{"name":"file","required":false,"in":"query","schema":{"type":"string"},"description":"Which document, 0-based."}],"responses":{"200":{"description":"The PDF"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"The PDF snapshot the participant signs (`file` picks one of several, 0-based). Refused once the envelope is cancelled, voided or expired.\n\n#### Signature\n\n```http\nGET /crm/signed-documents/portal/{token}/document (token: string, file?: string) -> The PDF\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`."}},"/crm/signed-documents/portal/{token}/download":{"get":{"operationId":"SignedDocumentController_downloadSigned","summary":"The signed copy (by token)","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"token","required":true,"in":"path","schema":{"type":"string"},"description":"Signing token.","example":"Xk2mH9…"}],"responses":{"200":{"description":"The PDF"},"409":{"description":"The signed copy is ready once everyone has signed. — Not everyone has signed yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"The signed copy is ready once everyone has signed.","reason":"not-complete"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Documents"],"description":"The signed PDF with its certificate of completion, once everyone has signed — for every participant, including those who only get a copy.\n\n#### Signature\n\n```http\nGET /crm/signed-documents/portal/{token}/download (token: string) -> The PDF\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `409` | — | The signed copy is ready once everyone has signed. | Not everyone has signed yet. | — |\n\nPlus the standard platform errors: `429`, `500`."}},"/crm/shared-accounts":{"get":{"operationId":"SharedAccountsController_list","summary":"List shared accounts","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer"}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"{ total, page, pageSize, data }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"Every shared account in the org, assembled: the account, its members (with names), pending invitations, `memberCount` and `needsManager` (members but no manager). An account holding only pending invitations is listed too. `search` matches the account, any member or any of its groups. Sorted by member count, then name.\n\n#### Signature\n\n```http\nGET /crm/shared-accounts (search?: string, page?: integer, pageSize?: integer) -> { total, page, pageSize, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/shared-accounts/{accountId}":{"get":{"operationId":"SharedAccountsController_get","summary":"Get a shared account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The account","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"One account, assembled as in the list.\n\n#### Signature\n\n```http\nGET /crm/shared-accounts/{accountId} (accountId: string) -> The account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/shared-accounts/{accountId}/orders":{"get":{"operationId":"SharedAccountsController_orders","summary":"Shared account orders","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"page","required":false,"in":"query","schema":{"type":"integer"}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Paged orders","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"Orders placed on the account by any member.\n\n#### Signature\n\n```http\nGET /crm/shared-accounts/{accountId}/orders (accountId: string, page?: integer, pageSize?: integer) -> Paged orders\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/shared-accounts/{accountId}/activity":{"get":{"operationId":"SharedAccountsController_activity","summary":"Shared account activity","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"{ leads, deals, lost, tickets, messages, totals }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"The account's open leads, deals (leads at a won stage), lost count, tickets and the latest 100 conversations, with totals (open value, won value, open tickets, messages).\n\n#### Signature\n\n```http\nGET /crm/shared-accounts/{accountId}/activity (accountId: string) -> { leads, deals, lost, tickets, messages, totals }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/shared-accounts/{accountId}/members":{"post":{"operationId":"SharedAccountsController_addMember","summary":"Add someone to a shared account","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-host","required":false,"in":"header","schema":{"type":"string"},"description":"Storefront host for the invitation link."},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"`{ added, reinstated, customerId }` or `{ invited, resent, email }`, plus the assembled `account`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid email is required — `email` missing or has no @.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid email is required","path":"/crm/shared-accounts/{accountId}/members","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"An email that already belongs to a customer is associated straight away (a suspended member is reinstated) and told by email; a new email gets a pending invitation whose sign-up link points at `x-client-host`. `role` defaults to buyer.\n\n#### Signature\n\n```http\nPOST /crm/shared-accounts/{accountId}/members (accountId: string, body) -> `{ added, reinstated, customerId }` or `{ invited, resent, email }`, plus the assembled `account`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | EMAIL_REQUIRED | A valid email is required | `email` missing or has no @. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"role":{"type":"string","enum":["manager","buyer"]},"message":{"type":"string"}}},"example":{"email":"buyer@acme.com","role":"manager"}}}}}},"/crm/shared-accounts/{accountId}/members/{associationId}":{"put":{"operationId":"SharedAccountsController_updateMember","summary":"Change a shared account member","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"associationId","required":true,"in":"path","schema":{"type":"string"},"description":"customer_association sk."}],"responses":{"200":{"description":"The assembled account","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Nothing to change — pass a role or a status — Neither field given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Nothing to change — pass a role or a status","path":"/crm/shared-accounts/{accountId}/members/{associationId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Member not found on this account — The association does not exist or belongs to another account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Member not found on this account","path":"/crm/shared-accounts/{accountId}/members/{associationId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"Changes `role` or `status` (suspend / reinstate). Unlike the customer route, staff may leave an account with no manager — the returned account says so with `needsManager`.\n\n#### Signature\n\n```http\nPUT /crm/shared-accounts/{accountId}/members/{associationId} (accountId: string, associationId: string, body) -> The assembled account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | MEMBER_NOT_FOUND | Member not found on this account | The association does not exist or belongs to another account. | — |\n| `400` | NOTHING_TO_CHANGE | Nothing to change — pass a role or a status | Neither field given. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["manager","buyer"]},"status":{"type":"string","enum":["active","suspended"]}}},"example":{"role":"manager"}}}}},"delete":{"operationId":"SharedAccountsController_removeMember","summary":"Remove a shared account member","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"associationId","required":true,"in":"path","schema":{"type":"string"},"description":"customer_association sk."}],"responses":{"200":{"description":"The assembled account","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Member not found on this account — The association does not exist or belongs to another account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Member not found on this account","path":"/crm/shared-accounts/{accountId}/members/{associationId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"Unlinks the member. Their past orders are untouched.\n\n#### Signature\n\n```http\nDELETE /crm/shared-accounts/{accountId}/members/{associationId} (accountId: string, associationId: string) -> The assembled account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | MEMBER_NOT_FOUND | Member not found on this account | The association does not exist or belongs to another account. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/shared-accounts/{accountId}/invites/{invitationId}/cancel":{"post":{"operationId":"SharedAccountsController_cancelInvite","summary":"Withdraw an invitation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"invitationId","required":true,"in":"path","schema":{"type":"string"},"description":"customer_invitation sk."}],"responses":{"201":{"description":"The assembled account","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Invitation not found on this account — No such pending invitation on this account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Invitation not found on this account","path":"/crm/shared-accounts/{accountId}/invites/{invitationId}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["CRM · Shared accounts"],"description":"#### Signature\n\n```http\nPOST /crm/shared-accounts/{accountId}/invites/{invitationId}/cancel (accountId: string, invitationId: string) -> The assembled account\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | INVITE_NOT_FOUND | Invitation not found on this account | No such pending invitation on this account. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/crm/customers-benefits/overview":{"get":{"operationId":"CustomersOverviewController_overview","summary":"Customers & Benefits overview — the dashboard, computed server-side","description":"What needs someone (`attention`, each item naming the tab it opens), contacts (total, new in the period against the previous one, a trend with every bucket, reach by email/phone, account types, lead stages), customer groups (members by the same membership the Groups tab uses, benefits carried, unreadable rules), benefits (holders directly or through groups, applications waiting), benefit applications (by status, decided in the period, approval rate, days to decide, oldest waiting, ending in 30 days), shared accounts and prospects. A section that cannot be read answers `{ error }` and the rest still answer.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"period","required":false,"in":"query","schema":{"enum":["7d","30d","90d","12m"],"type":"string"}}],"responses":{"200":{"description":""}},"tags":["CRM Customers & Benefits"]}},"/analytics":{"get":{"operationId":"AnalyticsController_getAnalytics","summary":"Get analytics data","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"]},"description":"Dashboard type. Omit for all but email.","example":"storefront"},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Analytics data","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"orgId is required — The `orgid` header is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"orgId is required","path":"/analytics","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get analytics — The figures could not be computed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get analytics","path":"/analytics","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"The general analytics read. `type` selects one dashboard; omitting it returns `{ website, blog, workflow, storefront, tickets, leads, automation, users }` in one response (heavier, and `email` is only available by naming it). Unlike the per-area routes, this read carries no previous-window `comparison`.\n\n#### Signature\n\n```http\nGET /analytics (type?: string, startDate?: string, endDate?: string) -> Analytics data\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORGID_REQUIRED | orgId is required | The `orgid` header is missing. | Send the `orgid` header. |\n| `500` | ANALYTICS_FAILED | Failed to get analytics | The figures could not be computed. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics/website`"}},"/analytics/filter-options":{"get":{"operationId":"AnalyticsController_getFilterOptions","summary":"Get filter options","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Filter options","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"orgId is required — The `orgid` header is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"orgId is required","path":"/analytics/filter-options","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get filter options — The figures could not be computed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get filter options","path":"/analytics/filter-options","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Distinct sites, domains and hosts seen in web visit data over the last 90 days — what populates a dashboard's filter dropdowns. Derived from observed traffic, so a site with no visits in that window will not appear. Up to 100 of each.\n\n#### Signature\n\n```http\nGET /analytics/filter-options () -> Filter options\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORGID_REQUIRED | orgId is required | The `orgid` header is missing. | Send the `orgid` header. |\n| `500` | ANALYTICS_FAILED | Failed to get filter options | The figures could not be computed. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics/website`"}},"/analytics/sites":{"get":{"operationId":"AnalyticsController_getAnalyticsSites","summary":"The org sites the Website / Blog dashboards report on, the default one, and whether each has its blog on","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Analytics"]}},"/analytics/live-view":{"get":{"operationId":"AnalyticsController_getLiveView","summary":"Get Live View","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"minutes","required":false,"in":"query","description":"Window in minutes, default 15, minimum 1. Wider is less \"live\".","schema":{"type":"integer"},"example":5}],"responses":{"200":{"description":"Current visitors and metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"orgId is required — The `orgid` header is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"orgId is required","path":"/analytics/live-view","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get live view — The figures could not be computed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get live view","path":"/analytics/live-view","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Unique visitors on the site right now, with real-time aggregated metrics. `minutes` sets how far back \"now\" reaches — a wider window shows more people but stops being live.\n\nBuilt from the web-visit timeseries, so a visitor appears only once their first event has been recorded. Bots, scanners and probes are never recorded, so they never appear here. Refreshed about every 15 seconds; up to 500 visitors, most recently seen first.\n\n#### Signature\n\n```http\nGET /analytics/live-view (minutes?: integer) -> Current visitors and metrics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORGID_REQUIRED | orgId is required | The `orgid` header is missing. | Send the `orgid` header. |\n| `500` | ANALYTICS_FAILED | Failed to get live view | The figures could not be computed. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics/live-view/{deviceId}/journey`"}},"/analytics/live-view/{deviceId}/journey":{"get":{"operationId":"AnalyticsController_getLiveViewJourney","summary":"Get a visitor journey","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"deviceId","required":true,"in":"path","schema":{"type":"string"},"description":"Device identifier from Live View.","example":"dev_7Kq2M9"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"example":100}],"responses":{"200":{"description":"The journey","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"400":{"description":"orgId is required — The `orgid` header is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"orgId is required","path":"/analytics/live-view/{deviceId}/journey","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get device journey — The figures could not be computed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get device journey","path":"/analytics/live-view/{deviceId}/journey","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"The full timeline for one visitor — every page and event in order. `deviceId` identifies a browser, not a person: the same human on a phone and a laptop is two device ids, and a cleared browser is a new one. Newest event first, at most 500 (`limit`, default 100). Refreshed about every 15 seconds, like Live View.\n\n#### Signature\n\n```http\nGET /analytics/live-view/{deviceId}/journey (deviceId: string, limit?: integer) -> The journey\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORGID_REQUIRED | orgId is required | The `orgid` header is missing. | Send the `orgid` header. |\n| `500` | ANALYTICS_FAILED | Failed to get device journey | The figures could not be computed. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics/live-view`"}},"/analytics/website":{"get":{"operationId":"AnalyticsController_getWebsiteAnalytics","summary":"Get website analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Website analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get website analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get website analytics","path":"/analytics/website","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Traffic and engagement across the org's sites over a date range.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/website (startDate?: string, endDate?: string) -> Website analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get website analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/blog":{"get":{"operationId":"AnalyticsController_getBlogAnalytics","summary":"Get blog analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Blog analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get blog analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get blog analytics","path":"/analytics/blog","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Post readership and engagement. A visit counts as a view of a post when the last segment of its URL is one of the org’s post slugs (the post’s `name` when it has no slug) — whatever prefix the site gives posts (`/blog/`, `/news/`, …). `topPosts` are the ten most-viewed posts in the range; `overview.totalViews` counts every post view in the range. Category and author figures come from the posts themselves.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/blog (startDate?: string, endDate?: string) -> Blog analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get blog analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/workflow":{"get":{"operationId":"AnalyticsController_getWorkflowAnalytics","summary":"Get workflow analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get workflow analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get workflow analytics","path":"/analytics/workflow","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Pipeline throughput and stage timings from the workflow engine.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/workflow (startDate?: string, endDate?: string) -> Workflow analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get workflow analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/storefront":{"get":{"operationId":"AnalyticsController_getStorefrontAnalytics","summary":"Get storefront analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Storefront analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get storefront analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get storefront analytics","path":"/analytics/storefront","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Orders, revenue and conversion for the storefront.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/storefront (startDate?: string, endDate?: string) -> Storefront analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get storefront analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/storefront/orders":{"post":{"operationId":"AnalyticsController_getOrderDashboard","summary":"Get the order dashboard","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Order analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"orgId is required — The `orgid` header is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"orgId is required","path":"/analytics/storefront/orders","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get order dashboard analytics — The figures could not be computed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get order dashboard analytics","path":"/analytics/storefront/orders","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Order analytics with a richer selector than the query-string dashboards: `period` picks a named window (`today`, `week`, `month`, `year`), or give explicit dates. `recentLimit` caps how many recent orders come back alongside the aggregates.\n\nA POST because of the body, not because it changes anything — it is a read.\n\n#### Signature\n\n```http\nPOST /analytics/storefront/orders (body) -> Order analytics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Read-only despite being a POST.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORGID_REQUIRED | orgId is required | The `orgid` header is missing. | Send the `orgid` header. |\n| `500` | ANALYTICS_FAILED | Failed to get order dashboard analytics | The figures could not be computed. | Retry; escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics/storefront`","requestBody":{"description":"The window.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","enum":["today","week","month","year"],"example":"month"},"startDate":{"type":"string","description":"Overrides `period`.","example":"2026-08-01"},"endDate":{"type":"string","example":"2026-08-31"},"recentLimit":{"type":"integer","description":"How many recent orders to include.","example":10}}},"examples":{"namedPeriod":{"summary":"A named period","value":{"period":"month","recentLimit":10}},"explicit":{"summary":"An explicit range","value":{"startDate":"2026-08-01","endDate":"2026-08-31"}}}}}}}},"/analytics/tickets":{"get":{"operationId":"AnalyticsController_getTicketAnalytics","summary":"Get ticket analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get ticket analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get ticket analytics","path":"/analytics/tickets","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Support ticket volume, resolution time and backlog.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/tickets (startDate?: string, endDate?: string) -> Ticket analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get ticket analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/attribution":{"get":{"operationId":"AnalyticsController_getAttributionAnalytics","summary":"Get revenue attribution","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"{ period, totals, bySource, byMedium, byCampaign }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"period":{"startDate":"2026-08-01T00:00:00.000Z","endDate":"2026-08-31T00:00:00.000Z"},"totals":{"orders":120,"revenue":9400,"attributedOrders":84,"attributedRevenue":7010,"coverage":70,"unattributedRevenue":2390},"bySource":[{"name":"facebook","orders":40,"revenue":3200,"customers":36,"sessions":900,"revenuePerSession":3.56}],"byMedium":[{"name":"cpc","orders":50,"revenue":4100,"customers":44}],"byCampaign":[{"name":"fall-sale","orders":30,"revenue":2500,"customers":28,"sessions":610,"revenuePerSession":4.1}]}}}},"400":{"description":"Organization ID is required — The `orgid` header is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Organization ID is required","path":"/analytics/attribution","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"],"description":"Revenue by campaign source, medium and campaign, read from what the campaign page handed over at checkout (`sf_order.data.attribution`) — not a join back over visits, which are purged after six months. Cancelled, refunded and draft orders are not counted.\n\n`bySource` and `byCampaign` also carry `sessions` from web visits (their `utmSource` / `utmCampaign`), so a source with traffic and no revenue still shows, with `revenuePerSession`. Rows sort by revenue, then sessions. `totals.coverage` is the percentage of orders that carried a source — a low number means campaign pages are not handing their source over at checkout.\n\nWithout dates the window is the last 30 days. Cached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/attribution (startDate?: string, endDate?: string) -> { period, totals, bySource, byMedium, byCampaign }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORGID_REQUIRED | Organization ID is required | The `orgid` header is missing. | Send the `orgid` header. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /analytics/storefront`"}},"/analytics/leads":{"get":{"operationId":"AnalyticsController_getLeadsAnalytics","summary":"Get leads analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Leads analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get leads analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get leads analytics","path":"/analytics/leads","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Lead volume, source and conversion.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/leads (startDate?: string, endDate?: string) -> Leads analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get leads analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/automation":{"get":{"operationId":"AnalyticsController_getAutomationAnalytics","summary":"Get automation analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Automation analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get automation analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get automation analytics","path":"/analytics/automation","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Automation run counts, successes and failures.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/automation (startDate?: string, endDate?: string) -> Automation analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get automation analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/users":{"get":{"operationId":"AnalyticsController_getUserAccountAnalytics","summary":"Get user account analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"User account analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get user account analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get user account analytics","path":"/analytics/users","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Account signups, activity and retention.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/users (startDate?: string, endDate?: string) -> User account analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get user account analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/email":{"get":{"operationId":"AnalyticsController_getEmailAnalytics","summary":"Get email analytics","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"],"type":"string"}},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}}],"responses":{"200":{"description":"Email analytics with the previous-window comparison","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"overview":{"type":"object","additionalProperties":true},"period":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"}}},"comparison":{"type":"object","properties":{"startDate":{"type":"string"},"endDate":{"type":"string"},"overview":{"type":"object","additionalProperties":{"type":"object","properties":{"previous":{"type":"number"},"changePercent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","flat"]},"sentiment":{"type":"string","enum":["good","bad","neutral"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to get email analytics — The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to get email analytics","path":"/analytics/email","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Email send and engagement figures.\n\nEvery dashboard is computed twice — for the requested window and for the window of the same length just before it — and returned with `period` (the window used) and `comparison: { startDate, endDate, overview }`, where each numeric `overview` figure gets `{ previous, changePercent, direction: up|down|flat, sentiment: good|bad|neutral }`. `changePercent` is `null` when the previous value was 0. Without dates the window is the last 30 days.\n\nCached for about five minutes: a reload inside that window returns the same figures.\n\n#### Signature\n\n```http\nGET /analytics/email (startDate?: string, endDate?: string) -> Email analytics with the previous-window comparison\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to get email analytics | The figures could not be computed — or the `orgid` header is missing (the handler reports that as this 500, not a 400). | Check the `orgid` header; otherwise retry and escalate if it persists. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/analytics/export":{"post":{"operationId":"AnalyticsController_exportAnalytics","summary":"Export analytics data","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"startDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"description":"ISO date.","example":"2026-08-31"},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["website","blog","workflow","storefront","tickets","leads","automation","users","email"]},"description":"Dashboard. Omit for all but email.","example":"storefront"},{"name":"metrics","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"demo","required":false,"in":"query","description":"Use demo data instead of real data","schema":{"type":"boolean"}},{"name":"siteName","required":false,"in":"query","description":"Website and Blog dashboards: the site to report on (default: the org default site)","schema":{"type":"string"}},{"name":"pipelineId","required":false,"in":"query","description":"Leads dashboard: the pipeline to draw the stage funnel for (default: the pipeline with the most leads)","schema":{"type":"string"}},{"name":"onlyPipeline","required":false,"in":"query","description":"With pipelineId: every number counts only that pipeline's leads (a blueprint's pipeline), not just the funnel","schema":{"type":"string"}},{"name":"tz","required":false,"in":"query","description":"Leads dashboard: the viewer's IANA time zone; days are that zone's calendar days (default UTC)","schema":{"type":"string"}},{"name":"fresh","required":false,"in":"query","description":"'1' = Refresh: compute the figures now instead of serving the up-to-5-minute cache","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["csv","json","pdf"],"default":"csv"},"description":"Echoed back; does not change the payload yet."}],"responses":{"201":{"description":"{ format, data, exportedAt }","content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string"},"data":{"type":"object","additionalProperties":true},"exportedAt":{"type":"string"}}},"example":{"format":"csv","data":{"overview":{}},"exportedAt":"2026-09-29T14:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to export analytics — The figures could not be computed — or the `orgid` header is missing (reported as this 500).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to export analytics","path":"/analytics/export","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Analytics"],"description":"Returns the same figures as `GET /analytics` for the dashboard and date range, wrapped as `{ format, data, exportedAt }`. The selector travels in the **query string**, not a body. No file is produced yet: `format` is echoed back and `data` is always JSON, whatever format is asked for.\n\n#### Signature\n\n```http\nPOST /analytics/export (type?: string, startDate?: string, endDate?: string, format?: string) -> { format, data, exportedAt }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | ANALYTICS_FAILED | Failed to export analytics | The figures could not be computed — or the `orgid` header is missing (reported as this 500). | Check the `orgid` header; otherwise retry. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /analytics`"}},"/stats/{datatype}/{id}/like":{"post":{"operationId":"StatsController_like","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Like a record","description":"Records that the caller likes a record.\n\nA per-caller toggle: send `action: \"remove\"` to undo it. Repeating `add` does not double-count — the signal is recorded once per caller.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/like (datatype: string, id: string, body) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/{datatype}/{id}`","requestBody":{"description":"Whether to add or remove the signal. Defaults to `add`.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["add","remove"],"description":"Defaults to `add`.","example":"add"}}},"examples":{"add":{"summary":"Add the signal","value":{"action":"add"}},"remove":{"summary":"Remove it","value":{"action":"remove"}}}}}}}},"/stats/{datatype}/{id}/dislike":{"post":{"operationId":"StatsController_dislike","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Dislike a record","description":"Records that the caller dislikes a record. Separate from removing a like — a dislike is its own signal.\n\nA per-caller toggle: send `action: \"remove\"` to undo it. Repeating `add` does not double-count — the signal is recorded once per caller.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/dislike (datatype: string, id: string, body) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/{datatype}/{id}`","requestBody":{"description":"Whether to add or remove the signal. Defaults to `add`.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["add","remove"],"description":"Defaults to `add`.","example":"add"}}},"examples":{"add":{"summary":"Add the signal","value":{"action":"add"}},"remove":{"summary":"Remove it","value":{"action":"remove"}}}}}}}},"/stats/{datatype}/{id}/bookmark":{"post":{"operationId":"StatsController_bookmark","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Bookmark a record","description":"Saves a record to the caller's bookmarks.\n\nA per-caller toggle: send `action: \"remove\"` to undo it. Repeating `add` does not double-count — the signal is recorded once per caller.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/bookmark (datatype: string, id: string, body) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/{datatype}/{id}`","requestBody":{"description":"Whether to add or remove the signal. Defaults to `add`.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["add","remove"],"description":"Defaults to `add`.","example":"add"}}},"examples":{"add":{"summary":"Add the signal","value":{"action":"add"}},"remove":{"summary":"Remove it","value":{"action":"remove"}}}}}}}},"/stats/{datatype}/{id}/follow":{"post":{"operationId":"StatsController_follow","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Follow a record","description":"Follows a record, so the caller is tracked as interested in it.\n\nA per-caller toggle: send `action: \"remove\"` to undo it. Repeating `add` does not double-count — the signal is recorded once per caller.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/follow (datatype: string, id: string, body) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/{datatype}/{id}`","requestBody":{"description":"Whether to add or remove the signal. Defaults to `add`.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["add","remove"],"description":"Defaults to `add`.","example":"add"}}},"examples":{"add":{"summary":"Add the signal","value":{"action":"add"}},"remove":{"summary":"Remove it","value":{"action":"remove"}}}}}}}},"/stats/{datatype}/{id}/favorite":{"post":{"operationId":"StatsController_favorite","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Favorite a record","description":"Marks a record as one of the caller's favourites.\n\nA per-caller toggle: send `action: \"remove\"` to undo it. Repeating `add` does not double-count — the signal is recorded once per caller.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/favorite (datatype: string, id: string, body) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/{datatype}/{id}`","requestBody":{"description":"Whether to add or remove the signal. Defaults to `add`.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["add","remove"],"description":"Defaults to `add`.","example":"add"}}},"examples":{"add":{"summary":"Add the signal","value":{"action":"add"}},"remove":{"summary":"Remove it","value":{"action":"remove"}}}}}}}},"/stats/{datatype}/{id}/rating":{"post":{"operationId":"StatsController_rating","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Rate a record","description":"Records the caller's numeric rating. `action: \"update\"` changes an existing rating rather than adding a second — send it when the caller has already rated, or the aggregate counts them twice.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/rating (datatype: string, id: string, body) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Use `update` to change an existing rating.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/{datatype}/{id}`","requestBody":{"description":"The rating.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"type":"number","description":"The rating.","example":4},"action":{"type":"string","enum":["add","update"],"description":"Defaults to `add`.","example":"add"}}},"example":{"value":4}}}}}},"/stats/{datatype}/{id}/reaction":{"post":{"operationId":"StatsController_reaction","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"React to a record","description":"Records a named reaction — the open-ended signal, where like and favourite are fixed ones. The reaction name is whatever the caller sends.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/reaction (datatype: string, id: string, body) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /stats/{datatype}/{id}/like`","requestBody":{"description":"The reaction.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","description":"The reaction name.","example":"celebrate"},"action":{"type":"string","enum":["add","remove"],"example":"add"}}},"example":{"value":"celebrate"}}}}}},"/stats/{datatype}/{id}/view":{"post":{"operationId":"StatsController_view","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Record a view","description":"Increments the record's view count. A **counter, not a toggle** — every call adds one, so a client that fires it on each render inflates the figure.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/view (datatype: string, id: string) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Increments on every call.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /stats/{datatype}/{id}/share`"}},"/stats/{datatype}/{id}/share":{"post":{"operationId":"StatsController_share","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"201":{"description":"The updated stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Record a share","description":"Increments the record's share count. Also a counter — it records that a share was initiated, not that anyone received it.\n\n#### Signature\n\n```http\nPOST /stats/{datatype}/{id}/share (datatype: string, id: string) -> The updated stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Increments on every call.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /stats/{datatype}/{id}/view`"}},"/stats/{datatype}/{id}":{"get":{"operationId":"StatsController_get","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"200":{"description":"The stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Get a record's stats","description":"Aggregate signals for one record — counts, average rating, and the caller's own state where relevant.\n\n#### Signature\n\n```http\nGET /stats/{datatype}/{id} (datatype: string, id: string) -> The stats\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/by-resource/{datatype}/{id}`"}},"/stats/by-resource/{datatype}/{id}":{"get":{"operationId":"StatsController_byResource","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType of the record.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id.","example":"PRD-4821"}],"responses":{"200":{"description":"Signals on the record","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Get stats by resource","description":"The signals recorded against one record, listed rather than aggregated — who liked it, who bookmarked it.\n\n#### Signature\n\n```http\nGET /stats/by-resource/{datatype}/{id} (datatype: string, id: string) -> Signals on the record\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/by-customer/{datatype}/{id}`"}},"/stats/by-customer/{datatype}/{id}":{"get":{"operationId":"StatsController_byCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"datatype","required":true,"in":"path","schema":{"type":"string"},"description":"DataType. Optional.","example":"product"},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Record id. Optional.","example":"PRD-4821"}],"responses":{"200":{"description":"The caller's signals","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Stats"],"summary":"Get stats by customer","description":"The signals the **calling customer** has recorded, optionally narrowed to a datatype or a single record. Both path segments are optional — omit them for everything the caller has liked, bookmarked or followed.\n\n#### Signature\n\n```http\nGET /stats/by-customer/{datatype}/{id} (datatype: string, id: string) -> The caller's signals\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /stats/by-resource/{datatype}/{id}`"}},"/studio-overview/{section}":{"get":{"operationId":"StudioOverviewController_getSection","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"section","required":true,"in":"path","schema":{"type":"string","enum":["home","account","config","database","crm","store","finance","logistics","events","community","dam","build-studio","ai-automation"]},"description":"Which dashboard.","example":"home"},{"name":"site","in":"query","required":false,"description":"Narrows `home` and `build-studio` to one site (site name). Ignored by other sections.","schema":{"type":"string"},"example":"acme-shop"}],"responses":{"200":{"description":"{ section, generatedAt, ...figures }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"section":"home","generatedAt":"2026-09-29T14:00:00.000Z","customers":1240,"sites":2,"activityToday":37,"recentActivity":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Unknown overview section \"reports\" — `section` is not one of the listed dashboards.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Unknown overview section \"reports\"","path":"/studio-overview/{section}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"],"summary":"Get a Studio section overview","description":"The finished figures one Studio dashboard renders — counts, recent records and section-specific tiles — computed on the server so the screen only draws them. Every response carries `section` and `generatedAt` beside the section's own fields. Not cached.\n\n#### Signature\n\n```http\nGET /studio-overview/{section} (section: string, site?: string) -> { section, generatedAt, ...figures }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | UNKNOWN_SECTION | Unknown overview section \"reports\" | `section` is not one of the listed dashboards. | Use one of the enum values. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/analytics/activity-feed":{"get":{"operationId":"ActivityFeedController_activityFeed","summary":"Get the activity feed","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"q","in":"query","required":false,"description":"Words in what happened, the name on it, who (email or name), the action or the record type.","schema":{"type":"string"},"example":"invoice"},{"name":"type","in":"query","required":false,"description":"Actions (ActivityTypes keys), comma separated.","schema":{"type":"string"},"example":"login,update"},{"name":"datatype","in":"query","required":false,"description":"Record types (owner.datatype), comma separated.","schema":{"type":"string"},"example":"sf_invoice"},{"name":"status","in":"query","required":false,"description":"Statuses, comma separated.","schema":{"type":"string"},"example":"failed"},{"name":"author","in":"query","required":false,"description":"Who (author as stored: email, id or system name), comma separated.","schema":{"type":"string"},"example":"jo@example.com"},{"name":"authorQ","in":"query","required":false,"description":"Searches the Who list by name or email.","schema":{"type":"string"},"example":"jo"},{"name":"owner","in":"query","required":false,"description":"Only activity about this record (owner.id).","schema":{"type":"string"},"example":"66f0c2a1b2c3d4e5f6a7b8c9"},{"name":"range","in":"query","required":false,"description":"A date preset; `custom` (or none) uses `from` / `to`.","schema":{"type":"string","enum":["today","7d","30d","custom"]},"example":"7d"},{"name":"from","in":"query","required":false,"description":"From: an ISO date-time, or a calendar day (YYYY-MM-DD) read in `tz` from its first moment.","schema":{"type":"string"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"To, inclusive: an ISO date-time, or a calendar day (YYYY-MM-DD) read in `tz` to its last moment.","schema":{"type":"string"},"example":"2026-10-17"},{"name":"errors","in":"query","required":false,"description":"Only failed / error statuses.","schema":{"type":"boolean"},"example":true},{"name":"tz","in":"query","required":false,"description":"IANA time zone for today / last 7 days; default UTC.","schema":{"type":"string"},"example":"America/New_York"},{"name":"p","in":"query","required":false,"description":"Page, default 1.","schema":{"type":"integer"},"example":1},{"name":"ps","in":"query","required":false,"description":"Page size, default 50, at most 200.","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"{ data, total, page, pageSize, totals, facets, authorLimit, authorMore, owner, window }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"data":[{"sk":"66f0c2a1b2c3d4e5f6a7b8c9","author":"jo@example.com","owner":{"datatype":"sf_invoice","id":"66f0c2a1b2c3d4e5f6a7b8c0"},"createdate":"2026-10-17T14:00:00.000Z","data":{"type":"update","status":"success","comment":"Invoice updated"},"actionLabel":"Updated","recordLabel":"Invoice","recordTitle":"INV-1042","who":"Jo Park","statusLabel":"Succeeded","tone":"good"}],"total":8466,"totals":{"all":8466,"today":37,"last7d":412,"errors":9},"facets":{"type":[{"value":"update","label":"Updated","count":3100}],"datatype":[{"value":"sf_invoice","label":"Invoice","count":900}],"status":[{"value":"failed","label":"Failed","count":9}],"author":[{"value":"jo@example.com","label":"Jo Park","count":1200}]},"authorMore":false,"owner":null}}}},"400":{"description":"orgId is required — The `orgid` header is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"orgId is required","path":"/analytics/activity-feed","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"This needs someone signed in to the business — A customer or the site's app identity called it.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This needs someone signed in to the business","path":"/analytics/activity-feed","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"],"description":"One page of the org's activity log (`activity` records, newest first) under the filters asked for, with the figures, every filter's options and counts, and each row's plain-words labels — the screen only renders them.\n\nFacets are counted over every current filter except their own dimension. `facets.type` lists every action the platform records (zero counts included), `facets.datatype` and `facets.status` every value this org has any activity for, `facets.author` the 50 busiest people under the filters (`authorMore: true` when there are more — search them with `authorQ`). The value `_none` stands for \"not recorded\". `totals` (`all`, `today`, `last7d`, `errors`) are over the current filters; `today` and `last7d` start at midnight in `tz`. Rows carry `actionLabel`, `recordLabel`, `recordTitle`, `who`, `statusLabel` and `tone` (good | bad | neutral). Staff only. Not cached (the facets' full value lists are, for two minutes).\n\n#### Signature\n\n```http\nGET /analytics/activity-feed (q?: string, type?: string, datatype?: string, status?: string, author?: string, authorQ?: string, owner?: string, range?: string, from?: string, to?: string, errors?: boolean, tz?: string, p?: integer, ps?: integer) -> { data, total, page, pageSize, totals, facets, authorLimit, authorMore, owner, window }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ORGID_REQUIRED | orgId is required | The `orgid` header is missing. | Send the `orgid` header. |\n| `403` | STAFF_ONLY | This needs someone signed in to the business | A customer or the site's app identity called it. | Call as a signed-in staff member. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `GET /studio-overview/{section}`"}},"/analytics/aggregates":{"get":{"operationId":"AggregatesController_overview","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/analytics/aggregates/{query}/runs":{"get":{"operationId":"AggregatesController_runs","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"query","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/analytics/aggregates/{query}/answer":{"get":{"operationId":"AggregatesController_answer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"query","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":true,"in":"query","schema":{"type":"string"}},{"name":"to","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/analytics/aggregates/check":{"post":{"operationId":"AggregatesController_check","parameters":[],"responses":{"201":{"description":""}}}},"/analytics/aggregates/{query}":{"get":{"operationId":"AggregatesController_read","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"query","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":true,"in":"query","schema":{"type":"string"}},{"name":"to","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/analytics/aggregates/skip":{"post":{"operationId":"AggregatesController_skip","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/analytics/aggregates/skip/{sk}":{"delete":{"operationId":"AggregatesController_unskip","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"sk","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}},"/k8/delete-service/{namespace}/{kind}/{name}":{"delete":{"operationId":"K8sManagementController_deleteService","summary":"Delete a Kubernetes resource","description":"Deletes a resource from the cluster. **Takes the workload down immediately** and cannot be undone — the manifest has to be re-applied to bring it back.\n\n#### Signature\n\n```http\nDELETE /k8/delete-service/{namespace}/{kind}/{name} (namespace: string, kind: string, name: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Immediately destructive.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /k8/apply-service`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"kind","required":true,"in":"path","description":"Resource kind.","schema":{"type":"string"},"example":"Deployment"},{"name":"namespace","required":true,"in":"path","description":"Namespace.","schema":{"type":"string"},"example":"org-4821"},{"name":"name","required":true,"in":"path","description":"Resource name.","schema":{"type":"string"},"example":"acme-shop"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Service deletion accepted"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/namespaces/{name}":{"delete":{"operationId":"K8sManagementController_deleteNamespace","summary":"Delete a namespace","description":"**Deletes an entire Kubernetes namespace and everything in it** — every deployment, service, secret and volume claim it holds.\n\nThis is the most destructive endpoint in the module. Namespaces typically correspond to a customer's workloads, so deleting one takes that customer offline entirely. There is no confirmation and no undo.\n\n#### Signature\n\n```http\nDELETE /k8/namespaces/{name} (name: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Destroys every resource in the namespace. No undo.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /k8/cleanup-resources`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Namespace to delete.","schema":{"type":"string"},"example":"org-4821"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Namespace deletion accepted"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/namespaces/{namespaceName}/pods":{"get":{"operationId":"K8sManagementController_getPods","summary":"List pods in a namespace","description":"Pods running in a namespace, with their status — the first look when a site is not responding.\n\n#### Signature\n\n```http\nGET /k8/namespaces/{namespaceName}/pods (namespaceName: string) -> Pods\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /k8/check-status/{namespace}/{kind}/{resource}`","parameters":[{"name":"namespaceName","required":true,"in":"path","description":"Namespace.","schema":{"type":"string"},"example":"org-4821"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Pods","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/namespaces/{namespaceName}":{"get":{"operationId":"K8sManagementController_getNamespace","summary":"Get a namespace","description":"One namespace and its metadata.\n\n#### Signature\n\n```http\nGET /k8/namespaces/{namespaceName} (namespaceName: string) -> The namespace\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /k8/namespaces/{namespaceName}/pods`","parameters":[{"name":"namespaceName","required":true,"in":"path","description":"Namespace.","schema":{"type":"string"},"example":"org-4821"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The namespace","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/check-status/{namespace}/{kind}/{resource}":{"get":{"operationId":"K8sManagementController_checkStatus","summary":"Check a resource's status","description":"The status of one Kubernetes resource, by namespace, kind and name.\n\n#### Signature\n\n```http\nGET /k8/check-status/{namespace}/{kind}/{resource} (namespace: string, kind: string, resource: string) -> The status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /k8/apply-service`","parameters":[{"name":"namespace","required":true,"in":"path","description":"Namespace.","schema":{"type":"string"},"example":"org-4821"},{"name":"kind","required":true,"in":"path","description":"Resource kind.","schema":{"type":"string"},"example":"Deployment"},{"name":"resource","required":true,"in":"path","description":"Resource name.","schema":{"type":"string"},"example":"acme-shop"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/namespaces":{"get":{"operationId":"K8sManagementController_listNamespaces","summary":"List namespaces","description":"Kubernetes namespaces on the cluster.\n\n#### Signature\n\n```http\nGET /k8/namespaces () -> Namespaces\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /k8/namespaces/{namespaceName}`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Namespaces","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/apply-service":{"post":{"operationId":"K8sManagementController_applyService","summary":"Apply a Kubernetes service","description":"Applies a service manifest to the cluster. Applying is declarative: it creates or replaces, so a partial manifest can remove fields that were previously set.\n\n#### Signature\n\n```http\nPOST /k8/apply-service (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Declarative apply — omitted fields are dropped.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /k8/delete-service/{namespace}/{kind}/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The manifest.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"namespace":"org-4821","kind":"Deployment","name":"acme-shop","spec":{}}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/cleanup-resources":{"post":{"operationId":"K8sManagementController_cleanupSiteResources","summary":"Clean up site resources","description":"Removes the cluster resources belonging to a site. Destructive by design — it exists to reclaim what a deleted site left behind, so confirm the site really is gone first.\n\n#### Signature\n\n```http\nPOST /k8/cleanup-resources (body) -> What was removed\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Deletes cluster resources.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /k8/delete-service/{namespace}/{kind}/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Which site.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","namespace":"org-4821"}}}},"responses":{"200":{"description":"Site resources cleanup initiated","content":{"application/json":{"schema":{"type":"object","properties":{"siteName":{"type":"string","description":"Site name"},"siteOrgId":{"type":"string","description":"Site organization ID"},"k8sCleanup":{"type":"object","description":"K8s resource cleanup results"},"nginxCleanup":{"type":"object","description":"Nginx configuration cleanup results"},"message":{"type":"string","description":"Cleanup status message"}}}}}},"201":{"description":"What was removed","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/scale-up":{"post":{"operationId":"K8sManagementController_scaleUp","summary":"Scale up a deployment","description":"Raises a deployment's replica count — bringing a scaled-to-zero workload back, or adding capacity. Costs cluster resources.\n\n#### Signature\n\n```http\nPOST /k8/scale-up (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /k8/scale-down`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to scale.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"namespace":"org-4821","name":"acme-shop","replicas":2}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/k8/scale-down":{"post":{"operationId":"K8sManagementController_scaleToZero","summary":"Scale a deployment to zero","description":"Scales a deployment down to zero replicas. The workload stops serving entirely — this is how an idle site is parked, and it is indistinguishable from an outage to anyone visiting it.\n\n#### Signature\n\n```http\nPOST /k8/scale-down (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Takes the workload offline.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /k8/scale-up`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to scale down.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"namespace":"org-4821","name":"acme-shop"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Kubernetes"]}},"/org-management/check-org-name/{orgName}":{"get":{"operationId":"OrgManagementController_checkOrgNameAvailability","summary":"Check organization name availability","description":"Whether a name is free to register. **Public**, because it runs during signup before an account exists — which also means it lets anyone enumerate which org names are taken.\n\n#### Signature\n\n```http\nGET /org-management/check-org-name/{orgName} (orgName: string) -> Availability\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated; discloses whether a name is taken.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /org-management/org-register`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orgName","required":true,"in":"path","schema":{"type":"string"},"description":"The name to check.","example":"acme"}],"requestBody":{"required":true,"description":"Organization name to check","content":{"application/json":{"schema":{"type":"object","properties":{"orgName":{"type":"string","description":"Organization name to check"}},"required":["orgName"]}}}},"responses":{"200":{"description":"Availability","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"available":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/profile/{orgId}":{"get":{"operationId":"OrgManagementController_getProfile","summary":"Get an organization profile","description":"The full profile — company, customer and address information. `orgId` is optional: omit it for the calling org, supply it to read another org (which the caller must be entitled to do).\n\n#### Signature\n\n```http\nGET /org-management/profile/{orgId} (orgId: string) -> The profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/profile/update`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orgId","required":true,"in":"path","schema":{"type":"string"},"description":"Org to read. Defaults to the caller's own.","example":"org_4821"}],"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/profile/{orgId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/profile/update":{"post":{"operationId":"OrgManagementController_updateCompanyProfile","summary":"Update the company profile","description":"Updates company profile information on the root org record.\n\n#### Signature\n\n```http\nPOST /org-management/profile/update (body) -> The updated profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /org-management/profile/customer`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"companyName":"Acme Ltd","phone":"+15551234567"}}}},"responses":{"201":{"description":"The updated profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/company/meta":{"post":{"operationId":"OrgManagementController_updateCompanyMeta","summary":"Update company metadata","description":"Merges a namespaced blob into the **caller's own** org at `company.data.meta` — for example `{ namespace: \"onboarding\", value: { setupCompletedAt } }`.\n\nDeliberately narrow: it writes only `data.meta.<namespace>.*`. Plan, balance and status cannot be reached through it, which is what makes it safe to expose to an app that needs to remember its own state.\n\n#### Signature\n\n```http\nPOST /org-management/company/meta (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Cannot reach plan, balance or status.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NAMESPACE_REQUIRED | A valid meta namespace is required | `namespace` is missing or invalid. | Supply a namespace. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/profile/{orgId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The namespace and its value.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["namespace","value"],"properties":{"namespace":{"type":"string","example":"onboarding"},"value":{"type":"object","description":"Must be an object.","additionalProperties":true,"example":{"setupCompletedAt":"2026-08-30T10:00:00.000Z"}}}},"example":{"namespace":"onboarding","value":{"setupCompletedAt":"2026-08-30T10:00:00.000Z"}}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid meta namespace is required — `namespace` is missing or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid meta namespace is required","path":"/org-management/company/meta","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/profile/customer":{"put":{"operationId":"OrgManagementController_updateCustomerProfile","summary":"Update the customer profile","description":"Updates the customer-side profile on the root org record.\n\n#### Signature\n\n```http\nPUT /org-management/profile/customer (body) -> The updated profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/profile/update`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"firstName":"Ada","lastName":"Lovelace"}}}},"responses":{"200":{"description":"The updated profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/profile/addresses":{"get":{"operationId":"OrgManagementController_getAddresses","summary":"Get addresses","description":"The current user's addresses.\n\n#### Signature\n\n```http\nGET /org-management/profile/addresses () -> Addresses\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/profile/addresses`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Addresses","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]},"post":{"operationId":"OrgManagementController_addAddress","summary":"Add an address","description":"Adds an address for the current user.\n\n#### Signature\n\n```http\nPOST /org-management/profile/addresses (body) -> The address\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/profile/addresses`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The address.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"line1":"1 Market St","city":"San Francisco","state":"CA","postalCode":"94105","country":"US"}}}},"responses":{"201":{"description":"The address","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/billing/balance":{"get":{"operationId":"OrgManagementController_getBalance","summary":"Get the credit balance","description":"Current credit balance and spending. `customerOrgId` reads another org's balance, for an operator managing a customer.\n\n#### Signature\n\n```http\nGET /org-management/billing/balance (customerOrgId?: string) -> Balance and spending\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/billing/transactions`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"customerOrgId","required":false,"in":"query","description":"Read another org's balance.","schema":{"type":"string"},"example":"org_4821"}],"responses":{"200":{"description":"Balance and spending","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/billing/buy-credits":{"post":{"operationId":"OrgManagementController_buyCredits","summary":"Buy credits","description":"Starts a credit purchase through the payment gateway. **Charges a real card.** Marked public because it is also reachable from a payment-return context; supply the org explicitly when there is no session.\n\n#### Signature\n\n```http\nPOST /org-management/billing/buy-credits (body) -> The payment setup\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Charges a card.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_AMOUNT | Invalid amount | The amount is missing or not positive. | Send a positive amount. |\n| `402` | PAYMENT_FAILED | Payment failed | The card was declined or the charge could not be taken. | Try another payment method. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /org-management/billing/complete-payment`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The purchase.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","example":5000},"quantity":{"type":"integer","example":1},"customerOrgId":{"type":"string","example":"org_4821"}}},"example":{"amount":5000}}}},"responses":{"201":{"description":"The payment setup","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid amount — The amount is missing or not positive.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid amount","path":"/org-management/billing/buy-credits","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"Payment failed — The card was declined or the charge could not be taken.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"Payment failed","path":"/org-management/billing/buy-credits","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/billing/complete-payment":{"post":{"operationId":"OrgManagementController_completePayment","summary":"Complete a credit payment","description":"Finalises a pending credit purchase after Stripe validation, crediting the balance. The session id is single-use — replaying one is refused rather than crediting twice.\n\n#### Signature\n\n```http\nPOST /org-management/billing/complete-payment (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Single-use per session.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PAYMENT_INTENT_REQUIRED | Payment intent ID is required | No intent id was supplied. | Pass the intent id from the client-side confirmation. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /org-management/billing/buy-credits`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The payment reference.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentIntentId":{"type":"string","example":"pi_3Abc123"},"sessionId":{"type":"string","example":"cs_test_a1b2c3"}}},"example":{"paymentIntentId":"pi_3Abc123"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Payment intent ID is required — No intent id was supplied.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Payment intent ID is required","path":"/org-management/billing/complete-payment","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/billing/transactions":{"get":{"operationId":"OrgManagementController_getTransactionHistory","summary":"Get transaction history","description":"The org's billing transactions.\n\n#### Signature\n\n```http\nGET /org-management/billing/transactions () -> Transactions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/billing/balance`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"customerOrgId","required":false,"in":"query","description":"Read another org (root only). Defaults to the caller.","schema":{}},{"name":"endDate","required":false,"in":"query","description":"End date filter","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date filter","schema":{"type":"string"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"type":"number"}}],"responses":{"200":{"description":"Transactions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/billing/auto-reload":{"get":{"operationId":"OrgManagementController_getAutoReload","summary":"Credit auto reload settings","description":"Whether the credit balance is topped up automatically, below what balance, by how much, and whether a card is saved to charge.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Organization Management"]},"post":{"operationId":"OrgManagementController_saveAutoReload","summary":"Turn credit auto reload on or off","description":"Body `{ enabled, threshold, amount }`. Turning it on needs the card saved with the plan (409 NO_SAVED_CARD otherwise).","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Organization Management"]}},"/org-management/billing/transactions/backfill-org-links":{"post":{"operationId":"OrgManagementController_backfillTransactionOrgLinks","summary":"Backfill transaction org links","description":"One-time repair: links root-owned credit purchases that predate the `data.customerOrgId` field back to the org they were paid for, using their Stripe PaymentIntent.\n\nIdempotent, so a re-run is safe, but it rewrites historical ledger rows — run it deliberately and bound it with `limit` on a first pass.\n\n#### Signature\n\n```http\nPOST /org-management/billing/transactions/backfill-org-links (limit?: integer) -> What was linked\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Notes\n\n- Rewrites historical transactions. Idempotent.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/billing/transactions`","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"Cap how many rows are processed.","example":100},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"What was linked","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/billing/subscriptions/migrate-stripe-billing":{"post":{"operationId":"OrgManagementController_migrateStripeBillingSubscriptions","summary":"Move plan subscriptions off Stripe Billing onto our own renewals","description":"One-time maintenance: each plan subscription still billed by a Stripe Billing subscription is set to cancel at the end of its paid period; its card becomes the saved card and our renewal date is set to that period end, so the plan-renewal job charges the next period. Body `{ dryRun?: boolean (default true), limit?: number }`. Idempotent.","parameters":[],"responses":{"200":{"description":"Counts and one row per subscription"}},"tags":["Organization Management"]}},"/org-management/billing/gift-credits":{"post":{"operationId":"OrgManagementController_giftCredits","summary":"Gift credits (admin)","description":"Grants credits to an org without payment. Admin-only, and it creates spendable balance out of nothing — the transaction record is the only trail, so record why.\n\n#### Signature\n\n```http\nPOST /org-management/billing/gift-credits (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- Creates balance with no payment behind it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_AMOUNT | Invalid amount | The amount is not positive. | Send a positive amount. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/billing/add-credit`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The gift.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerOrgId":{"type":"string","example":"org_4821"},"amount":{"type":"number","example":5000},"reason":{"type":"string","example":"Service credit for the March outage"}}},"example":{"customerOrgId":"org_4821","amount":5000,"reason":"Service credit for the March outage"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid amount — The amount is not positive.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid amount","path":"/org-management/billing/gift-credits","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/billing/add-credit":{"post":{"operationId":"OrgManagementController_addCredit","summary":"Add credit to an organization","description":"Adds credit directly to an org and writes the transaction record. An email is required so the record says **who** the credit was added for — a credit with no attributable person cannot be audited later.\n\n#### Signature\n\n```http\nPOST /org-management/billing/add-credit (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | EMAIL_REQUIRED | An email is required to record who the credit was added for | `email` is missing. | Supply the recipient email. |\n| `422` | INVALID_CUSTOMER_ORG | Invalid customerOrgId <id> | The target org does not exist. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/billing/gift-credits`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"An email is required to record who the credit was added for — `email` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"An email is required to record who the credit was added for","path":"/org-management/billing/add-credit","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Invalid customerOrgId <id> — The target org does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Invalid customerOrgId <id>","path":"/org-management/billing/add-credit","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"The credit.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"customerOrgId":{"type":"string","example":"org_4821"},"amount":{"type":"number","example":5000},"email":{"type":"string","description":"Who the credit was added for.","example":"ada@example.com"},"note":{"type":"string"}}},"example":{"customerOrgId":"org_4821","amount":5000,"email":"ada@example.com"}}}}}},"/org-management/subscription/plans":{"get":{"operationId":"OrgManagementController_getSubscriptionPlans","summary":"Get subscription plans","description":"The plans available. Public, since pricing pages show it before signup. `customer-org-id` (a **hyphenated** query parameter) scopes the list to what a specific org can take.\n\n#### Signature\n\n```http\nGET /org-management/subscription/plans (customer-org-id?: string) -> Plans\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /org-management/subscription/current`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"customer-org-id","required":false,"in":"query","schema":{"type":"string"},"description":"Note the hyphens — this is not `customerOrgId`.","example":"org_4821"},{"name":"app","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/subscription/current":{"get":{"operationId":"OrgManagementController_getCurrentSubscription","summary":"Get the current subscription","description":"The org's current plan, status and expiry. `customer-org-id` reads another org's.\n\n#### Signature\n\n```http\nGET /org-management/subscription/current (customer-org-id?: string) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `500` | PLAN_RETRIEVAL_FAILED | Failed to retrieve customer plan | The plan record could not be read. | Retry. |\n\nPlus the standard platform errors: `429`.\n\n#### See also\n\n- `POST /org-management/subscription/create`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"customer-org-id","required":false,"in":"query","schema":{"type":"string"},"example":"org_4821"}],"responses":{"200":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to retrieve customer plan — The plan record could not be read.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to retrieve customer plan","path":"/org-management/subscription/current","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Organization"]}},"/org-management/subscription/quote":{"get":{"operationId":"OrgManagementController_planChangeQuote","summary":"Plan change quote","description":"What moving to a plan costs today, less the unused days of the current plan","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"plan","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Organization Management"]}},"/org-management/subscription/create":{"post":{"operationId":"OrgManagementController_createSubscription","summary":"Create a subscription","description":"Starts a new subscription. **Charges the card** and sets the org's plan, which changes what the account is allowed to do.\n\n#### Signature\n\n```http\nPOST /org-management/subscription/create (body) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Charges a card and changes plan entitlements.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PLAN_REQUIRED | Plan is required | `plan` is missing. | Name a plan. |\n| `402` | PAYMENT_FAILED | Payment failed | The card was declined or the charge could not be taken. | Try another payment method. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /org-management/subscription/upgrade`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The plan.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","example":"pro-monthly"},"customerOrgId":{"type":"string","example":"org_4821"},"paymentMethodId":{"type":"string","example":"pm_1Abc123"}}},"example":{"plan":"pro-monthly","paymentMethodId":"pm_1Abc123"}}}},"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Plan is required — `plan` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Plan is required","path":"/org-management/subscription/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"Payment failed — The card was declined or the charge could not be taken.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"Payment failed","path":"/org-management/subscription/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/subscription/upgrade":{"post":{"operationId":"OrgManagementController_upgradeSubscription","summary":"Upgrade a subscription","description":"Moves the org to a higher plan. Charges the difference and raises the entitlements immediately.\n\n#### Signature\n\n```http\nPOST /org-management/subscription/upgrade (body) -> The subscription\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Charges the difference.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NEW_PLAN_REQUIRED | New plan is required | `newPlan` is missing. | Name the target plan. |\n| `402` | PAYMENT_FAILED | Payment failed | The card was declined or the charge could not be taken. | Try another payment method. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /org-management/subscription/downgrade`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The target plan.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["newPlan"],"properties":{"newPlan":{"type":"string","example":"enterprise-monthly"},"customerOrgId":{"type":"string"}}},"example":{"newPlan":"enterprise-monthly"}}}},"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"New plan is required — `newPlan` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"New plan is required","path":"/org-management/subscription/upgrade","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"402":{"description":"Payment failed — The card was declined or the charge could not be taken.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"Payment failed","path":"/org-management/subscription/upgrade","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/subscription/downgrade":{"post":{"operationId":"OrgManagementController_downgradeSubscription","summary":"Downgrade a subscription","description":"Moves the org to a lower plan. **Lowers entitlements**, so anything the org has that exceeds the new plan's limits — sites, seats, storage — may stop working or be refused on next use. Check usage against the target plan first.\n\n#### Signature\n\n```http\nPOST /org-management/subscription/downgrade (body) -> The subscription\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Reduces what the org is allowed to do.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NEW_PLAN_REQUIRED | New plan is required | `newPlan` is missing. | Name the target plan. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/subscription/upgrade`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The target plan.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["newPlan"],"properties":{"newPlan":{"type":"string","example":"starter-monthly"},"customerOrgId":{"type":"string"}}},"example":{"newPlan":"starter-monthly"}}}},"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"New plan is required — `newPlan` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"New plan is required","path":"/org-management/subscription/downgrade","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/subscription/cancel":{"post":{"operationId":"OrgManagementController_cancelSubscription","summary":"Cancel a subscription","description":"Cancels the current subscription. The org keeps its data but loses plan entitlements at the end of the term — separate from cancelling the account itself.\n\n#### Signature\n\n```http\nPOST /org-management/subscription/cancel (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/account/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Optional reason.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reason":"No longer needed"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/subscription/keep":{"post":{"operationId":"OrgManagementController_keepCurrentPlan","summary":"Keep current plan","description":"Undo a downgrade or cancel waiting for the end of the period","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Organization Management"]}},"/org-management/subscription/admin/update":{"post":{"operationId":"OrgManagementController_updateCustomerPlan","summary":"Update a customer plan (admin)","description":"Admin override for a customer's plan — type, status and expiry — with audit logging. Sets the plan directly without payment, so it is the tool for a negotiated arrangement, not the normal upgrade path.\n\n#### Signature\n\n```http\nPOST /org-management/subscription/admin/update (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Bypasses payment. Audited.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/subscription/current`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/subscription/admin/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"The plan fields to set.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"customerOrgId":"org_4821","planType":"enterprise","status":"active","expiry":"2027-08-30"}}}}}},"/org-management/subscription/complete-payment":{"post":{"operationId":"OrgManagementController_completeSubscriptionPayment","summary":"Complete a subscription payment","description":"Finalises a pending subscription payment after Stripe validation and activates the plan.\n\n#### Signature\n\n```http\nPOST /org-management/subscription/complete-payment (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PAYMENT_INTENT_REQUIRED | Payment intent ID is required | No intent id was supplied. | Pass the intent id from the client-side confirmation. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /org-management/subscription/complete-checkout`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The payment reference.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentIntentId":{"type":"string","example":"pi_3Abc123"}}},"example":{"paymentIntentId":"pi_3Abc123"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Payment intent ID is required — No intent id was supplied.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Payment intent ID is required","path":"/org-management/subscription/complete-payment","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/subscription/complete-checkout":{"post":{"operationId":"OrgManagementController_completeSubscriptionCheckout","summary":"Complete a subscription checkout","description":"Activates a subscription after a successful Stripe Checkout session. The session id is single-use — a replay is refused rather than starting a second subscription.\n\n#### Signature\n\n```http\nPOST /org-management/subscription/complete-checkout (body) -> The subscription\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SESSION_REQUIRED | Session ID is required | `sessionId` is missing. | Pass the Stripe session id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/subscription/complete-payment`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The checkout session.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string","example":"cs_test_a1b2c3"}}},"example":{"sessionId":"cs_test_a1b2c3"}}}},"responses":{"201":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Session ID is required — `sessionId` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Session ID is required","path":"/org-management/subscription/complete-checkout","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/account/cancel":{"post":{"operationId":"OrgManagementController_cancelAccount","summary":"Cancel the account","description":"Cancels the entire organization account — not just the subscription. Everything the org runs stops. Reactivation is an admin action, so this is not something a customer can undo themselves.\n\n#### Signature\n\n```http\nPOST /org-management/account/cancel (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Takes the whole org offline; only an admin can reverse it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | EMAIL_MISMATCH | Email confirmation does not match | The confirmation email does not match the org's. | Type the account email exactly. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /org-management/account/reactivate`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Confirmation and reason.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"confirmEmail":"owner@acme.example","reason":"Closing the business"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Email confirmation does not match — The confirmation email does not match the org's.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Email confirmation does not match","path":"/org-management/account/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/account/delete":{"post":{"operationId":"OrgManagementController_deleteOwnAccount","summary":"Delete the account (owner)","description":"The owner deletes the whole account; the account profile has them sign in again first (password, or the emailed sign-in code). Cancels the subscription, removes websites, domain connections and dev environments, drops all data, and takes the account off email sign-in. Cannot be undone. Root admins also have POST /org-management/delete.\n\n#### Signature\n\n```http\nPOST /org-management/account/delete () -> deleted: true\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `Owner`.\n\n#### Notes\n\n- Cannot be undone.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | PLATFORM_ACCOUNT | This is the platform's own account. It can't be deleted here. | The org is the root or shared platform org. | None. |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/account/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"deleted: true","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"This is the platform's own account. It can't be deleted here. — The org is the root or shared platform org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This is the platform's own account. It can't be deleted here.","path":"/org-management/account/delete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/account/reactivate":{"put":{"operationId":"OrgManagementController_reactivateAccount","summary":"Reactivate an account (admin)","description":"Brings a cancelled account back. Admin only; refused if the account is already active.\n\n#### Signature\n\n```http\nPUT /org-management/account/reactivate () -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | ALREADY_ACTIVE | Account is already active | The account was not cancelled. | Nothing to do. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/account/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Account is already active — The account was not cancelled.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Account is already active","path":"/org-management/account/reactivate","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/pre-approved-signups":{"post":{"operationId":"OrgManagementController_addPreApprovedSignup","summary":"Add a pre-approved signup (admin)","description":"Adds an email or a signup code to the pre-approved list. A code can be redeemed by anyone who has it, so treat codes as shareable and emails as individual.\n\n#### Signature\n\n```http\nPOST /org-management/pre-approved-signups (body) -> The entry\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `ConfigAdmin`.\n\n#### Notes\n\n- A code is usable by anyone holding it.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_EMAIL_FORMAT | Invalid email format | The email is malformed. | Supply a valid address. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/pre-approved-signups/remove`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The entry.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","example":"ada@example.com"},"code":{"type":"string","example":"PARTNER-2026"}}},"example":{"email":"ada@example.com"}}}},"responses":{"201":{"description":"The entry","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid email format — The email is malformed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid email format","path":"/org-management/pre-approved-signups","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]},"get":{"operationId":"OrgManagementController_getPreApprovedSignups","summary":"List pre-approved signups (admin)","description":"The emails and signup codes cleared to register.\n\n#### Signature\n\n```http\nGET /org-management/pre-approved-signups (type?: string, active?: boolean) -> Pre-approved entries\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/pre-approved-signups`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"type","required":false,"in":"query","description":"`email` or `code`.","schema":{"type":"string"},"example":"email"},{"name":"active","required":false,"in":"query","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"Pre-approved entries","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/pre-approved-signups/remove":{"post":{"operationId":"OrgManagementController_removePreApprovedSignup","summary":"Remove a pre-approved signup (admin)","description":"Removes an email or code from the pre-approved list, so it can no longer be used to register.\n\n#### Signature\n\n```http\nPOST /org-management/pre-approved-signups/remove (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/pre-approved-signups`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The entry to remove.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/pre-approved-signups/validate":{"post":{"operationId":"OrgManagementController_validatePreApprovedSignup","summary":"Validate a pre-approved signup","description":"Checks whether an email or code is cleared to sign up. **Public**, because it runs before an account exists — which also makes it an oracle for whether a given email is on the list, so rate-limit it.\n\n#### Signature\n\n```http\nPOST /org-management/pre-approved-signups/validate (body) -> Whether it is approved\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated; confirms list membership.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /org-management/pre-approved-signups`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to check.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com"}}}},"responses":{"201":{"description":"Whether it is approved","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"approved":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/org-register":{"post":{"operationId":"OrgManagementController_registerOrganization","summary":"Register an organization","description":"Creates an organization and, optionally, a development environment for cloud development. Provisioning a site or dev environment can fail after the org is created, so check the response rather than assuming all parts exist.\n\n#### Signature\n\n```http\nPOST /org-management/org-register (body) -> The organization\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `System`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Partial success is possible.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `422` | INVALID_EMAIL | Invalid Email <email> | The owner email is malformed. | Supply a valid address. |\n| `500` | PROVISIONING_FAILED | Failed to create site or dev environment | The org was created but provisioning failed. | The org exists — retry the provisioning step rather than re-registering. |\n\nPlus the standard platform errors: `401`, `403`, `429`.\n\n#### See also\n\n- `GET /org-management/check-org-name/{orgName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The organization to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"orgName":"acme","ownerEmail":"owner@acme.example","createDevEnv":true}}}},"responses":{"201":{"description":"The organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Invalid Email <email> — The owner email is malformed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Invalid Email <email>","path":"/org-management/org-register","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Failed to create site or dev environment — The org was created but provisioning failed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":500,"error":"Failed to create site or dev environment","path":"/org-management/org-register","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["Organization"]}},"/org-management/business-made-register":{"post":{"operationId":"OrgManagementController_registerBusinessMadeOrganization","summary":"Register a Business Made organization","description":"Public org creation dedicated to the Business Made app. **Origin/Referer must match** localhost, appmint.io or businessmade.io — that check is the only thing standing between this route and open org creation, since it is otherwise unauthenticated.\n\nIt forces the plan into the `bm-*` family and does **not** provision a site or dev environment, unlike `org-register`.\n\n#### Signature\n\n```http\nPOST /org-management/business-made-register (body) -> The organization\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated; gated only by Origin/Referer.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | ORIGIN_NOT_ALLOWED | Origin not allowed | The Origin or Referer is not one of the permitted hosts. | Call it from an allowed front end. |\n| `422` | INVALID_EMAIL | Invalid Email <email> | The owner email is malformed. | Supply a valid address. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /org-management/org-register`","parameters":[{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The organization.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"orgName":"acme-hr","ownerEmail":"owner@acme.example"}}}},"responses":{"201":{"description":"The organization","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Origin not allowed — The Origin or Referer is not one of the permitted hosts.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Origin not allowed","path":"/org-management/business-made-register","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"422":{"description":"Invalid Email <email> — The owner email is malformed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":422,"error":"Invalid Email <email>","path":"/org-management/business-made-register","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/delete":{"post":{"operationId":"OrgManagementController_deleteOrganization","summary":"Delete an organization","description":"Deletes an organization and, optionally, its sites and resources. Destructive and not recoverable through this API — everything the org owns goes with it. Cancel the account instead if the data may be needed.\n\n#### Signature\n\n```http\nPOST /org-management/delete (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `System`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Irreversible. Prefer account cancellation.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/account/cancel`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to delete.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","example":"org_4821"},"deleteSites":{"type":"boolean","example":true},"deleteResources":{"type":"boolean","example":true}}},"example":{"orgId":"org_4821","deleteSites":true}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/delete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/services/available":{"get":{"operationId":"OrgManagementController_getAvailableServices","summary":"Get available services","description":"Additional services the org can buy — export time, support and the like.\n\n#### Signature\n\n```http\nGET /org-management/services/available (category?: string) -> Available services\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/services/purchase`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"category","required":false,"in":"query","schema":{"type":"string"},"example":"support"}],"responses":{"200":{"description":"Available services","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/services/purchase":{"post":{"operationId":"OrgManagementController_purchaseService","summary":"Purchase a service","description":"Buys an additional service. Charges the card or draws down credit, depending on the service.\n\n#### Signature\n\n```http\nPOST /org-management/services/purchase (body) -> The purchase\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Costs money.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SERVICE_ID_REQUIRED | Service ID is required | `serviceId` is missing. | Name the service. |\n| `402` | PAYMENT_FAILED | Payment failed | The card was declined or the charge could not be taken. | Try another payment method. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/services/complete-payment`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to buy.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["serviceId"],"properties":{"serviceId":{"type":"string","example":"export-time"},"quantity":{"type":"integer","example":1}}},"example":{"serviceId":"export-time","quantity":1}}}},"responses":{"201":{"description":"The purchase","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Service ID is required — `serviceId` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Service ID is required","path":"/org-management/services/purchase","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"description":"Payment failed — The card was declined or the charge could not be taken.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":402,"error":"Payment failed","path":"/org-management/services/purchase","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/services/purchased":{"get":{"operationId":"OrgManagementController_getPurchasedServices","summary":"Get purchased services","description":"Services the org has bought and their status.\n\n#### Signature\n\n```http\nGET /org-management/services/purchased (status?: string) -> Purchased services\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/services/available`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"example":"active"}],"responses":{"200":{"description":"Purchased services","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/services/complete-payment":{"post":{"operationId":"OrgManagementController_completeServicePayment","summary":"Complete a service payment","description":"Finalises a pending service payment after gateway validation and activates the service.\n\n#### Signature\n\n```http\nPOST /org-management/services/complete-payment (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | PAYMENT_INTENT_REQUIRED | Payment intent ID is required | No intent id was supplied. | Pass the intent id from the client-side confirmation. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/services/purchase`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The payment reference.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"paymentIntentId":"pi_3Abc123"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Payment intent ID is required — No intent id was supplied.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Payment intent ID is required","path":"/org-management/services/complete-payment","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/transfer/ownership":{"post":{"operationId":"OrgManagementController_transferOrgOwnership","summary":"Transfer organization ownership","description":"Hands an organization to a new email, creating a user account for the new owner with the admin role.\n\nThis gives someone else administrative control of the org. There is no confirmation step from the recipient — the transfer takes effect on the call, so verify the address character by character.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/ownership (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Notes\n\n- Grants admin control immediately, with no recipient confirmation.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_NEW_OWNER_EMAIL | Invalid email format for new owner | The address is malformed. | Check the address. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/transfer/change-email`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid email format for new owner — The address is malformed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid email format for new owner","path":"/org-management/transfer/ownership","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"The new owner.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["newOwnerEmail"],"properties":{"newOwnerEmail":{"type":"string","example":"newowner@acme.example"}}},"example":{"newOwnerEmail":"newowner@acme.example"}}}}}},"/org-management/transfer/change-email":{"post":{"operationId":"OrgManagementController_changeOrgPrimaryEmail","summary":"Change the primary email","description":"Changes an org's primary email **without** transferring ownership — for a rename or a mailbox change, where `transfer/ownership` would be wrong.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/change-email (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_EMAIL_FORMAT | Invalid email format | The address is malformed. | Check the address. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/transfer/ownership`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid email format — The address is malformed.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid email format","path":"/org-management/transfer/change-email","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"The new email.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["newEmail"],"properties":{"newEmail":{"type":"string","example":"billing@acme.example"}}},"example":{"newEmail":"billing@acme.example"}}}}}},"/org-management/transfer/assets":{"post":{"operationId":"OrgManagementController_transferAssets","summary":"Transfer assets between organizations","description":"Moves or copies assets from one org to another. **`move` deletes the original** — copy first if there is any doubt, since a move across orgs is not undone by transferring back.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/assets (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- `move` is destructive on the source.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SAME_ORG | Source and target organizations cannot be the same | Source and target match. | Pick two different orgs. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/transfer/assets-bulk`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Source and target organizations cannot be the same — Source and target match.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Source and target organizations cannot be the same","path":"/org-management/transfer/assets","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"What to transfer, and how.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceOrgId":{"type":"string","example":"org_4821"},"targetOrgId":{"type":"string","example":"org_7712"},"assetType":{"type":"string","example":"product"},"ids":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["copy","move"],"description":"`move` deletes the original.","example":"copy"}}},"example":{"sourceOrgId":"org_4821","targetOrgId":"org_7712","assetType":"product","mode":"copy"}}}}}},"/org-management/transfer/assets-bulk":{"post":{"operationId":"OrgManagementController_transferAssetsBulk","summary":"Bulk-transfer assets between organizations","description":"Transfers several asset types at once. Same `copy`/`move` semantics as the single form, applied across everything named — which makes a `move` here considerably wider in blast radius.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/assets-bulk (body) -> Per-type results\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- A bulk `move` deletes across every named type.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | SAME_ORG | Source and target organizations cannot be the same | Source and target match. | Pick two different orgs. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/transfer/assets`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"Per-type results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Source and target organizations cannot be the same — Source and target match.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Source and target organizations cannot be the same","path":"/org-management/transfer/assets-bulk","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"What to transfer.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceOrgId":{"type":"string","example":"org_4821"},"targetOrgId":{"type":"string","example":"org_7712"},"assetTypes":{"type":"array","items":{"type":"string"},"example":["product","customer"]},"mode":{"type":"string","enum":["copy","move"],"example":"copy"}}},"example":{"sourceOrgId":"org_4821","targetOrgId":"org_7712","assetTypes":["product","customer"],"mode":"copy"}}}}}},"/org-management/services/pricing/{serviceName}":{"get":{"operationId":"OrgManagementController_getServicePricing","summary":"Get service pricing","description":"Pricing and terms for one service.\n\n#### Signature\n\n```http\nGET /org-management/services/pricing/{serviceName} (serviceName: string) -> Pricing and terms\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/services/available`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"serviceName","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"export-time"}],"responses":{"200":{"description":"Pricing and terms","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/services/agreements":{"get":{"operationId":"OrgManagementController_getServiceAgreements","summary":"Get service agreements","description":"Every service agreement the org has, and its state.\n\n#### Signature\n\n```http\nGET /org-management/services/agreements () -> Agreements\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/services/agreement/{serviceName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Agreements","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/init/{orgid}":{"get":{"operationId":"OrgManagementController_initStatus","summary":"Check an org's initialization","description":"Per step, whether the org has what every org starts with: the access-request workflow, the `meeting` reservation definition, and the publishing-approval workflow (seeded switched off). `complete` is true when every step is present.\n\n#### Signature\n\n```http\nGET /org-management/init/{orgid} (orgid: string) -> { orgId, steps: [{ key, title, present }], complete }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootSystem`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/init/{orgid}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orgid","in":"path","required":true,"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","schema":{"type":"string"},"example":"org_4821"}],"responses":{"200":{"description":"{ orgId, steps: [{ key, title, present }], complete }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"orgId":"acme","complete":false,"steps":[{"key":"workflow.access-approval","title":"Access request workflow","present":true},{"key":"reservation-definition.meeting","title":"Meeting bookings (reservation definition \"meeting\")","present":false}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]},"post":{"operationId":"OrgManagementController_initRun","summary":"Initialize an org","parameters":[{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"{ orgId, done, present, failed }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"orgId":"acme","done":["reservation-definition.meeting"],"present":["workflow.access-approval","workflow.publish-approval"],"failed":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"description":"Runs every initialization step the org is missing and leaves the rest alone — safe to repeat. A step that fails is reported and the others still run.\n\n#### Signature\n\n```http\nPOST /org-management/init/{orgid} (orgid: string) -> { orgId, done, present, failed }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootSystem`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/init/{orgid}`"}},"/org-management/setup/catalog":{"get":{"operationId":"OrgManagementController_getSetupCatalog","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"The catalog with status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Get the setup wizard catalog","description":"Every configuration item in the setup wizard, with live per-item status and completeness for this org — one call behind a whole onboarding checklist.\n\n#### Signature\n\n```http\nGET /org-management/setup/catalog () -> The catalog with status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/company/meta`"}},"/org-management/services/agreement/{serviceName}":{"get":{"operationId":"OrgManagementController_getServiceAgreement","summary":"Get a service agreement","description":"Whether the org has accepted the terms for one shareable service.\n\n#### Signature\n\n```http\nGET /org-management/services/agreement/{serviceName} (serviceName: string) -> The agreement status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/services/agreement/accept/{serviceName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"serviceName","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"export-time"}],"responses":{"200":{"description":"The agreement status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/services/agreement/accept/{serviceName}":{"post":{"operationId":"OrgManagementController_acceptServiceAgreement","summary":"Accept a service agreement","description":"Records acceptance of the terms for a shareable service — a legal act on the org's behalf, recorded against the accepting user.\n\n#### Signature\n\n```http\nPOST /org-management/services/agreement/accept/{serviceName} (serviceName: string, body) -> The agreement\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Records a binding acceptance.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/services/agreement/revoke/{serviceName}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"serviceName","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"export-time"}],"responses":{"201":{"description":"The agreement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"Acceptance detail.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"version":"2026-01"}}}}}},"/org-management/services/agreement/revoke/{serviceName}":{"post":{"operationId":"OrgManagementController_revokeServiceAgreement","summary":"Revoke a service agreement","description":"Withdraws acceptance for a shareable service. Anything relying on that agreement stops working.\n\n#### Signature\n\n```http\nPOST /org-management/services/agreement/revoke/{serviceName} (serviceName: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/services/agreements`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"serviceName","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"export-time"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/users/{orgid}":{"get":{"operationId":"OrgManagementController_getOrgUsers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"},{"name":"q","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Users","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"List an organization's users","description":"Users in the named org. The path `orgid` is the org being read; the header identifies the caller, which is what lets an operator read another org's users.\n\n#### Signature\n\n```http\nGET /org-management/users/{orgid} (orgid: string) -> Users\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/users/{orgid}/{userId}`"}},"/org-management/users/{orgid}/{userId}":{"get":{"operationId":"OrgManagementController_getOrgUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"},{"name":"userId","required":true,"in":"path","schema":{"type":"string"},"description":"User id.","example":"USR-4821"}],"responses":{"200":{"description":"The user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}/{userId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Get an organization user","description":"One user in the named org.\n\n#### Signature\n\n```http\nGET /org-management/users/{orgid}/{userId} (orgid: string, userId: string) -> The user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/users/{orgid}/update`"}},"/org-management/users/{orgid}/create":{"post":{"operationId":"OrgManagementController_createOrgUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The user","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Create an organization user","description":"Creates a user inside the named org. The role given here decides what they can do — a user created with an admin role has administrative control from the moment they sign in.\n\n#### Signature\n\n```http\nPOST /org-management/users/{orgid}/create (orgid: string, body) -> The user\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- The role grants real access.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/users/{orgid}/update`","requestBody":{"description":"The user.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@acme.example","firstName":"Ada","lastName":"Lovelace","role":"editor"}}}}}},"/org-management/users/{orgid}/update":{"post":{"operationId":"OrgManagementController_updateOrgUser","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Update an organization user","description":"Updates a user in the named org, including their role. A role change takes effect on their next request.\n\n#### Signature\n\n```http\nPOST /org-management/users/{orgid}/update (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/users/{orgid}/status`","requestBody":{"description":"The user id and fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"USR-4821","role":"admin"}}}}}},"/org-management/users/{orgid}/status":{"post":{"operationId":"OrgManagementController_setOrgUsersStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}/status","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Set organization users' status","description":"Activates or deactivates users in bulk. Deactivating removes their access at once — the reversible alternative to deleting them.\n\n#### Signature\n\n```http\nPOST /org-management/users/{orgid}/status (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/users/{orgid}/delete`","requestBody":{"description":"Which users, and the status.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"example":["USR-4821"]},"status":{"type":"string","example":"inactive"}}},"example":{"ids":["USR-4821"],"status":"inactive"}}}}}},"/org-management/users/{orgid}/delete":{"post":{"operationId":"OrgManagementController_deleteOrgUsers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}/delete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Delete organization users","description":"Permanently removes users from the named org. Deactivate instead unless the records genuinely should not exist — deletion loses the audit association with anything they did.\n\n#### Signature\n\n```http\nPOST /org-management/users/{orgid}/delete (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Irreversible; prefer deactivation.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/users/{orgid}/status`","requestBody":{"description":"Which users.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"example":["USR-4821"]}}},"example":{"ids":["USR-4821"]}}}}}},"/org-management/users/{orgid}/change-password":{"post":{"operationId":"OrgManagementController_resetOrgUserPassword","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}/change-password","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Change an organization user's password","description":"Sets a user's password directly, without their involvement. An administrative override — the user is not asked to confirm, and any session they hold may be invalidated. Prefer sending a reset link.\n\n#### Signature\n\n```http\nPOST /org-management/users/{orgid}/change-password (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Sensitive payload; prefer `send-reset`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/users/{orgid}/send-reset`","requestBody":{"description":"The user and the new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"USR-4821","password":"<new password>"}}}}}},"/org-management/users/{orgid}/send-reset":{"post":{"operationId":"OrgManagementController_sendOrgUserReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/users/{orgid}/send-reset","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Send a password reset to an organization user","description":"Emails a reset link to the user, letting them set their own password. The preferred route — it sends a real email, so check the recipient.\n\n#### Signature\n\n```http\nPOST /org-management/users/{orgid}/send-reset (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Sends an email.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/users/{orgid}/change-password`","requestBody":{"description":"Which user.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"USR-4821"}}}}}},"/org-management/customers/{orgid}":{"get":{"operationId":"OrgManagementController_getOrgCustomers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"},{"name":"q","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Customers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"List an organization's customers","description":"Customers belonging to the named org. Customers are the org's end users, distinct from its staff users.\n\n#### Signature\n\n```http\nGET /org-management/customers/{orgid} (orgid: string) -> Customers\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/users/{orgid}`"}},"/org-management/customers/{orgid}/{customerId}":{"get":{"operationId":"OrgManagementController_getOrgCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"},{"name":"customerId","required":true,"in":"path","schema":{"type":"string"},"description":"Customer id.","example":"CUST-4821"}],"responses":{"200":{"description":"The customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}/{customerId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Get an organization customer","description":"One customer in the named org.\n\n#### Signature\n\n```http\nGET /org-management/customers/{orgid}/{customerId} (orgid: string, customerId: string) -> The customer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/customers/{orgid}/update`"}},"/org-management/customers/{orgid}/create":{"post":{"operationId":"OrgManagementController_createOrgCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}/create","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Create an organization customer","description":"Creates a customer in the named org.\n\n#### Signature\n\n```http\nPOST /org-management/customers/{orgid}/create (orgid: string, body) -> The customer\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/customers/{orgid}/update`","requestBody":{"description":"The customer.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace"}}}}}},"/org-management/customers/{orgid}/update":{"post":{"operationId":"OrgManagementController_updateOrgCustomer","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}/update","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Update an organization customer","description":"Updates a customer in the named org.\n\n#### Signature\n\n```http\nPOST /org-management/customers/{orgid}/update (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/customers/{orgid}/status`","requestBody":{"description":"The customer id and fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"CUST-4821","phone":"+15551234567"}}}}}},"/org-management/customers/{orgid}/status":{"post":{"operationId":"OrgManagementController_setOrgCustomersStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}/status","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Set organization customers' status","description":"Activates or deactivates customers in bulk. Deactivated customers cannot sign in.\n\n#### Signature\n\n```http\nPOST /org-management/customers/{orgid}/status (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/customers/{orgid}/delete`","requestBody":{"description":"Which customers, and the status.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ids":["CUST-4821"],"status":"inactive"}}}}}},"/org-management/customers/{orgid}/delete":{"post":{"operationId":"OrgManagementController_deleteOrgCustomers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}/delete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Delete organization customers","description":"Permanently removes customers. Their orders, bookings and history may reference them — deactivate unless the records genuinely must go.\n\n#### Signature\n\n```http\nPOST /org-management/customers/{orgid}/delete (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Irreversible; breaks references from historical records.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/customers/{orgid}/status`","requestBody":{"description":"Which customers.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ids":["CUST-4821"]}}}}}},"/org-management/customers/{orgid}/change-password":{"post":{"operationId":"OrgManagementController_resetOrgCustomerPassword","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}/change-password","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Change an organization customer's password","description":"Sets a customer's password directly. An administrative override, without the customer's involvement — prefer sending a reset link.\n\n#### Signature\n\n```http\nPOST /org-management/customers/{orgid}/change-password (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Sensitive payload; prefer `send-reset`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/customers/{orgid}/send-reset`","requestBody":{"description":"The customer and the new password.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"CUST-4821","password":"<new password>"}}}}}},"/org-management/customers/{orgid}/send-reset":{"post":{"operationId":"OrgManagementController_sendOrgCustomerReset","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"path","schema":{"type":"string"},"description":"The org being acted on — separate from the `orgid` **header**, which identifies the caller.","example":"org_4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid orgId — The org id is missing or not a real org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid orgId","path":"/org-management/customers/{orgid}/send-reset","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"summary":"Send a password reset to an organization customer","description":"Emails a reset link to the customer. Requires the customer to have an email on file — without one there is nowhere to send it.\n\n#### Signature\n\n```http\nPOST /org-management/customers/{orgid}/send-reset (orgid: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`.\n\n#### Notes\n\n- Sends an email.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVALID_ORG_ID | Invalid orgId | The org id is missing or not a real org. | Check the id. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /org-management/customers/{orgid}/change-password`","requestBody":{"description":"Which customer.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"CUST-4821"}}}}}},"/org-management/transfer/requests":{"post":{"operationId":"OrgTransferController_createRequest","summary":"Ask another org to accept a data transfer","description":"The source org (the `orgid` header) asks a target org to accept a **copy** or **move** of records. Nothing moves until a ConfigAdmin of the target org accepts. Name what to send as `scope` — per collection, `select: all | filter | ids` — or with the older `assets: { datatype: [ids] }`. Every entry is counted up front; one request carries at most **100,000** records. The request expires after **7 days** if nobody decides. The target org gets an in-app notice and an email.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/requests (body) -> The request as the caller sees it\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | TARGET_REQUIRED | targetOrgId is required | No target org. | — |\n| `404` | TARGET_NOT_FOUND | Target organization acme-eu not found | The target org does not exist. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /org-management/transfer/requests/check-org/{targetOrgId}`\n- `POST /org-management/transfer/requests/{id}/accept`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The request as the caller sees it","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","running","completed","partial","failed","rejected","cancelled","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Which side the caller is on."},"sourceOrgId":{"type":"string"},"targetOrgId":{"type":"string"},"mode":{"type":"string","enum":["copy","move"]},"datatypes":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"object","additionalProperties":true}},"totalRecords":{"type":"integer"},"processedRecords":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"requestedBy":{"type":"string"},"requestedAt":{"type":"string"},"expiresAt":{"type":"string"},"acceptedBy":{"type":"string"},"rejectReason":{"type":"string"},"successCount":{"type":"integer"},"failCount":{"type":"integer"},"results":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"targetOrgId is required — No target org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"targetOrgId is required","path":"/org-management/transfer/requests","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Target organization acme-eu not found — The target org does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Target organization acme-eu not found","path":"/org-management/transfer/requests","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"What to send and to whom.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetOrgId"],"properties":{"targetOrgId":{"type":"string"},"scope":{"type":"array","items":{"type":"object","properties":{"datatype":{"type":"string"},"select":{"type":"string","enum":["all","filter","ids"]},"filter":{"type":"object","additionalProperties":true},"ids":{"type":"array","items":{"type":"string"}}}}},"assets":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"mode":{"type":"string","enum":["copy","move"],"default":"copy"},"reason":{"type":"string"},"message":{"type":"string"}}},"examples":{"collections":{"summary":"Whole collections","value":{"targetOrgId":"acme-eu","mode":"copy","scope":[{"datatype":"sf_product","select":"all"}],"reason":"Opening the EU store"}},"rows":{"summary":"Chosen records","value":{"targetOrgId":"acme-eu","assets":{"page":["65f0c2a1e4b0a1b2c3d4e5f6"]}}}}}}}},"get":{"operationId":"OrgTransferController_listRequests","summary":"List transfer requests","description":"Requests where this org is the source (`outgoing`) or the target (`incoming`), newest first. A pending request past its expiry is reported as `expired` when read.\n\n#### Signature\n\n```http\nGET /org-management/transfer/requests (direction?: string, status?: string, page?: integer, pageSize?: integer) -> { data, total }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"direction","required":false,"in":"query","schema":{"type":"string","enum":["incoming","outgoing","all"],"default":"all"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","accepted","running","completed","partial","failed","rejected","cancelled","expired"]}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"{ data, total }","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","running","completed","partial","failed","rejected","cancelled","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Which side the caller is on."},"sourceOrgId":{"type":"string"},"targetOrgId":{"type":"string"},"mode":{"type":"string","enum":["copy","move"]},"datatypes":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"object","additionalProperties":true}},"totalRecords":{"type":"integer"},"processedRecords":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"requestedBy":{"type":"string"},"requestedAt":{"type":"string"},"expiresAt":{"type":"string"},"acceptedBy":{"type":"string"},"rejectReason":{"type":"string"},"successCount":{"type":"integer"},"failCount":{"type":"integer"},"results":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/transfer/requests/check-org/{targetOrgId}":{"get":{"operationId":"OrgTransferController_checkOrg","summary":"Check a target org before sending","description":"Whether a transfer could name this org, and its display name — so the sender learns before building a request. Returns existence and name only.\n\n#### Signature\n\n```http\nGET /org-management/transfer/requests/check-org/{targetOrgId} (targetOrgId: string) -> { exists, orgId, name? , reason? }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"targetOrgId","required":true,"in":"path","description":"Org id to check.","schema":{"type":"string"},"example":"acme-eu"}],"responses":{"200":{"description":"{ exists, orgId, name? , reason? }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"found":{"summary":"Exists","value":{"exists":true,"orgId":"acme-eu","name":"Acme EU"}},"self":{"summary":"Own org","value":{"exists":false,"orgId":"acme","reason":"That is this organization"}},"missing":{"summary":"Unknown","value":{"exists":false,"orgId":"acme-xx","reason":"No organization with that id"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/transfer/requests/{id}":{"get":{"operationId":"OrgTransferController_getRequest","summary":"Get one transfer request","description":"One request with its progress (`processedRecords` of `totalRecords`) and, once finished, `successCount`, `failCount` and `results`. Only the source or target org can read it; to anyone else it does not exist.\n\n#### Signature\n\n```http\nGET /org-management/transfer/requests/{id} (id: string) -> The request\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TRANSFER_NOT_FOUND | Transfer request not found | No such request, or the caller's org is neither its source nor its target. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Transfer request id.","schema":{"type":"string"},"example":"66f1c0ffee12ab34cd56ef78"}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","running","completed","partial","failed","rejected","cancelled","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Which side the caller is on."},"sourceOrgId":{"type":"string"},"targetOrgId":{"type":"string"},"mode":{"type":"string","enum":["copy","move"]},"datatypes":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"object","additionalProperties":true}},"totalRecords":{"type":"integer"},"processedRecords":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"requestedBy":{"type":"string"},"requestedAt":{"type":"string"},"expiresAt":{"type":"string"},"acceptedBy":{"type":"string"},"rejectReason":{"type":"string"},"successCount":{"type":"integer"},"failCount":{"type":"integer"},"results":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Transfer request not found — No such request, or the caller's org is neither its source nor its target.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Transfer request not found","path":"/org-management/transfer/requests/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/transfer/requests/{id}/accept":{"post":{"operationId":"OrgTransferController_acceptRequest","summary":"Accept a transfer request","description":"The target org accepts. The request switches to `running` and comes back at once; the records are copied (or moved) in batches of 200 in the background, writing progress onto the request, and both orgs are told when it ends. Poll `GET …/requests/{id}` for progress.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/requests/{id}/accept (id: string) -> The request, now running\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TRANSFER_NOT_FOUND | Transfer request not found | No such request, or the caller's org is neither its source nor its target. | — |\n| `400` | NOT_PENDING | Transfer request is running, not pending | The request has already been decided, cancelled or has expired. | — |\n| `403` | NOT_TARGET | Only the target organization can accept a transfer request | The caller is the source org. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Transfer request id.","schema":{"type":"string"},"example":"66f1c0ffee12ab34cd56ef78"}],"responses":{"201":{"description":"The request, now running","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","running","completed","partial","failed","rejected","cancelled","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Which side the caller is on."},"sourceOrgId":{"type":"string"},"targetOrgId":{"type":"string"},"mode":{"type":"string","enum":["copy","move"]},"datatypes":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"object","additionalProperties":true}},"totalRecords":{"type":"integer"},"processedRecords":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"requestedBy":{"type":"string"},"requestedAt":{"type":"string"},"expiresAt":{"type":"string"},"acceptedBy":{"type":"string"},"rejectReason":{"type":"string"},"successCount":{"type":"integer"},"failCount":{"type":"integer"},"results":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"Transfer request is running, not pending — The request has already been decided, cancelled or has expired.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Transfer request is running, not pending","path":"/org-management/transfer/requests/{id}/accept","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the target organization can accept a transfer request — The caller is the source org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the target organization can accept a transfer request","path":"/org-management/transfer/requests/{id}/accept","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Transfer request not found — No such request, or the caller's org is neither its source nor its target.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Transfer request not found","path":"/org-management/transfer/requests/{id}/accept","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/org-management/transfer/requests/{id}/reject":{"post":{"operationId":"OrgTransferController_rejectRequest","summary":"Reject a transfer request","description":"The target org declines, optionally saying why. The source org is told.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/requests/{id}/reject (id: string, body) -> The request, now rejected\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TRANSFER_NOT_FOUND | Transfer request not found | No such request, or the caller's org is neither its source nor its target. | — |\n| `400` | NOT_PENDING | Transfer request is running, not pending | The request has already been decided, cancelled or has expired. | — |\n| `403` | NOT_TARGET | Only the target organization can reject a transfer request | The caller is the source org. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Transfer request id.","schema":{"type":"string"},"example":"66f1c0ffee12ab34cd56ef78"}],"responses":{"201":{"description":"The request, now rejected","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","running","completed","partial","failed","rejected","cancelled","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Which side the caller is on."},"sourceOrgId":{"type":"string"},"targetOrgId":{"type":"string"},"mode":{"type":"string","enum":["copy","move"]},"datatypes":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"object","additionalProperties":true}},"totalRecords":{"type":"integer"},"processedRecords":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"requestedBy":{"type":"string"},"requestedAt":{"type":"string"},"expiresAt":{"type":"string"},"acceptedBy":{"type":"string"},"rejectReason":{"type":"string"},"successCount":{"type":"integer"},"failCount":{"type":"integer"},"results":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"Transfer request is running, not pending — The request has already been decided, cancelled or has expired.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Transfer request is running, not pending","path":"/org-management/transfer/requests/{id}/reject","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the target organization can reject a transfer request — The caller is the source org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the target organization can reject a transfer request","path":"/org-management/transfer/requests/{id}/reject","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Transfer request not found — No such request, or the caller's org is neither its source nor its target.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Transfer request not found","path":"/org-management/transfer/requests/{id}/reject","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"],"requestBody":{"description":"Why.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Wrong catalogue"}}}}}},"/org-management/transfer/requests/{id}/cancel":{"post":{"operationId":"OrgTransferController_cancelRequest","summary":"Cancel a transfer request","description":"The source org withdraws a request before the target decides. The target is told.\n\n#### Signature\n\n```http\nPOST /org-management/transfer/requests/{id}/cancel (id: string) -> The request, now cancelled\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TRANSFER_NOT_FOUND | Transfer request not found | No such request, or the caller's org is neither its source nor its target. | — |\n| `400` | NOT_PENDING | Transfer request is running, not pending | The request has already been decided, cancelled or has expired. | — |\n| `403` | NOT_SOURCE | Only the source organization can cancel a transfer request | The caller is the target org. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Transfer request id.","schema":{"type":"string"},"example":"66f1c0ffee12ab34cd56ef78"}],"responses":{"201":{"description":"The request, now cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","running","completed","partial","failed","rejected","cancelled","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Which side the caller is on."},"sourceOrgId":{"type":"string"},"targetOrgId":{"type":"string"},"mode":{"type":"string","enum":["copy","move"]},"datatypes":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"object","additionalProperties":true}},"totalRecords":{"type":"integer"},"processedRecords":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"requestedBy":{"type":"string"},"requestedAt":{"type":"string"},"expiresAt":{"type":"string"},"acceptedBy":{"type":"string"},"rejectReason":{"type":"string"},"successCount":{"type":"integer"},"failCount":{"type":"integer"},"results":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}}},"400":{"description":"Transfer request is running, not pending — The request has already been decided, cancelled or has expired.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Transfer request is running, not pending","path":"/org-management/transfer/requests/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Only the source organization can cancel a transfer request — The caller is the target org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Only the source organization can cancel a transfer request","path":"/org-management/transfer/requests/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Transfer request not found — No such request, or the caller's org is neither its source nor its target.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Transfer request not found","path":"/org-management/transfer/requests/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Organization"]}},"/ai/mcp/tools":{"get":{"operationId":"AIController_getMcpTools","summary":"List MCP tools","description":"The tools the model can call against this org's data. Read this to know what a chat turn is capable of doing — the list is the blast radius.\n\n#### Signature\n\n```http\nGET /ai/mcp/tools () -> { tools }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/mcp/execute`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"{ tools }","content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/mcp/execute":{"post":{"operationId":"AIController_executeMcpTool","summary":"Execute an MCP tool","description":"Runs one tool directly, without going through the model. Useful for testing what a tool actually does before letting a conversation call it.\n\nTools act on real org data: a write tool writes. The arguments are passed to the tool as given.\n\n#### Signature\n\n```http\nPOST /ai/mcp/execute (body) -> The tool result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Tools can modify org data.\n- A missing `toolName` fails as a server error (500), not a 400.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /ai/mcp/tools`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The tool and its arguments.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["toolName"],"properties":{"toolName":{"type":"string","example":"search_customers"},"args":{"type":"object","additionalProperties":true,"description":"`orgId` and `userId` are filled from the caller when not given.","example":{"query":"ada"}}}},"example":{"toolName":"search_customers","args":{"query":"ada"}}}}},"responses":{"201":{"description":"The tool result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/chat":{"post":{"operationId":"AIController_chat","summary":"Chat with AI","description":"A single chat turn. Files attached under `files` are processed and made available to the model, so a document can be asked about directly.\n\nTwo ways to carry history: send prior turns in `conversationHistory`, or pass a `conversationId` and let the server hold the memory. The second is cheaper — `conversationHistory` is re-sent and re-billed on every call.\n\n`availableTools` narrows what the model may call; leaving it out means the full MCP tool set is in play.\n\n#### Signature\n\n```http\nPOST /ai/chat (body) -> The chat response\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Consumes billable AI credit.\n- Tool calls can modify org data.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/agent/chat`\n- `POST /ai/agent/stream`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The chat request.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"string","description":"The user message or task.","example":"Summarise last month's refunds."},"conversationHistory":{"type":"array","description":"Prior turns. Re-sent each call, so a long history costs more.","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"example":"user"},"content":{"type":"string"}}}},"context":{"type":"object","description":"Additional context for the model. `context.agent` picks the role the assistant plays (default `chat`).","additionalProperties":true},"conversationId":{"type":"string","description":"Server-side memory key — carries history without re-sending it.","example":"CONV-4821"},"memoryTtl":{"type":"number","description":"How long that memory lives, in seconds.","example":3600},"clientMcpTools":{"type":"array","description":"Tools the client itself can run.","items":{"type":"object","additionalProperties":true}},"availableTools":{"type":"array","description":"Restrict which tools the model may call.","items":{"type":"object","additionalProperties":true}},"files":{"type":"array","description":"Documents to process alongside the message.","items":{"type":"object","properties":{"path":{"type":"string","description":"File path in storage.","example":"uploads/spec.pdf"},"name":{"type":"string","example":"spec.pdf"},"url":{"type":"string","description":"Optional.","example":"https://cdn.example.com/uploads/spec.pdf"},"size":{"type":"number","example":184320}}}}}},"examples":{"simple":{"summary":"A single question","value":{"task":"Summarise last month's refunds."}},"withMemory":{"summary":"Continuing a conversation","value":{"task":"And the month before?","conversationId":"CONV-4821","memoryTtl":3600}},"withFile":{"summary":"Ask about a document","value":{"task":"What are the payment terms?","files":[{"path":"uploads/contract.pdf","name":"contract.pdf"}]}}}}}},"responses":{"201":{"description":"The chat response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/agent/chat":{"post":{"operationId":"AIController_agentChat","summary":"Chat with an AI agent","description":"A chat turn where the caller chooses the role the assistant plays (`agentRole`, or a role named in `aiMode`) and can add system instructions (`agentInstructions`). Same file handling and memory options as `POST /ai/chat`.\n\n#### Signature\n\n```http\nPOST /ai/agent/chat (body) -> The chat response\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Consumes billable AI credit.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/chat`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The chat request, plus the role and instructions.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"string","description":"The user message or task.","example":"Summarise last month's refunds."},"conversationHistory":{"type":"array","description":"Prior turns. Re-sent each call, so a long history costs more.","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"example":"user"},"content":{"type":"string"}}}},"context":{"type":"object","description":"Additional context for the model. `context.agent` picks the role the assistant plays (default `chat`).","additionalProperties":true},"conversationId":{"type":"string","description":"Server-side memory key — carries history without re-sending it.","example":"CONV-4821"},"memoryTtl":{"type":"number","description":"How long that memory lives, in seconds.","example":3600},"clientMcpTools":{"type":"array","description":"Tools the client itself can run.","items":{"type":"object","additionalProperties":true}},"availableTools":{"type":"array","description":"Restrict which tools the model may call.","items":{"type":"object","additionalProperties":true}},"files":{"type":"array","description":"Documents to process alongside the message.","items":{"type":"object","properties":{"path":{"type":"string","description":"File path in storage.","example":"uploads/spec.pdf"},"name":{"type":"string","example":"spec.pdf"},"url":{"type":"string","description":"Optional.","example":"https://cdn.example.com/uploads/spec.pdf"},"size":{"type":"number","example":184320}}}},"agentRole":{"type":"string","description":"The role the assistant plays, by name. Defaults to `chat`.","example":"chat"},"aiMode":{"type":"string","description":"Older clients send the role here; it selects the role only when it names one, otherwise it is mode data the chat role reads.","example":"ai-agent"},"agentInstructions":{"type":"string","description":"Extra system instructions for this turn."}}},"example":{"agentRole":"chat","agentInstructions":"Answer as the support desk.","task":"Draft a reply to ticket 4821."}}}},"responses":{"201":{"description":"The chat response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/ui/ack":{"post":{"operationId":"AIController_uiActionAck","summary":"Confirm a UI action landed","description":"The client telling the server that a UI action the assistant asked for (e.g. `navigate`) actually happened. The waiting tool call is released with what the client reports, so the assistant can say \"done\" rather than \"dispatched, not confirmed\". Post it once the route is mounted or the change is made; `result` carries what the client did (e.g. ids of objects it added) back to the model.\n\n#### Signature\n\n```http\nPOST /ai/ui/ack (body) -> { received: true }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/agent/stream`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What happened.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string","description":"Defaults to `default`."},"action":{"type":"string","description":"Defaults to `navigate`.","example":"navigate"},"route":{"type":"string","example":"/crm/leads"},"view":{"type":"string"},"ok":{"type":"boolean","description":"false when it failed; anything else counts as success."},"error":{"type":"string"},"result":{"type":"object","additionalProperties":true}}},"example":{"conversationId":"CONV-4821","action":"navigate","route":"/crm/leads","ok":true}}}},"responses":{"201":{"description":"{ received: true }","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"}}},"example":{"received":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/stream/{streamId}/cancel":{"post":{"operationId":"AIController_cancelStream","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"streamId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["AI"]}},"/ai/agent/stream":{"post":{"operationId":"AIController_chatStream","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"{ streamId }","content":{"application/json":{"schema":{"type":"object","properties":{"streamId":{"type":"string"}}},"example":{"streamId":"STR-4821"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"description":"Insufficient balance to use AI services — The org has no subscription and not enough balance for the minimum estimated cost.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance to use AI services","required":0.01,"available":0,"action":"add_credits","billingUrl":"/billing"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"],"summary":"Start a streaming chat","description":"Starts a streaming response and returns a **stream id** — it does not return the text. Connect to `GET /ai/stream/{streamId}` to read it as it arrives.\n\nThe two-step shape exists because the generation outlives the request; a client that only calls this and never connects has still paid for the generation.\n\nWith a `conversationId`, the history is the **server's**: the last 20 messages of that conversation replace any `conversationHistory` sent. The user message and the reply are saved to the conversation. Tool calls the assistant makes run as the caller (their bearer token), so their own permissions apply.\n\nThe org needs a subscription or a positive balance to start.\n\n#### Signature\n\n```http\nPOST /ai/agent/stream (body) -> { streamId }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Consumes billable AI credit.\n- Returns a stream id, not the response.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `402` | INSUFFICIENT_BALANCE | Insufficient balance to use AI services | The org has no subscription and not enough balance for the minimum estimated cost. | Add credits (billingUrl) and retry. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /ai/stream/{streamId}`","requestBody":{"description":"The chat request.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"string","description":"The user message or task.","example":"Summarise last month's refunds."},"conversationHistory":{"type":"array","description":"Prior turns. Re-sent each call, so a long history costs more.","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"example":"user"},"content":{"type":"string"}}}},"context":{"type":"object","description":"Additional context for the model. `context.agent` picks the role the assistant plays (default `chat`).","additionalProperties":true},"conversationId":{"type":"string","description":"Server-side memory key — carries history without re-sending it.","example":"CONV-4821"},"memoryTtl":{"type":"number","description":"How long that memory lives, in seconds.","example":3600},"clientMcpTools":{"type":"array","description":"Tools the client itself can run.","items":{"type":"object","additionalProperties":true}},"availableTools":{"type":"array","description":"Restrict which tools the model may call.","items":{"type":"object","additionalProperties":true}},"files":{"type":"array","description":"Documents to process alongside the message.","items":{"type":"object","properties":{"path":{"type":"string","description":"File path in storage.","example":"uploads/spec.pdf"},"name":{"type":"string","example":"spec.pdf"},"url":{"type":"string","description":"Optional.","example":"https://cdn.example.com/uploads/spec.pdf"},"size":{"type":"number","example":184320}}}},"agentRole":{"type":"string","description":"The role the assistant plays, by name. Defaults to `chat`.","example":"chat"},"aiMode":{"type":"string","description":"Older clients send the role here; it selects the role only when it names one, otherwise it is mode data the chat role reads.","example":"ai-agent"},"agentInstructions":{"type":"string","description":"Extra system instructions for this turn."},"images":{"type":"array","description":"Images to send to the model with the message.","items":{"type":"object","additionalProperties":true}},"settings":{"type":"object","additionalProperties":true,"description":"Model options passed through (e.g. model, temperature)."}}},"example":{"task":"Write a summary of this quarter.","conversationId":"CONV-4821"}}}}}},"/ai/stream/{streamId}":{"get":{"operationId":"AIController_streamEvents","summary":"Read a stream","description":"A **Server-Sent Events** connection to a stream started by `POST /ai/agent/stream`. The first event is `data` with `{ type: \"status\", status: \"connected\" }`; chunks already produced are then **replayed**, so a client that reconnects does not lose the start. Events: `data` (a chunk as JSON), `end` (done), `error` (`{ message }` — the provider's own reason when it refused).\n\nAn unknown stream id, or a missing `orgid` header, answers with a single `error` event and closes — not an HTTP error status.\n\n#### Signature\n\n```http\nGET /ai/stream/{streamId} (streamId: string) -> The event stream\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/agent/stream`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"streamId","required":true,"in":"path","description":"Stream id from the stream start call.","schema":{"type":"string"},"example":"STR-4821"}],"responses":{"200":{"description":"The event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/models/{purpose}":{"get":{"operationId":"AIController_getModels","summary":"Models offered for a purpose","description":"The models a picker should offer for `purpose` (`image`, `video`, `completion`, `embedding`, `transcription`, `speech`), read from the platform's model registry. Only models the provider currently supports are listed; retired or deprecated ones are left out, and so are providers this org cannot reach (no integration of its own and no platform access) — those are named in `unavailable`. Send the chosen `id` and its `provider` to the generate endpoint. When the registry changes, this list changes with it.\n\n#### Signature\n\n```http\nGET /ai/models/{purpose} (purpose: string) -> { default: { id, provider }, models: [{ id, label, provider, default, aspectRatios?, sizes?, maxImages? }], unavailable: [provider] }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | BAD_REQUEST | Unknown model purpose <purpose> | An unknown purpose. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/generate/image`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"purpose","required":true,"in":"path","schema":{"type":"string"},"description":"What the model is for.","example":"image"}],"requestBody":{"required":true,"description":"Image generation request","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"The text prompt for image generation"},"images":{"type":"array","description":"Reference images for guided generation","items":{"type":"object","properties":{"path":{"type":"string","description":"File path in storage"},"url":{"type":"string","description":"Public URL of the image"}}}},"mask":{"type":"object","description":"Mask image for editing (transparent areas will be replaced)","properties":{"path":{"type":"string","description":"File path in storage"},"url":{"type":"string","description":"Public URL of the mask"}}},"n":{"type":"number","description":"Number of images to generate (default: 1)"},"variations":{"type":"number","description":"Alias for \"n\""},"size":{"type":"string","description":"Image size (e.g., \"1024x1024\")"},"quality":{"type":"string","description":"Image quality (e.g., \"standard\", \"hd\")"},"style":{"type":"string","description":"Image style (e.g., \"vivid\", \"natural\")"},"provider":{"type":"string","description":"AI provider to use (optional)"}},"required":["prompt"]}}}},"responses":{"200":{"description":"{ default: { id, provider }, models: [{ id, label, provider, default, aspectRatios?, sizes?, maxImages? }], unavailable: [provider] }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"default":{"id":"gemini-3-pro-image","provider":"GoogleGeminiProvider"},"models":[{"id":"gpt-image-2.5-sunburst","label":"GPT Image 2.5 Sunburst","provider":"OpenAIProvider","default":true}]}}}},"400":{"description":"Unknown model purpose <purpose> — An unknown purpose.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Unknown model purpose <purpose>","path":"/ai/models/{purpose}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/generate/image":{"post":{"operationId":"AIController_generateImage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The provider response plus `files` (the images saved to the org's storage) and a `message`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"<the provider's reason> — Any failure — including \"No AI provider found\" and a provider that does not make images — comes back as a 400 carrying the reason.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"<the provider's reason>","path":"/ai/generate/image","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"],"summary":"Generate an image","description":"One endpoint covering three modes, chosen by what is in the body:\n\n- **From a prompt** — `prompt` alone creates a new image.\n- **With references** — `prompt` plus `images` guides generation from existing pictures.\n- **Inpainting** — `prompt` plus an image and a `mask` edits the masked region.\n\nThis replaces the deprecated variations and edit endpoints; new code should use this one.\n\n#### Signature\n\n```http\nPOST /ai/generate/image (body) -> The provider response plus `files` (the images saved to the org's storage) and a `message`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Consumes billable AI credit.\n- Each image in `n` is billed separately.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | IMAGE_GENERATION_FAILED | <the provider's reason> | Any failure — including \"No AI provider found\" and a provider that does not make images — comes back as a 400 carrying the reason. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/generate/video`","requestBody":{"description":"The generation request.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"The text prompt.","example":"A cola bottle on a marble counter, studio lighting"},"images":{"type":"array","description":"Reference images for guided generation.","items":{"type":"object","properties":{"path":{"type":"string","example":"uploads/ref.jpg"},"url":{"type":"string"}}}},"mask":{"type":"object","description":"Mask for inpainting — the region to replace.","additionalProperties":true},"size":{"type":"string","example":"1024x1024"},"n":{"type":"integer","description":"How many to generate (default 1). Each one is billed.","example":1},"variations":{"type":"integer","description":"Alias for `n`."},"quality":{"type":"string","example":"hd"},"style":{"type":"string","example":"natural"},"provider":{"type":"string","description":"Which configured AI provider to use; default is the platform's image provider."}}},"examples":{"fromPrompt":{"summary":"From a prompt","value":{"prompt":"A cola bottle on a marble counter, studio lighting","size":"1024x1024"}},"withReference":{"summary":"Guided by a reference image","value":{"prompt":"Same bottle, on a wooden table","images":[{"path":"uploads/ref.jpg"}]}},"inpaint":{"summary":"Edit a masked region","value":{"prompt":"Replace the label with a plain white one","images":[{"path":"uploads/bottle.jpg"}],"mask":{"path":"uploads/bottle-mask.png"}}}}}}}}},"/ai/generate/image/variations":{"post":{"operationId":"AIController_generateImageVariations","summary":"Generate image variations (deprecated)","description":"Deprecated. Use `POST /ai/generate/image` with `images` as references — it covers this and more. Kept for existing callers.\n\n#### Signature\n\n```http\nPOST /ai/generate/image/variations (body) -> The variations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Deprecated.\n- Consumes billable AI credit.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/generate/image`","deprecated":true,"parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The request.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"The reference image (becomes `images: [{ path }]`)."},"images":{"type":"array","items":{"type":"object","additionalProperties":true}},"prompt":{"type":"string"},"n":{"type":"integer"}}},"example":{"path":"uploads/ref.jpg","n":2}}}},"responses":{"201":{"description":"The variations","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/generate/image/edit":{"post":{"operationId":"AIController_editImage","summary":"Edit an image (deprecated)","description":"Deprecated. Use `POST /ai/generate/image` with a `mask` for inpainting. Kept for existing callers.\n\n#### Signature\n\n```http\nPOST /ai/generate/image/edit (body) -> The edited image\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Deprecated.\n- Consumes billable AI credit.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/generate/image`","deprecated":true,"parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The request.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string"},"imagePath":{"type":"string","description":"Becomes `images: [{ path }]`."},"maskPath":{"type":"string","description":"Becomes `mask: { path }`."},"images":{"type":"array","items":{"type":"object","additionalProperties":true}},"mask":{"type":"object","additionalProperties":true}}},"example":{"prompt":"Plain white label","imagePath":"uploads/bottle.jpg","maskPath":"uploads/bottle-mask.png"}}}},"responses":{"201":{"description":"The edited image","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/ai/generate/video":{"post":{"operationId":"AIController_generateVideo","summary":"Generate a video","description":"Generates video from a prompt with a provider that supports video. The request waits for the result, which is slow — considerably slower and more expensive than an image. Each video returned is saved to the org's storage.\n\n#### Signature\n\n```http\nPOST /ai/generate/video (body) -> The provider response plus `files` (the saved videos) and a `message`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Consumes billable AI credit.\n- Slow and comparatively expensive.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | VIDEO_GENERATION_FAILED | <the provider's reason> | No AI provider, a provider that does not support video (\"Provider <name> does not support video generation\"), or the provider refused. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai/generate/image`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The generation request, passed to the provider.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"provider":{"type":"string","description":"A configured provider that makes video."}},"additionalProperties":true},"example":{"prompt":"A slow pan across a city skyline at dusk"}}}},"responses":{"201":{"description":"The provider response plus `files` (the saved videos) and a `message`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"<the provider's reason> — No AI provider, a provider that does not support video (\"Provider <name> does not support video generation\"), or the provider refused.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"<the provider's reason>","path":"/ai/generate/video","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI"]}},"/client-data/dashboard":{"get":{"operationId":"ClientAccountController_getClientDashboard","summary":"Get my dashboard","description":"A consolidated view for the signed-in customer — recent orders, upcoming reservations, open tickets and unread messages in one call, so an account home page does not need six requests.\n\n#### Signature\n\n```http\nGET /client-data/dashboard () -> The dashboard\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/all`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The dashboard","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/dashboard","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/shared-accounts/{accountId}/members":{"get":{"operationId":"ClientAccountController_getSharedAccountMembers","summary":"List shared account members","description":"Managers only. Everyone associated with the account, suspended members included. A member whose customer record is gone is kept (`missing: true`) so it can still be removed.\n\n#### Signature\n\n```http\nGET /client-data/shared-accounts/{accountId}/members (accountId: string) -> [{ associationId, customerId, name, email, role, status, missing }]\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `403` | NOT_MANAGER | You do not manage this account | The caller has no active manager association with this account. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"accountId","required":true,"in":"path","description":"Shared account id (the account `customer` record).","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"[{ associationId, customerId, name, email, role, status, missing }]","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/shared-accounts/{accountId}/members","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"You do not manage this account — The caller has no active manager association with this account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You do not manage this account","path":"/client-data/shared-accounts/{accountId}/members","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/shared-accounts/{accountId}/orders":{"get":{"operationId":"ClientAccountController_getSharedAccountOrders","summary":"List shared account orders","description":"Managers only. Orders placed on the account by any member.\n\n#### Signature\n\n```http\nGET /client-data/shared-accounts/{accountId}/orders (accountId: string, page?: integer, limit?: integer) -> Paged orders\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `403` | NOT_MANAGER | You do not manage this account | The caller has no active manager association with this account. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"accountId","required":true,"in":"path","description":"Shared account id (the account `customer` record).","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"Rows per page.","example":20}],"responses":{"200":{"description":"Paged orders","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/shared-accounts/{accountId}/orders","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"You do not manage this account — The caller has no active manager association with this account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You do not manage this account","path":"/client-data/shared-accounts/{accountId}/orders","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/shared-accounts/{accountId}/members/{associationId}":{"put":{"operationId":"ClientAccountController_updateSharedAccountMember","summary":"Change a shared account member","description":"Managers only. Changes a member's `role` (manager | buyer) or `status` (active | suspended). Suspending keeps the association so their past orders still explain themselves. The account must keep at least one active manager.\n\n#### Signature\n\n```http\nPUT /client-data/shared-accounts/{accountId}/members/{associationId} (accountId: string, associationId: string, body) -> The association\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `403` | NOT_MANAGER | You do not manage this account | The caller has no active manager association with this account. | — |\n| `404` | MEMBER_NOT_FOUND | Member not found on this account | The association does not exist or belongs to another account. | — |\n| `400` | LAST_MANAGER | The account must keep at least one manager | The change would leave no active manager. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"associationId","required":true,"in":"path","schema":{"type":"string"},"description":"customer_association sk."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["manager","buyer"]},"status":{"type":"string","enum":["active","suspended"]}}},"example":{"status":"suspended"}}}},"responses":{"200":{"description":"The association","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The account must keep at least one manager — The change would leave no active manager.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The account must keep at least one manager","path":"/client-data/shared-accounts/{accountId}/members/{associationId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/shared-accounts/{accountId}/members/{associationId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"You do not manage this account — The caller has no active manager association with this account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You do not manage this account","path":"/client-data/shared-accounts/{accountId}/members/{associationId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"Member not found on this account — The association does not exist or belongs to another account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Member not found on this account","path":"/client-data/shared-accounts/{accountId}/members/{associationId}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/shared-accounts/{accountId}/invites":{"post":{"operationId":"ClientAccountController_inviteToSharedAccount","summary":"Invite someone to a shared account","description":"Managers only. An email that already belongs to a customer is associated straight away (a suspended member is reinstated) and told by email; a new email gets a pending invitation with a sign-up link on the storefront the manager is on (`x-client-host`). Resending to a pending invite re-sends it. `role` defaults to buyer.\n\n#### Signature\n\n```http\nPOST /client-data/shared-accounts/{accountId}/invites (accountId: string, body) -> `{ added, reinstated, customerId }` or `{ invited, resent, email }`, plus the assembled `account`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `403` | NOT_MANAGER | You do not manage this account | The caller has no active manager association with this account. | — |\n| `400` | EMAIL_REQUIRED | A valid email is required | `email` missing or has no @. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"accountId","required":true,"in":"path","schema":{"type":"string"},"description":"Shared account id (the account `customer` record).","example":"66f1a2b3c4d5e6f708192a3b"},{"name":"x-client-host","required":false,"in":"header","schema":{"type":"string"},"description":"The storefront host the invitation link points at."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"role":{"type":"string","enum":["manager","buyer"]},"message":{"type":"string"}}},"example":{"email":"buyer@acme.com","role":"buyer","message":"Welcome to the Acme account"}}}},"responses":{"201":{"description":"`{ added, reinstated, customerId }` or `{ invited, resent, email }`, plus the assembled `account`","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"A valid email is required — `email` missing or has no @.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A valid email is required","path":"/client-data/shared-accounts/{accountId}/invites","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/shared-accounts/{accountId}/invites","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"You do not manage this account — The caller has no active manager association with this account.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"You do not manage this account","path":"/client-data/shared-accounts/{accountId}/invites","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/shared-accounts/invites/validate/{invitationToken}":{"get":{"operationId":"ClientAccountController_validateSharedAccountInvitation","summary":"Check a shared account invitation","description":"Public. Validates an invitation link before the sign-up form is shown. An expired link is marked expired and refused.\n\n#### Signature\n\n```http\nGET /client-data/shared-accounts/invites/validate/{invitationToken} (invitationToken: string) -> { email, firstName, lastName, invitedByName, message, accountName }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INVITE_INVALID | Invalid or expired invitation | No pending invitation has that token. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"invitationToken","required":true,"in":"path","schema":{"type":"string"},"description":"Token from the invitation email."}],"responses":{"200":{"description":"{ email, firstName, lastName, invitedByName, message, accountName }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid or expired invitation — No pending invitation has that token.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid or expired invitation","path":"/client-data/shared-accounts/invites/validate/{invitationToken}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/shared-accounts/invites/accept/{invitationToken}":{"post":{"operationId":"ClientAccountController_acceptSharedAccountInvitation","summary":"Accept a shared account invitation","description":"Once the invitee is signed in (just signed up through the link, or already had an account), associates them with the account named on the invitation with its role.\n\n#### Signature\n\n```http\nPOST /client-data/shared-accounts/invites/accept/{invitationToken} (invitationToken: string) -> { accepted: true, accountId, role }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | NOT_SIGNED_IN | Not signed in | No signed-in customer. | — |\n| `400` | INVITE_INVALID | Invalid or expired invitation | No pending invitation has that token. | — |\n| `403` | WRONG_EMAIL | This invitation was sent to a different email | The signed-in email is not the invited one. | — |\n\nPlus the standard platform errors: `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"invitationToken","required":true,"in":"path","schema":{"type":"string"},"description":"Token from the invitation email."}],"responses":{"201":{"description":"{ accepted: true, accountId, role }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid or expired invitation — No pending invitation has that token.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Invalid or expired invitation","path":"/client-data/shared-accounts/invites/accept/{invitationToken}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Not signed in — No signed-in customer.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Not signed in","path":"/client-data/shared-accounts/invites/accept/{invitationToken}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"description":"This invitation was sent to a different email — The signed-in email is not the invited one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This invitation was sent to a different email","path":"/client-data/shared-accounts/invites/accept/{invitationToken}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/profile":{"get":{"operationId":"ClientAccountController_getProfile","summary":"Get my profile","description":"The signed-in customer's profile.\n\n#### Signature\n\n```http\nGET /client-data/profile () -> The profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /client-data/profile`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/profile","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"put":{"operationId":"ClientAccountController_updateProfile","summary":"Update my profile","description":"Updates the customer's own profile. Changing an email here does not re-verify it — use the verification endpoints if the new address needs proving.\n\n#### Signature\n\n```http\nPUT /client-data/profile (body) -> The updated profile\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/verification/email/send`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"firstName":"Ada","lastName":"Lovelace","phone":"+15551234567"}}}},"responses":{"200":{"description":"The updated profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/profile","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/orders":{"get":{"operationId":"ClientAccountController_getOrders","summary":"Get my orders","description":"The customer's order history, paged.\n\n#### Signature\n\n```http\nGET /client-data/orders (page?: integer, limit?: integer, status?: string, sortBy?: string, sortOrder?: string) -> Orders\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/orders/{orderId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"Rows per page.","example":20},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Order status."},{"name":"sortBy","required":false,"in":"query","schema":{"type":"string"}},{"name":"sortOrder","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Orders","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/orders","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/forms":{"get":{"operationId":"ClientAccountController_getForms","summary":"Get my forms","description":"Forms this customer has submitted and any still waiting on them, matched on their email. A `pending` row is a link that was asked for and not used yet (`submittedAt` null).\n\n#### Signature\n\n```http\nGET /client-data/forms (page?: integer, limit?: integer, status?: string) -> { data, total, page, pageSize }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"Rows per page.","example":20},{"name":"status","required":false,"in":"query","schema":{"type":"string"},"description":"Submission status, e.g. `pending`."}],"responses":{"200":{"description":"{ data, total, page, pageSize }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/forms","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/orders/{orderId}":{"get":{"operationId":"ClientAccountController_getOrder","summary":"Get one of my orders","description":"Fetches one of the customer's own orders. An order belonging to someone else is not returned.\n\n#### Signature\n\n```http\nGET /client-data/orders/{orderId} (orderId: string) -> The order\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/transactions`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"orderId","required":true,"in":"path","description":"Order id or number.","schema":{"type":"string"},"example":"A7K2M9QX4"}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/orders/{orderId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/reservations":{"get":{"operationId":"ClientAccountController_getReservations","summary":"Get my reservations","description":"The customer's bookings, past and upcoming.\n\n#### Signature\n\n```http\nGET /client-data/reservations () -> Reservations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/reservations`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Reservations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/reservations","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"post":{"operationId":"ClientAccountController_createReservation","summary":"Make a reservation","description":"Books a reservation for the customer.\n\n#### Signature\n\n```http\nPOST /client-data/reservations (body) -> The created reservation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/reservations/available-slots`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-client-host","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"For a timed service: use the selected definition id and service name, exact startTime/endTime returned by availability, and answers keyed by the configured form schema. The bearer session supplies customer identity. Replace the illustrative id, service, date and form answers with your own configuration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reservationDefinitionId":"6acb4561d685f653775b8772","service":"Room planning","startTime":"2026-10-22T16:00:00.000Z","endTime":"2026-10-22T16:30:00.000Z","form":{"projectType":"Single room","brief":"Plan a reading corner with accessible shelving.","contactConsent":true}}}}},"responses":{"201":{"description":"The created reservation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/reservations","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"put":{"operationId":"ClientAccountController_updateReservation","summary":"Update my reservation","description":"Reschedules or amends one of the customer's reservations. Availability is not re-checked automatically — confirm the new slot is free first.\n\n#### Signature\n\n```http\nPUT /client-data/reservations (body) -> The updated reservation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /client-data/reservations/{reservationId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"description":"The reservation to update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reservationId":"RES-4821","startDate":"2026-10-06T10:00:00.000Z"}}}},"responses":{"200":{"description":"The updated reservation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/reservations","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/reservations/{reservationId}":{"get":{"operationId":"ClientAccountController_getReservation","summary":"Get one of my reservations","description":"Fetches one of the customer's own reservations.\n\n#### Signature\n\n```http\nGET /client-data/reservations/{reservationId} (reservationId: string) -> The reservation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /client-data/reservations`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"reservationId","required":true,"in":"path","description":"Reservation id.","schema":{"type":"string"},"example":"RES-4821"}],"responses":{"200":{"description":"The reservation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/reservations/{reservationId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"delete":{"operationId":"ClientAccountController_cancelReservation","summary":"Cancel my reservation","description":"Cancels one of the customer's reservations, freeing the slot.\n\n#### Signature\n\n```http\nDELETE /client-data/reservations/{reservationId} (reservationId: string) -> Cancellation result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/reservations`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}},{"name":"reservationId","required":true,"in":"path","description":"Reservation id.","schema":{"type":"string"},"example":"RES-4821"}],"responses":{"200":{"description":"Cancellation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/reservations/{reservationId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/reservations/{reservationId}/card/setup":{"post":{"operationId":"ClientAccountController_bookingCardSetup","summary":"Keep a card on a booking: start","description":"A Stripe SetupIntent for the booking's client ({ clientSecret, setupIntentId, publishableKey, customerId }). The client's own booking, or a guest's with body { email, number }.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"reservationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Client Account"]}},"/client-data/reservations/{reservationId}/card":{"post":{"operationId":"ClientAccountController_bookingCardSave","summary":"Keep a card on a booking","description":"Body: { setupIntentId } (confirmed) or { paymentMethodId } (one of my saved cards), plus { email, number } for a guest. The no-show / late-cancel fee and the check-out balance are charged to it, with a receipt. Returns { card: { brand, last4, expMonth, expYear } }.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"reservationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Client Account"]}},"/client-data/reservations/available-slots":{"post":{"operationId":"ClientAccountController_getAvailableSlots","summary":"Find available slots","description":"Computes bookable slots for the selected reservation definition and configured service. Slots are calculated, not held — one shown here can be taken before the customer books it.\n\n#### Signature\n\n```http\nPOST /client-data/reservations/available-slots (body) -> Selected reservationDefinition and service with a slots array; a closed or inactive day has an empty slots array.\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- No hold is placed — handle a conflict on booking.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/reservations`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to check availability for.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reservationDefinitionId":"6acb4561d685f653775b8772","serviceName":"Room planning","serviceDate":"2026-10-22"}}}},"responses":{"201":{"description":"Selected reservationDefinition and service with a slots array; a closed or inactive day has an empty slots array.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/reservations/available-slots","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/tickets":{"get":{"operationId":"ClientAccountController_getTickets","summary":"Get my support tickets","description":"The customer's own support tickets.\n\n#### Signature\n\n```http\nGET /client-data/tickets (status?: string, enrich?: string) -> Tickets\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/tickets`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"status","required":false,"in":"query","schema":{"type":"string"}},{"name":"enrich","required":false,"in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Include linked records."}],"responses":{"200":{"description":"Tickets","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/tickets","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"post":{"operationId":"ClientAccountController_createTicket","summary":"Raise a support ticket","description":"Creates a support ticket as the signed-in customer.\n\n#### Signature\n\n```http\nPOST /client-data/tickets (body) -> The created ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/tickets/with-attachments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The ticket.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"title":"Order never arrived","description":"Tracking has not updated in a week","orderNumber":"A7K2M9QX4"}}}},"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/tickets","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"put":{"operationId":"ClientAccountController_updateTicket","summary":"Update my ticket","description":"Adds to or amends one of the customer's tickets — replying, or supplying detail that was asked for.\n\n#### Signature\n\n```http\nPUT /client-data/tickets (body) -> The updated ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/tickets/{ticketNumber}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The ticket update.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ticketNumber":"TKT-4821","message":"Tracking updated today — please close this"}}}},"responses":{"200":{"description":"The updated ticket","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/tickets","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/tickets/{ticketNumber}":{"get":{"operationId":"ClientAccountController_getTicket","summary":"Get one of my tickets","description":"Fetches one ticket with its customer-visible conversation. Internal staff comments are not included.\n\n#### Signature\n\n```http\nGET /client-data/tickets/{ticketNumber} (ticketNumber: string) -> The ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Only the customer-facing thread is returned — internal comments stay internal.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /client-data/tickets`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"ticketNumber","required":true,"in":"path","description":"Ticket number.","schema":{"type":"string"},"example":"TKT-4821"}],"responses":{"200":{"description":"The ticket","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/tickets/{ticketNumber}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/tickets/with-attachments":{"post":{"operationId":"ClientAccountController_createTicketWithAttachments","summary":"Raise a ticket with attachments","description":"Creates a ticket and uploads supporting files in one multipart request — screenshots and photos, which is what most support issues need.\n\n#### Signature\n\n```http\nPOST /client-data/tickets/with-attachments (body) -> The created ticket\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/tickets`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"Multipart form with the ticket fields and files.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"files":{"type":"array","items":{"type":"string","format":"binary"}}}}}}},"responses":{"201":{"description":"The created ticket","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/tickets/with-attachments","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/messages":{"get":{"operationId":"ClientAccountController_getMessages","summary":"Get my messages","description":"Messages sent to and from the customer.\n\n#### Signature\n\n```http\nGET /client-data/messages (page?: integer, pageSize?: integer, sort?: string, sortType?: string, conversationWith?: string) -> Messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/conversations`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"conversationWith","required":false,"in":"query","schema":{"type":"string"},"description":"Only the thread with this address."},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":20},{"name":"sort","required":false,"in":"query","schema":{"type":"string"},"description":"Field to sort by."},{"name":"sortType","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/messages","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"post":{"operationId":"ClientAccountController_sendMessage","summary":"Send a message","description":"Sends a message as the customer.\n\n#### Signature\n\n```http\nPOST /client-data/messages (send?: boolean, body) -> The sent message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/messages`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"send","required":false,"in":"query","schema":{"type":"boolean"},"description":"true to send immediately; otherwise saved as a draft."}],"requestBody":{"description":"The message.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"subject":"Question about delivery","body":"When do you ship to Ireland?"}}}},"responses":{"201":{"description":"The sent message","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/messages","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/conversations":{"get":{"operationId":"ClientAccountController_getConversations","summary":"Get my conversations","description":"The customer's messages grouped into threads — the inbox list view.\n\n#### Signature\n\n```http\nGET /client-data/conversations () -> Conversations\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/messages`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Conversations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/conversations","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/messages/{messageId}/status/{status}":{"put":{"operationId":"ClientAccountController_updateMessageStatus","summary":"Set a message status","description":"Marks one of the customer's messages read, archived or similar. Both values are path segments rather than a body.\n\n#### Signature\n\n```http\nPUT /client-data/messages/{messageId}/status/{status} (messageId: string, status: string) -> The updated message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/messages`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"messageId","required":true,"in":"path","description":"Message id.","schema":{"type":"string"},"example":"MSG-4821"},{"name":"status","required":true,"in":"path","description":"New status.","schema":{"type":"string"},"example":"read"}],"responses":{"200":{"description":"The updated message","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/messages/{messageId}/status/{status}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/notifications":{"get":{"operationId":"ClientAccountController_getNotifications","summary":"Get my notifications","description":"Notifications for the signed-in customer.\n\n#### Signature\n\n```http\nGET /client-data/notifications (unreadOnly?: boolean) -> Notifications\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/notifications/push-token`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"unreadOnly","required":false,"in":"query","schema":{"type":"boolean"},"description":"true for unread notifications only."}],"responses":{"200":{"description":"Notifications","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/notifications","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/notifications/push-token":{"post":{"operationId":"ClientAccountController_savePushToken","summary":"Register a push token","description":"Registers a device for push notifications. Call it on every app launch — platform tokens rotate, and a stale one silently stops delivering.\n\n#### Signature\n\n```http\nPOST /client-data/notifications/push-token (body) -> The registered token\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/notifications`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The device token.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"fcm_dGhpcyBpcyBhIHRva2Vu","platform":"ios"}}}},"responses":{"201":{"description":"The registered token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/notifications/push-token","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/payment-methods":{"get":{"operationId":"ClientAccountController_getPaymentMethods","summary":"Get my payment methods","description":"The customer's saved payment methods. Card details are masked — expect a last-four, never a full number.\n\n#### Signature\n\n```http\nGET /client-data/payment-methods () -> Payment methods\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/payment-methods`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Payment methods","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/payment-methods","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"post":{"operationId":"ClientAccountController_addPaymentMethod","summary":"Add a payment method","description":"Saves a payment method for the customer. Send a gateway token rather than raw card details — the card should reach the payment provider, not this API.\n\n#### Signature\n\n```http\nPOST /client-data/payment-methods (body) -> The saved method\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Tokenise on the client. Raw card data here would pull the platform into PCI scope.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /client-data/payment-methods/{paymentMethodId}/default`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The payment method.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"token":"pm_1PabcXYZ","gateway":"stripe","isDefault":true}}}},"responses":{"201":{"description":"The saved method","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/payment-methods","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/payment-methods/{paymentMethodId}":{"delete":{"operationId":"ClientAccountController_removePaymentMethod","summary":"Remove a payment method","description":"Deletes a saved payment method. Any subscription billing against it will fail at its next renewal — check before removing the only method on file.\n\n#### Signature\n\n```http\nDELETE /client-data/payment-methods/{paymentMethodId} (paymentMethodId: string) -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Recurring charges using it will start failing.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/payment-methods`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"paymentMethodId","required":true,"in":"path","description":"Payment method id.","schema":{"type":"string"},"example":"PM-4821"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/payment-methods/{paymentMethodId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/payment-methods/{paymentMethodId}/default":{"put":{"operationId":"ClientAccountController_setDefaultPaymentMethod","summary":"Set the default payment method","description":"Makes one method the default for future purchases and renewals.\n\n#### Signature\n\n```http\nPUT /client-data/payment-methods/{paymentMethodId}/default (paymentMethodId: string) -> The updated method\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/payment-methods`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"paymentMethodId","required":true,"in":"path","description":"Payment method id.","schema":{"type":"string"},"example":"PM-4821"}],"responses":{"200":{"description":"The updated method","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/payment-methods/{paymentMethodId}/default","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/addresses":{"get":{"operationId":"ClientAccountController_getAddresses","summary":"Get my addresses","description":"The customer's saved addresses.\n\n#### Signature\n\n```http\nGET /client-data/addresses () -> Addresses\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/addresses`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Addresses","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/addresses","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"post":{"operationId":"ClientAccountController_saveAddress","summary":"Add an address","description":"Saves an address for the customer.\n\n#### Signature\n\n```http\nPOST /client-data/addresses (body) -> The saved address\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/addresses/autocomplete`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The address.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"line1":"12 Ada Way","city":"London","postcode":"E1 6AN","country":"GB","isDefault":true}}}},"responses":{"201":{"description":"The saved address","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/addresses","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/addresses/{addressId}":{"delete":{"operationId":"ClientAccountController_deleteAddress","summary":"Remove an address","description":"Deletes a saved address. Orders already placed keep the address they shipped to.\n\n#### Signature\n\n```http\nDELETE /client-data/addresses/{addressId} (addressId: string) -> Removal result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/addresses`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"addressId","required":true,"in":"path","description":"Address id.","schema":{"type":"string"},"example":"ADR-4821"}],"responses":{"200":{"description":"Removal result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/addresses/{addressId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/addresses/autocomplete":{"post":{"operationId":"ClientAccountController_getAddressAutocomplete","summary":"Autocomplete an address","description":"Returns address suggestions as the customer types. Backed by a billable maps provider — debounce it rather than calling per keystroke.\n\n#### Signature\n\n```http\nPOST /client-data/addresses/autocomplete (body) -> Address suggestions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/addresses/place/{placeId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What has been typed.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"input":"12 Ada W","sessiontoken":"b1f2c3d4"}}}},"responses":{"201":{"description":"Address suggestions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/addresses/autocomplete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/addresses/place/{placeId}":{"get":{"operationId":"ClientAccountController_getPlaceDetails","summary":"Get address details for a place","description":"Expands a place id from autocomplete into a full structured address.\n\n#### Signature\n\n```http\nGET /client-data/addresses/place/{placeId} (placeId: string) -> The structured address\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `400` | PLACE_ID_REQUIRED | place_id is required | The place id is missing. | Take it from an autocomplete suggestion. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/addresses/autocomplete`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"placeId","required":true,"in":"path","description":"Place id from an autocomplete suggestion.","schema":{"type":"string"},"example":"ChIJd8BlQ2BZwokRAFUEcm_qrcA"}],"responses":{"200":{"description":"The structured address","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"place_id is required — The place id is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"place_id is required","path":"/client-data/addresses/place/{placeId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/addresses/place/{placeId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/wishlist":{"get":{"operationId":"ClientAccountController_getWishlist","summary":"Get my wishlist","description":"The customer's saved products.\n\n#### Signature\n\n```http\nGET /client-data/wishlist () -> Wishlist\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/wishlist/{productId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Wishlist","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/wishlist","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"post":{"operationId":"ClientAccountController_createWishlist","summary":"Create a wishlist","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The created wishlist","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/wishlist","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"],"description":"Creates a named wishlist, for customers keeping more than one list.\n\n#### Signature\n\n```http\nPOST /client-data/wishlist (body) -> The created wishlist\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /client-data/wishlist-list/{wishlistId}`","requestBody":{"description":"The wishlist to create.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"Christmas"}}}}}},"/client-data/wishlist/{productId}":{"post":{"operationId":"ClientAccountController_addToWishlist","summary":"Add a product to my wishlist","description":"Saves a product to the wishlist. The product must carry a SKU — that is what the wishlist keys on.\n\n#### Signature\n\n```http\nPOST /client-data/wishlist/{productId} (productId: string, body) -> The updated wishlist\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `400` | SKU_REQUIRED | product.sku is required | The product has no SKU. | Wishlist entries are keyed on SKU. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /client-data/wishlist/{productId}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"productId","required":true,"in":"path","description":"Product id or SKU.","schema":{"type":"string"},"example":"DRK-COLA-330"}],"responses":{"201":{"description":"The updated wishlist","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"product.sku is required — The product has no SKU.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"product.sku is required","path":"/client-data/wishlist/{productId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/wishlist/{productId}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"],"requestBody":{"description":"Optional product detail.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"product":{"sku":"DRK-COLA-330"}}}}}},"delete":{"operationId":"ClientAccountController_removeFromWishlist","summary":"Remove a product from my wishlist","description":"Removes a product from the wishlist.\n\n#### Signature\n\n```http\nDELETE /client-data/wishlist/{productId} (productId: string, wishlistId?: string) -> The updated wishlist\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `400` | SKU_REQUIRED | sku is required | No SKU was resolved from the path. | Supply the product SKU. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/wishlist`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"productId","required":true,"in":"path","description":"Product id or SKU.","schema":{"type":"string"},"example":"DRK-COLA-330"},{"name":"wishlistId","required":false,"in":"query","schema":{"type":"string"},"description":"A named wishlist; omit for the default one."}],"responses":{"200":{"description":"The updated wishlist","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"sku is required — No SKU was resolved from the path.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"sku is required","path":"/client-data/wishlist/{productId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/wishlist/{productId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/wishlist-list/{wishlistId}":{"delete":{"operationId":"ClientAccountController_deleteWishlist","summary":"Delete a wishlist","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"wishlistId","required":true,"in":"path","schema":{"type":"string"},"description":"Wishlist id.","example":"WL-4821"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Not your wishlist — The wishlist belongs to another customer.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Not your wishlist","path":"/client-data/wishlist-list/{wishlistId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/wishlist-list/{wishlistId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Wishlist not found — No wishlist has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Wishlist not found","path":"/client-data/wishlist-list/{wishlistId}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"],"description":"Deletes one of the customer's named wishlists. Ownership is checked — deleting someone else's list is refused with `Not your wishlist`.\n\n#### Signature\n\n```http\nDELETE /client-data/wishlist-list/{wishlistId} (wishlistId: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n| `404` | WISHLIST_NOT_FOUND | Wishlist not found | No wishlist has that id. | Check the id. |\n| `400` | NOT_YOUR_WISHLIST | Not your wishlist | The wishlist belongs to another customer. | Ownership is enforced — you can only delete your own. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/wishlist`"}},"/client-data/all":{"get":{"operationId":"ClientAccountController_getAllClientData","summary":"Get everything about my account","description":"The customer's full account data in one response. Heavier than the dashboard — intended for a data-export or \"download my data\" flow rather than routine page loads.\n\n#### Signature\n\n```http\nGET /client-data/all () -> All account data\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Large response. Do not call it on every page.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/dashboard`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"x-client-info","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"All account data","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/all","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/transactions":{"get":{"operationId":"ClientAccountController_getTransactions","summary":"Get my transactions","description":"The customer's payment history across orders and subscriptions.\n\n#### Signature\n\n```http\nGET /client-data/transactions (page?: integer, limit?: integer, status?: string, paymentMethodId?: string) -> Transactions\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/orders`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"paymentMethodId","required":false,"in":"query","schema":{"type":"string"},"description":"Only transactions paid with this saved method."},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1},"example":1},{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"description":"Rows per page.","example":20},{"name":"status","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Transactions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/transactions","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/pay/{id}":{"get":{"operationId":"ClientAccountController_getPaymentLink","summary":"What a payment link is for, and what is owed","description":"Resolves the link's record and answers with its lines, total, what has been paid, the `balance` left, the payments so far and the gateways the org accepts (public fields only). A payment request is the payment itself, so it is either fully owed or settled.\n\n#### Signature\n\n```http\nGET /client-data/pay/{id} (id: string) -> The payment view\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PAYMENT_NOT_FOUND | No payment matches that reference | The id resolves to neither a payment request nor an invoice. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/pay/{id}/intent`\n- `POST /client-data/pay/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"The record id the payment link carries: a payment-request pay token or transaction sk, or an invoice sk.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"200":{"description":"The payment view","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["transaction","invoice"]},"id":{"type":"string"},"reference":{"type":"string","description":"Invoice number, or the request's ref."},"description":{"type":"string"},"requestedBy":{"type":"string","nullable":true,"description":"Payment requests only."},"issuedAt":{"type":"string","nullable":true},"dueAt":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"discount":{"type":"number"},"amount":{"type":"number"}}}},"subTotal":{"type":"number"},"tax":{"type":"number"},"discount":{"type":"number"},"total":{"type":"number"},"totalPaid":{"type":"number","description":"For an invoice, summed from the payments recorded against it (refunds and voids subtracted) — never the stored amountPaid."},"balance":{"type":"number","description":"What is still owed. The only amount a payment against this link can charge."},"currency":{"type":"string","example":"USD"},"status":{"type":"string"},"payments":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"gateway":{"type":"string"},"method":{"type":"string"},"status":{"type":"string"},"date":{"type":"string"}}}},"gateways":{"type":"array","items":{"type":"object","description":"What a payment page may see of a gateway: provider, label and its own public credential. Gateways missing a credential they need are left out.","properties":{"sk":{"type":"string"},"name":{"type":"string"},"data":{"type":"object","properties":{"provider":{"type":"string","example":"StripeProvider"},"name":{"type":"string"},"default":{"type":"boolean"},"publishableKey":{"type":"string"},"clientId":{"type":"string"},"sandbox":{"type":"boolean"},"testMode":{"type":"boolean"}}}}}},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No payment matches that reference — The id resolves to neither a payment request nor an invoice.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No payment matches that reference","path":"/client-data/pay/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account · Payment links"]},"post":{"operationId":"ClientAccountController_payPaymentLink","summary":"Record a payment taken against a payment link","description":"Records what the gateway charged. The amount is the **server** balance, not the caller's — with nothing owed nothing is recorded (`alreadySettled: true`, `paid: 0`), which is what stops a link collecting twice.\n\nAn invoice goes through the storefront payment path (transaction written, invoice updated, amount verified with the gateway); a payment request is settled in place rather than gaining a second row for the same reference. The payer is recorded: the signed-in customer, or the `email`/`name` given on the page.\n\n#### Signature\n\n```http\nPOST /client-data/pay/{id} (id: string, body) -> The refreshed payment view plus `paid` (what was recorded)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PAYMENT_NOT_FOUND | No payment matches that reference | The id resolves to neither a payment request nor an invoice. | — |\n| `400` | REF_REQUIRED | The gateway reference is required | Something is owed and no `ref` was sent. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/pay/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"The record id the payment link carries: a payment-request pay token or transaction sk, or an invoice sk.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gateway","ref"],"properties":{"gateway":{"type":"string","description":"Gateway that took the money.","example":"stripe"},"ref":{"type":"string","description":"Gateway transaction / payment intent id.","example":"pi_3PabcXYZ"},"method":{"type":"string","example":"card"},"email":{"type":"string"},"name":{"type":"string"}}},"example":{"gateway":"stripe","ref":"pi_3PabcXYZ","method":"card","email":"ada@example.com"}}}},"responses":{"201":{"description":"The refreshed payment view plus `paid` (what was recorded)","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["transaction","invoice"]},"id":{"type":"string"},"reference":{"type":"string","description":"Invoice number, or the request's ref."},"description":{"type":"string"},"requestedBy":{"type":"string","nullable":true,"description":"Payment requests only."},"issuedAt":{"type":"string","nullable":true},"dueAt":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"discount":{"type":"number"},"amount":{"type":"number"}}}},"subTotal":{"type":"number"},"tax":{"type":"number"},"discount":{"type":"number"},"total":{"type":"number"},"totalPaid":{"type":"number","description":"For an invoice, summed from the payments recorded against it (refunds and voids subtracted) — never the stored amountPaid."},"balance":{"type":"number","description":"What is still owed. The only amount a payment against this link can charge."},"currency":{"type":"string","example":"USD"},"status":{"type":"string"},"payments":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"gateway":{"type":"string"},"method":{"type":"string"},"status":{"type":"string"},"date":{"type":"string"}}}},"gateways":{"type":"array","items":{"type":"object","description":"What a payment page may see of a gateway: provider, label and its own public credential. Gateways missing a credential they need are left out.","properties":{"sk":{"type":"string"},"name":{"type":"string"},"data":{"type":"object","properties":{"provider":{"type":"string","example":"StripeProvider"},"name":{"type":"string"},"default":{"type":"boolean"},"publishableKey":{"type":"string"},"clientId":{"type":"string"},"sandbox":{"type":"boolean"},"testMode":{"type":"boolean"}}}}}},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}}},"paid":{"type":"number"},"alreadySettled":{"type":"boolean"}}}}}},"400":{"description":"The gateway reference is required — Something is owed and no `ref` was sent.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"The gateway reference is required","path":"/client-data/pay/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No payment matches that reference — The id resolves to neither a payment request nor an invoice.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No payment matches that reference","path":"/client-data/pay/{id}","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account · Payment links"]}},"/client-data/pay/{id}/intent":{"post":{"operationId":"ClientAccountController_payPaymentLinkIntent","summary":"Start a card payment for a payment link","description":"Creates a Stripe PaymentIntent (card) for the **server's** balance on the record, so the browser cannot name the amount. The receipt email is the signed-in customer's, else `email`, else the one on the record. With nothing owed the answer is `{ alreadySettled: true }` and no intent is created.\n\n#### Signature\n\n```http\nPOST /client-data/pay/{id}/intent (id: string, body) -> The Stripe intent (client secret and publishable key), or { alreadySettled, balance, currency }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | PAYMENT_NOT_FOUND | No payment matches that reference | The id resolves to neither a payment request nor an invoice. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/pay/{id}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"The record id the payment link carries: a payment-request pay token or transaction sk, or an invoice sk.","schema":{"type":"string"},"example":"66f1a2b3c4d5e6f708192a3b"}],"responses":{"201":{"description":"The Stripe intent (client secret and publishable key), or { alreadySettled, balance, currency }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"alreadySettled":{"type":"boolean"},"balance":{"type":"number"},"currency":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No payment matches that reference — The id resolves to neither a payment request nor an invoice.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No payment matches that reference","path":"/client-data/pay/{id}/intent","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account · Payment links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Payer email when nobody is signed in."}}},"example":{"email":"ada@example.com"}}}}}},"/client-data/pay/{id}/squad":{"post":{"operationId":"ClientAccountController_payPaymentLinkSquad","summary":"Start a Squad payment for a payment link","description":"The balance the server says is owed, on Squad's page; the payer comes back to callbackUrl. Answers { ref, checkoutUrl } or { alreadySettled: true }.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Client Account"]}},"/client-data/verification/status":{"get":{"operationId":"ClientAccountController_getVerificationStatus","summary":"Get my verification status","description":"Whether the customer's email and phone have been verified.\n\n#### Signature\n\n```http\nGET /client-data/verification/status () -> Verification status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/verification/email/send`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Verification status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/verification/status","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/verification/email/send":{"post":{"operationId":"ClientAccountController_sendEmailVerification","summary":"Send an email verification code","description":"Sends a verification code to the customer's email. Rate-limit it — otherwise it doubles as a way to send mail to an address repeatedly.\n\n#### Signature\n\n```http\nPOST /client-data/verification/email/send (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/verification/email/verify`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/verification/email/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"],"requestBody":{"description":"Optional target.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/client-data/verification/email/verify":{"post":{"operationId":"ClientAccountController_verifyEmail","summary":"Verify an email code","description":"Confirms the code sent to the customer's email, marking it verified.\n\n#### Signature\n\n```http\nPOST /client-data/verification/email/verify (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/verification/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The code.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"code":"481625"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/verification/email/verify","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/verification/phone/send":{"post":{"operationId":"ClientAccountController_sendPhoneVerification","summary":"Send a phone verification code","description":"Sends a verification code by SMS. Each send costs money and lands on someone's phone — rate-limit per number, not just per account.\n\n#### Signature\n\n```http\nPOST /client-data/verification/phone/send (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/verification/phone/verify`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The number to verify.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"phone":"+15551234567"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/verification/phone/send","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/verification/phone/verify":{"post":{"operationId":"ClientAccountController_verifyPhone","summary":"Verify a phone code","description":"Confirms the SMS code, marking the number verified.\n\n#### Signature\n\n```http\nPOST /client-data/verification/phone/verify (body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/verification/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The code.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"code":"481625"}}}},"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/verification/phone/verify","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/analytics":{"get":{"operationId":"ClientAccountController_getAnalytics","summary":"Get my account analytics","description":"Summary figures about the customer's own activity — spend, order count, engagement.\n\n#### Signature\n\n```http\nGET /client-data/analytics () -> Account analytics\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/dashboard`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Account analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/analytics","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/expert/messages":{"post":{"operationId":"ClientAccountController_sendMessageToExpert","summary":"Message an expert","description":"Sends a message to an expert.\n\n#### Signature\n\n```http\nPOST /client-data/expert/messages (send?: boolean, body) -> The sent message\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/expert/hire`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"send","required":false,"in":"query","schema":{"type":"boolean"},"description":"true to send immediately; otherwise saved as a draft."}],"requestBody":{"description":"The message.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"expertId":"EXP-4821","message":"Can you advise on sizing?"}}}},"responses":{"201":{"description":"The sent message","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/expert/messages","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]},"get":{"operationId":"ClientAccountController_getExpertMessages","summary":"Get my expert messages","description":"Messages exchanged with experts.\n\n#### Signature\n\n```http\nGET /client-data/expert/messages (page?: integer, pageSize?: integer, sort?: string, sortType?: string, conversationWith?: string) -> Expert messages\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/expert/messages`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"conversationWith","required":false,"in":"query","schema":{"type":"string"},"description":"Only the thread with this address."},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":20},{"name":"sort","required":false,"in":"query","schema":{"type":"string"},"description":"Field to sort by."},{"name":"sortType","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Expert messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/expert/messages","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/expert/hire":{"post":{"operationId":"ClientAccountController_hireExpert","summary":"Hire an expert","description":"Engages an expert. This commits the customer to a paid engagement, so confirm terms before calling it.\n\n#### Signature\n\n```http\nPOST /client-data/expert/hire (body) -> The engagement\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/expert/messages`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The engagement.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"expertId":"EXP-4821","scope":"One-hour consultation"}}}},"responses":{"201":{"description":"The engagement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/expert/hire","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/files":{"get":{"operationId":"ClientAccountController_getFiles","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/files","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"],"summary":"Get my files","description":"Files the customer has uploaded, in their own storage area.\n\n#### Signature\n\n```http\nGET /client-data/files () -> Files\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/files/upload`"}},"/client-data/files/{path}":{"delete":{"operationId":"ClientAccountController_deleteFile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"path","required":true,"in":"path","schema":{"type":"string"},"description":"File path within the customer's area. URL-encode any slashes.","example":"documents%2Fcontract.pdf"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/files/{path}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"],"summary":"Delete a file","description":"Deletes one of the customer's files. The path is a segment, so it must be URL-encoded if it contains slashes.\n\n#### Signature\n\n```http\nDELETE /client-data/files/{path} (path: string) -> Deletion result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/files`"}},"/client-data/files/upload":{"post":{"operationId":"ClientAccountController_upload","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The uploaded file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/files/upload","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"],"summary":"Upload a file","description":"Uploads a file to the customer's own storage area.\n\n#### Signature\n\n```http\nPOST /client-data/files/upload (body) -> The uploaded file\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /client-data/files/{path}`","requestBody":{"description":"Multipart form with the file.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}}}},"/client-data/benefits":{"get":{"operationId":"ClientAccountController_getCustomerBenefits","summary":"Get available benefits","description":"Benefits the customer can enrol in.\n\n#### Signature\n\n```http\nGET /client-data/benefits () -> Available benefits\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/benefits/enroll`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Available benefits","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/benefits","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/benefits/enroll":{"post":{"operationId":"ClientAccountController_applyForBenefit","summary":"Enrol in a benefit","description":"Enrols the customer in a benefit. Enrolment may require an application form and a legal agreement — the CRM benefit endpoints enforce those rules.\n\n#### Signature\n\n```http\nPOST /client-data/benefits/enroll (body) -> The enrolment\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `GET /client-data/benefits/enrollments`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The enrolment.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"benefit":"health-plan","agreementAccepted":true}}}},"responses":{"201":{"description":"The enrolment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/benefits/enroll","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/benefits/enrollments":{"get":{"operationId":"ClientAccountController_getMyEnrollments","summary":"Get my benefit enrolments","description":"The customer's benefit enrolments and their status.\n\n#### Signature\n\n```http\nGET /client-data/benefits/enrollments () -> Enrolments\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `401` | CUSTOMER_REQUIRED | Customer required | No signed-in customer could be resolved. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |\n\nPlus the standard platform errors: `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/benefits/enroll`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Enrolments","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Customer required — No signed-in customer could be resolved.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":401,"error":"Customer required","path":"/client-data/benefits/enrollments","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/client-data/benefits/{name}/application":{"get":{"operationId":"ClientAccountController_getBenefitApplication","summary":"Get one benefit application","description":"One benefit's application as a page asks for it: the benefit (title, description, legal agreement, whether it needs approval, whether it is open), its application form schema, and the signed-in customer's current enrolment for it.\n\n#### Signature\n\n```http\nGET /client-data/benefits/{name}/application () -> The application and my status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /client-data/benefits/enroll`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Benefit name","schema":{"type":"string"}}],"responses":{"200":{"description":"The application and my status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Client Account"]}},"/sync":{"get":{"operationId":"SyncController_syncInfo","summary":"Get sync information","description":"Overall sync state for the platform.\n\n#### Signature\n\n```http\nGET /sync () -> Sync information\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/info`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Sync information","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/info":{"get":{"operationId":"SyncController_info","summary":"Get organization sync info","description":"Sync configuration and last-run detail for the calling org.\n\n#### Signature\n\n```http\nGET /sync/info () -> Org sync info\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Org sync info","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/purge":{"get":{"operationId":"SyncController_purge","summary":"Purge sync data","description":"Deletes the org's accumulated sync data.\n\n**This is a destructive operation exposed as a GET.** Anything that pre-fetches links, a browser address bar, or a crawler following a URL will trigger it. There is no confirmation body and no undo — the next sync has to rebuild everything from the source platform.\n\n#### Signature\n\n```http\nGET /sync/purge () -> The purge result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Destructive, and reachable by a plain GET.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sync/trigger`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The purge result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/queue":{"post":{"operationId":"SyncController_queueJob","summary":"Queue a sync job","description":"Queues a sync job for processing. The body is the job configuration; an empty body is rejected.\n\n#### Signature\n\n```http\nPOST /sync/queue (body) -> The queued job\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | EMPTY_DATA | Empty Data | The body is empty. | Supply a job configuration. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sync/trigger`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The sync job configuration.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"platform":"shopify","syncType":"products"}}}},"responses":{"201":{"description":"The queued job","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Empty Data — The body is empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Empty Data","path":"/sync/queue","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/pause/{name}":{"get":{"operationId":"SyncController_pause","summary":"Pause a sync job","description":"Pauses a running sync job. **A state change exposed as a GET** — treat the URL as an action, not something safe to prefetch.\n\nPausing stops new work; a job already mid-run finishes what it is doing.\n\n#### Signature\n\n```http\nGET /sync/pause/{name} (name: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Mutating GET.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/resume/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Sync job name.","schema":{"type":"string"},"example":"shopify-products"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/resume/{name}":{"get":{"operationId":"SyncController_resume","summary":"Resume a sync job","description":"Resumes a paused sync job. Also a mutating GET.\n\n#### Signature\n\n```http\nGET /sync/resume/{name} (name: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Mutating GET.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/pause/{name}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"name","required":true,"in":"path","description":"Sync job name.","schema":{"type":"string"},"example":"shopify-products"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/trigger":{"post":{"operationId":"SyncController_triggerSync","summary":"Trigger a sync","description":"Manually runs a sync for a platform. `syncType` takes a single type **or an array** of types, so several can be triggered together.\n\n`options.force` overrides the guard that stops a sync starting while one is already running — which is exactly the guard that prevents two concurrent syncs writing over each other. Use it only when you know the previous run is genuinely dead.\n\nWithout `startDate`/`endDate` the platform's own default window applies; supply them to back-fill.\n\nRecurring sync runs as platform scheduled jobs per business (GET /jobs/scheduled): `broadcast-send`, `notification-send`, `external-mail-pull`, `service-billing`, `data-purge`, `social-sync-messages`, `social-sync-content`, `social-sync-insights`. Some platforms here are those jobs run now: `notifications` → notification-send, `external-mail` → external-mail-pull (the answer lists each mailbox), `all-social` → the three social jobs in turn, `escalation` → workflow-escalation. Each run is a `job` record (`jobId`).\n\n#### Signature\n\n```http\nPOST /sync/trigger (body) -> The triggered job\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `force` bypasses the concurrent-run guard.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/platforms`\n- `GET /sync/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What to sync.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","syncType"],"properties":{"platform":{"type":"string","description":"Platform to sync.","example":"shopify"},"syncType":{"description":"One type, or several.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"example":"products"},"options":{"type":"object","properties":{"startDate":{"type":"string","description":"ISO string.","example":"2026-08-01"},"endDate":{"type":"string","description":"ISO string.","example":"2026-08-31"},"force":{"type":"boolean","description":"Run even if a sync is already in flight.","example":false}}}}},"examples":{"single":{"summary":"One sync type","value":{"platform":"shopify","syncType":"products"}},"backfill":{"summary":"Back-fill a date range across several types","value":{"platform":"shopify","syncType":["products","orders"],"options":{"startDate":"2026-08-01","endDate":"2026-08-31"}}}}}}},"responses":{"200":{"description":"Sync job triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"platform":{"type":"string"},"syncType":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"orgId":{"type":"string"},"jobId":{"type":"string"},"timestamp":{"type":"number"}}}}}},"201":{"description":"The triggered job","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid sync type or missing parameters"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/trigger/{platform}/{syncType}":{"post":{"operationId":"SyncController_triggerSyncByParam","summary":"Trigger a sync by URL","description":"The same trigger, with the platform and sync type in the path instead of the body — convenient from a script or a webhook. `syncType` is optional; omitting it runs the platform's default set.\n\n#### Signature\n\n```http\nPOST /sync/trigger/{platform}/{syncType} (platform: string, syncType: string, body) -> The triggered job\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sync/trigger`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"platform","required":true,"in":"path","description":"Platform to sync.","schema":{"type":"string"},"example":"shopify"},{"name":"syncType","required":true,"in":"path","description":"Sync type. Optional — omit for the platform default.","schema":{"type":"string"},"example":"products"}],"requestBody":{"description":"Optional options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"force":false}}}},"responses":{"201":{"description":"The triggered job","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid sync type"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/platforms":{"get":{"operationId":"SyncController_getAvailablePlatforms","summary":"List platforms and sync types","description":"Which platforms can be synced and which sync types each supports — read this before constructing a trigger, since the valid types differ per platform.\n\n#### Signature\n\n```http\nGET /sync/platforms () -> Platforms and their sync types\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /sync/trigger`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"Platforms and their sync types","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/status":{"get":{"operationId":"SyncController_getSyncStatus","summary":"Get sync job status","description":"The state of the org's sync jobs — what is running, what finished, what failed.\n\n#### Signature\n\n```http\nGET /sync/status () -> Sync status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/status/{platform}`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Sync status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/sync/status/{platform}":{"get":{"operationId":"SyncController_getPlatformSyncStatus","summary":"Get one platform's sync status","description":"Sync state for a single platform.\n\n#### Signature\n\n```http\nGET /sync/status/{platform} (platform: string) -> Platform sync status\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /sync/status`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"platform","required":true,"in":"path","description":"Platform name.","schema":{"type":"string"},"example":"shopify"}],"responses":{"200":{"description":"Platform sync status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Sync"]}},"/schedule-control/run/{id}":{"post":{"operationId":"ScheduleControlController_runNow","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/schedule-control/start/{id}":{"post":{"operationId":"ScheduleControlController_start","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/schedule-control/stop/{id}":{"post":{"operationId":"ScheduleControlController_stop","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/schedule-control/cancel-job":{"post":{"operationId":"ScheduleControlController_cancelJob","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":""}}}},"/notice/feed":{"get":{"operationId":"NoticeController_feed","summary":"Get notices for this viewer","description":"The notices to show the current viewer right now — targeting and frequency rules are applied server-side, so a client shows what it is given rather than deciding itself. `surface` says where they will be displayed.\n\n#### Signature\n\n```http\nGET /notice/feed (site?: string, surface?: string) -> Notices to display\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /notice/{id}/display`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"site","required":false,"in":"query","schema":{"type":"string"},"example":"acme-shop"},{"name":"surface","required":false,"in":"query","schema":{"type":"string"},"description":"Where the notices will be shown.","example":"dashboard"}],"responses":{"200":{"description":"Notices to display","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/inbox":{"get":{"operationId":"NoticeController_inbox","summary":"Get the notice inbox","description":"Every notice the org has been sent, whether or not it is currently eligible to display — the archive, where `feed` is the live selection.\n\n#### Signature\n\n```http\nGET /notice/inbox (site?: string) -> Notices\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /notice/feed`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"site","required":false,"in":"query","schema":{"type":"string"},"example":"acme-shop"}],"responses":{"200":{"description":"Notices","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/{id}/display":{"post":{"operationId":"NoticeController_display","summary":"Record a notice display","description":"Records that a notice was actually shown. This feeds frequency capping as well as reporting — without it, a notice capped at three impressions will keep reappearing.\n\n#### Signature\n\n```http\nPOST /notice/{id}/display (id: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Drives frequency capping, not just analytics.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /notice/{id}/click`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Notice id.","schema":{"type":"string"},"example":"NTC-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/{id}/click":{"post":{"operationId":"NoticeController_click","summary":"Record a notice click","description":"Records a click on one of a notice's actions.\n\n#### Signature\n\n```http\nPOST /notice/{id}/click (id: string, body) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /notice/{id}/insights`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Notice id.","schema":{"type":"string"},"example":"NTC-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"],"requestBody":{"description":"Which action.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"action":"learn-more"}}}}}},"/notice/{id}/accept":{"post":{"operationId":"NoticeController_accept","summary":"Accept a notice","description":"Records that the viewer accepted what the notice asked. For a notice presenting terms, this is the acceptance record — it carries weight beyond analytics.\n\n#### Signature\n\n```http\nPOST /notice/{id}/accept (id: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /notice/{id}/reject`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Notice id.","schema":{"type":"string"},"example":"NTC-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/{id}/reject":{"post":{"operationId":"NoticeController_reject","summary":"Reject a notice","description":"Records that the viewer declined. Distinct from dismissing: rejection is an answer, dismissal is closing the box.\n\n#### Signature\n\n```http\nPOST /notice/{id}/reject (id: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /notice/{id}/dismiss`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Notice id.","schema":{"type":"string"},"example":"NTC-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/{id}/dismiss":{"post":{"operationId":"NoticeController_dismiss","summary":"Dismiss a notice","description":"Closes a notice for this viewer without answering it. Typically stops it reappearing for that viewer.\n\n#### Signature\n\n```http\nPOST /notice/{id}/dismiss (id: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /notice/{id}/reject`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Notice id.","schema":{"type":"string"},"example":"NTC-4821"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/activity":{"get":{"operationId":"NoticeController_activity","summary":"Get the notice activity log","description":"Raw notice events — displays, clicks, acceptances — filterable by notice, event type and viewer.\n\n#### Signature\n\n```http\nGET /notice/activity (noticeId?: string, event?: string, viewerId?: string, page?: integer, pageSize?: integer) -> Activity events\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /notice/insights`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"noticeId","required":false,"in":"query","schema":{"type":"string"},"example":"NTC-4821"},{"name":"event","required":false,"in":"query","schema":{"type":"string"},"example":"click"},{"name":"viewerId","required":false,"in":"query","schema":{"type":"string"},"example":"CUST-4821"},{"name":"page","required":false,"in":"query","schema":{"type":"integer"},"example":1},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"Activity events","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/insights":{"get":{"operationId":"NoticeController_overview","summary":"Get notice engagement","description":"Engagement across every live notice — which are being seen and acted on.\n\n#### Signature\n\n```http\nGET /notice/insights (site?: string) -> Engagement figures\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /notice/{id}/insights`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"site","required":false,"in":"query","schema":{"type":"string"},"example":"acme-shop"}],"responses":{"200":{"description":"Engagement figures","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/notice/{id}/insights":{"get":{"operationId":"NoticeController_insights","summary":"Get one notice's insights","description":"The funnel for a single notice — displayed, clicked, accepted — plus its recent activity.\n\n#### Signature\n\n```http\nGET /notice/{id}/insights (id: string) -> Funnel and activity\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /notice/activity`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"id","required":true,"in":"path","description":"Notice id.","schema":{"type":"string"},"example":"NTC-4821"},{"name":"limit","required":false,"in":"query","description":"Recent interactions to return (default 50)","schema":{"type":"string"}}],"responses":{"200":{"description":"Funnel and activity","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Notices"]}},"/monitoring/overview":{"get":{"operationId":"MonitoringController_getSystemOverview","summary":"Get the system overview","parameters":[],"responses":{"200":{"description":"The overview","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"The operational dashboard in one call — health, resources, queues and recent alerts together. The first thing to look at when something is wrong.\n\n#### Signature\n\n```http\nGET /monitoring/overview () -> The overview\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/health`"}},"/monitoring/historical":{"get":{"operationId":"MonitoringController_getHistoricalMetrics","summary":"Get historical metrics","parameters":[{"name":"range","required":false,"in":"query","description":"Time range, e.g. `1h`, `24h`, `7d`.","schema":{"type":"string"},"example":"24h"}],"responses":{"200":{"description":"Historical metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Metrics over a time range, for spotting a trend rather than a moment. `range` names the window.\n\n#### Signature\n\n```http\nGET /monitoring/historical (range?: string) -> Historical metrics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/system-metrics`"}},"/monitoring/health":{"get":{"operationId":"MonitoringController_getHealthCheck","summary":"Get detailed health checks","parameters":[],"responses":{"200":{"description":"Component health","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Per-component health for every system dependency — database, Redis, queues, external services. More detailed than a liveness probe: a component can be degraded while the process is alive.\n\nThis path is exempt from rate limiting, so it is safe to poll from a monitor.\n\n#### Signature\n\n```http\nGET /monitoring/health () -> Component health\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/system-metrics`"}},"/monitoring/system-metrics":{"get":{"operationId":"MonitoringController_getSystemMetrics","summary":"Get system resource metrics","parameters":[],"responses":{"200":{"description":"Resource metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"CPU, memory and process metrics for the running instance.\n\n#### Signature\n\n```http\nGET /monitoring/system-metrics () -> Resource metrics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/historical`"}},"/monitoring/queues":{"get":{"operationId":"MonitoringController_getQueueStats","summary":"Get queue statistics","parameters":[],"responses":{"200":{"description":"Queue statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Job counts and processing rates across queues. Rising waiting counts with a flat completed rate is the signature of a stalled worker.\n\n#### Signature\n\n```http\nGET /monitoring/queues () -> Queue statistics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/queues/{queueName}`"}},"/monitoring/jobs":{"get":{"operationId":"MonitoringController_findJobs","summary":"Jobs across the queues, searched, filtered and paged on the server (newest first)","parameters":[{"name":"queue","required":true,"in":"query","schema":{"type":"string"}},{"name":"status","required":true,"in":"query","schema":{"type":"string"}},{"name":"q","required":true,"in":"query","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"string"}},{"name":"pageSize","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Monitoring"]}},"/monitoring/jobs/{queueName}/{jobId}/{action}":{"post":{"operationId":"MonitoringController_jobAction","summary":"Retry a failed job, or remove a job from its queue","parameters":[{"name":"queueName","required":true,"in":"path","schema":{"type":"string"}},{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}},{"name":"action","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Monitoring"]}},"/monitoring/queues/{queueName}":{"get":{"operationId":"MonitoringController_getQueueDetails","summary":"Get one queue's statistics","parameters":[{"name":"queueName","required":true,"in":"path","description":"Queue name.","schema":{"type":"string"},"example":"sync"}],"responses":{"200":{"description":"Queue statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Statistics for a single queue.\n\n#### Signature\n\n```http\nGET /monitoring/queues/{queueName} (queueName: string) -> Queue statistics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/queues`"}},"/monitoring/alerts":{"get":{"operationId":"MonitoringController_getRecentAlerts","summary":"Get recent alerts","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer"},"example":50}],"responses":{"200":{"description":"Alerts","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Alerts and notifications the system has raised, newest first.\n\n#### Signature\n\n```http\nGET /monitoring/alerts (limit?: integer) -> Alerts\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/alert-notifications`"}},"/monitoring/user-activity":{"get":{"operationId":"MonitoringController_getUserActivity","summary":"Get user activity metrics","parameters":[],"responses":{"200":{"description":"Activity metrics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Current user activity across the platform — sessions and request volume.\n\n#### Signature\n\n```http\nGET /monitoring/user-activity () -> Activity metrics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n- Reads across organizations, not just the calling one.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/web-activity`"}},"/monitoring/company-creation":{"get":{"operationId":"MonitoringController_getCompanyCreationMetrics","summary":"Monitor company creation","parameters":[],"responses":{"200":{"description":"Recent company creations","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"New organization registrations recorded in the **root org** — a growth signal for operators.\n\nBecause it reads root-org records on an unauthenticated route, it discloses who has recently signed up to anyone who can reach it.\n\n#### Signature\n\n```http\nGET /monitoring/company-creation () -> Recent company creations\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n- Reads across organizations, not just the calling one.\n- Discloses recent signups.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/domain-mappings`"}},"/monitoring/domain-mappings":{"get":{"operationId":"MonitoringController_getDomainMappingMetrics","summary":"Monitor domain mappings","parameters":[],"responses":{"200":{"description":"Domain mappings","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Domain mappings recorded in the root org — which hostnames route where across the platform. Cross-org, and unauthenticated: it maps customers to their domains.\n\n#### Signature\n\n```http\nGET /monitoring/domain-mappings () -> Domain mappings\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n- Reads across organizations, not just the calling one.\n- Discloses customer domains.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/company-creation`"}},"/monitoring/alert-notifications":{"get":{"operationId":"MonitoringController_getAlertNotificationMetrics","summary":"Monitor alerts and notifications","parameters":[],"responses":{"200":{"description":"Alert notifications","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Alerts and notifications recorded in the shared and root orgs — the platform-wide notification stream.\n\n#### Signature\n\n```http\nGET /monitoring/alert-notifications () -> Alert notifications\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n- Reads across organizations, not just the calling one.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/alerts`"}},"/monitoring/usage":{"get":{"operationId":"MonitoringController_getUsageMetrics","summary":"Monitor platform usage","parameters":[],"responses":{"200":{"description":"Usage statistics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Platform usage and API consumption figures across organizations.\n\n#### Signature\n\n```http\nGET /monitoring/usage () -> Usage statistics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n- Reads across organizations, not just the calling one.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/overview`"}},"/monitoring/web-activity":{"get":{"operationId":"MonitoringController_getWebActivityMetrics","summary":"Monitor web activity","parameters":[],"responses":{"200":{"description":"Web activity","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Monitoring"],"description":"Site visits and user interactions recorded across the platform.\n\n#### Signature\n\n```http\nGET /monitoring/web-activity () -> Web activity\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n- Reads across organizations, not just the calling one.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /monitoring/user-activity`"}},"/analytics/dashboard/all":{"get":{"operationId":"AnalyticsController_getAllDashboardData","summary":"Get all dashboard data","description":"Every dashboard in one response — website, blog, workflow, storefront, tickets, leads, automation, social and users. Heavier than fetching one, but it saves nine round trips when a page shows them together.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/all (startDate?: string, endDate?: string) -> All dashboards\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/website`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"All dashboards","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/website":{"get":{"operationId":"AnalyticsController_getWebsiteAnalytics","summary":"Get website analytics","description":"Traffic and engagement for the org's sites. Narrow it with `siteName`, `domain` or `host` — without one, the figures cover every site the org runs, which is rarely what a per-site view wants.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/website (startDate?: string, endDate?: string, siteName?: string, domain?: string, host?: string) -> Website analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/filter-options`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"},{"name":"siteName","required":false,"in":"query","schema":{"type":"string"},"example":"acme-shop"},{"name":"domain","required":false,"in":"query","schema":{"type":"string"},"example":"shop.example.com"},{"name":"host","required":false,"in":"query","schema":{"type":"string"},"example":"shop.example.com"}],"responses":{"200":{"description":"Website analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/blog":{"get":{"operationId":"AnalyticsController_getBlogAnalytics","summary":"Get blog analytics","description":"Post performance and readership over a date range.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/blog (startDate?: string, endDate?: string) -> Blog analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/all`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Blog analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/workflow":{"get":{"operationId":"AnalyticsController_getWorkflowAnalytics","summary":"Get workflow analytics","description":"Pipeline throughput and stage timings, drawn from the workflow engine.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/workflow (startDate?: string, endDate?: string) -> Workflow analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /workflow/analytics/{workflowId}/wait-times`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Workflow analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/storefront":{"get":{"operationId":"AnalyticsController_getStorefrontAnalytics","summary":"Get storefront analytics","description":"Orders, revenue and conversion for the storefront.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/storefront (startDate?: string, endDate?: string) -> Storefront analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/all`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Storefront analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/tickets":{"get":{"operationId":"AnalyticsController_getTicketAnalytics","summary":"Get ticket analytics","description":"Support ticket volume, resolution time and backlog.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/tickets (startDate?: string, endDate?: string) -> Ticket analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/all`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Ticket analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/leads":{"get":{"operationId":"AnalyticsController_getLeadsAnalytics","summary":"Get leads analytics","description":"Lead volume, source and conversion over a date range.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/leads (startDate?: string, endDate?: string) -> Leads analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/automation`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Leads analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/automation":{"get":{"operationId":"AnalyticsController_getAutomationAnalytics","summary":"Get automation analytics","description":"Automation run counts, successes and failures.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/automation (startDate?: string, endDate?: string) -> Automation analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/all`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Automation analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/social":{"get":{"operationId":"AnalyticsController_getSocialMediaAnalytics","summary":"Get social media analytics","description":"Social reach and engagement across connected accounts.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/social (startDate?: string, endDate?: string) -> Social analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/all`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"Social analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/users":{"get":{"operationId":"AnalyticsController_getUserAccountAnalytics","summary":"Get user account analytics","description":"Account signups, activity and retention for the org.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/users (startDate?: string, endDate?: string) -> User analytics\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/all`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"User analytics","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/analytics/dashboard/{dashboardType}/refresh":{"get":{"operationId":"AnalyticsController_refreshDashboard","summary":"Refresh a dashboard","description":"Recomputes one dashboard rather than serving the cached figures. Deliberately more expensive than the plain read — call it when the numbers must be current, not on every page load.\n\n#### Signature\n\n```http\nGET /analytics/dashboard/{dashboardType}/refresh (dashboardType: string, startDate?: string, endDate?: string) -> The refreshed dashboard\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — this controller is entirely public.\n- Recomputes rather than reading cache.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /analytics/dashboard/all`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"dashboardType","required":true,"in":"path","description":"Which dashboard — `website`, `blog`, `storefront`, and so on.","schema":{"type":"string"},"example":"storefront"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-31"}],"responses":{"200":{"description":"The refreshed dashboard","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Analytics"]}},"/documentation":{"get":{"operationId":"DocumentationController_page","parameters":[],"responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"The API reference page","description":"The reference for people: a page that loads the index and fetches one section at a time. It needs JavaScript; crawlers and agents should use the markdown and search routes instead.\n\n#### Signature\n\n```http\nGET /documentation () -> HTML page\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /llms.txt`\n- `GET /documentation.md`","tags":["API reference"]}},"/api-docs":{"get":{"operationId":"DocumentationController_alias","parameters":[],"responses":{"302":{"description":"Redirect to /documentation","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Redirect /api-docs to the reference","description":"A conventional alias, so a reasonable guess lands somewhere useful: 302 to `/documentation`.\n\n#### Signature\n\n```http\nGET /api-docs () -> Redirect to /documentation\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /documentation`","tags":["API reference"]}},"/docs":{"get":{"operationId":"DocumentationController_alias","parameters":[],"responses":{"302":{"description":"Redirect to /documentation","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Redirect /docs to the reference","description":"A conventional alias, so a reasonable guess lands somewhere useful: 302 to `/documentation`.\n\n#### Signature\n\n```http\nGET /docs () -> Redirect to /documentation\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /documentation`","tags":["API reference"]}},"/swagger":{"get":{"operationId":"DocumentationController_alias","parameters":[],"responses":{"302":{"description":"Redirect to /documentation","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Redirect /swagger to the reference","description":"A conventional alias, so a reasonable guess lands somewhere useful: 302 to `/documentation`.\n\n#### Signature\n\n```http\nGET /swagger () -> Redirect to /documentation\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /documentation`","tags":["API reference"]}},"/llms.txt":{"get":{"operationId":"DocumentationController_llms","parameters":[],"responses":{"200":{"description":"Plain text","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"API documentation is not ready yet — The server has just started and has not built the document yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"API documentation is not ready yet","path":"/llms.txt","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"What this API is, for agents","description":"The entry point an agent checks before guessing URLs (llmstxt.org): what the platform is and where the rest of the reference lives — a map to the real files rather than a copy of them. Cached for 5 minutes.\n\n#### Signature\n\n```http\nGET /llms.txt () -> Plain text\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `503` | DOCS_NOT_READY | API documentation is not ready yet | The server has just started and has not built the document yet. | Retry in a few seconds. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /documentation/search`\n- `GET /documentation.md`","tags":["API reference"]}},"/documentation.md":{"get":{"operationId":"DocumentationController_indexMarkdown","parameters":[],"responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"API documentation is not ready yet — The server has just started and has not built the document yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"API documentation is not ready yet","path":"/documentation.md","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"Every endpoint, one line each","description":"The whole list as markdown, grouped by section — for reading breadth-first. Cached for 5 minutes.\n\n#### Signature\n\n```http\nGET /documentation.md () -> Markdown\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `503` | DOCS_NOT_READY | API documentation is not ready yet | The server has just started and has not built the document yet. | Retry in a few seconds. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /documentation/tag/{slug}.md`","tags":["API reference"]}},"/documentation/tag/{slug}.md":{"get":{"operationId":"DocumentationController_tagMarkdown","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"},"description":"Section slug — the tag name lowercased with dashes, as listed in `/documentation.md` or `/documentation/index.json`.","example":"ai-employees"}],"responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"No documented endpoints for \"ai-employees\" — No section has that slug.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No documented endpoints for \"ai-employees\"","path":"/documentation/tag/{slug}.md","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"API documentation is not ready yet — The server has just started and has not built the document yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"API documentation is not ready yet","path":"/documentation/tag/{slug}.md","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"One section in full, as markdown","description":"Every endpoint in one section with its parameters, bodies, responses, errors and examples.\n\n#### Signature\n\n```http\nGET /documentation/tag/{slug}.md (slug: string) -> Markdown\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SECTION_NOT_FOUND | No documented endpoints for \"ai-employees\" | No section has that slug. | — |\n| `503` | DOCS_NOT_READY | API documentation is not ready yet | The server has just started and has not built the document yet. | Retry in a few seconds. |\n\nPlus the standard platform errors: `429`, `500`.","tags":["API reference"]}},"/documentation/search":{"get":{"operationId":"DocumentationController_search","parameters":[{"name":"q","required":true,"in":"query","schema":{"type":"string"},"example":"refund"},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","default":20},"description":"Up to 100."}],"responses":{"200":{"description":"{ query, count, results }","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"method":{"type":"string"},"path":{"type":"string"},"summary":{"type":"string"},"group":{"type":"string"},"detail":{"type":"string","description":"URL of GET /documentation/endpoint for it."},"section":{"type":"string","description":"URL of its section's markdown."}}}}}}}}},"400":{"description":"Pass ?q= to search, e.g. /documentation/search?q=refund — `q` is missing or empty.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Pass ?q= to search, e.g. /documentation/search?q=refund","path":"/documentation/search","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Find endpoints by phrase","description":"The endpoints that match a phrase, best first, each with the URL of its full detail and of its section — so a caller never has to construct one.\n\n#### Signature\n\n```http\nGET /documentation/search (q?: string, limit?: integer) -> { query, count, results }\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | QUERY_REQUIRED | Pass ?q= to search, e.g. /documentation/search?q=refund | `q` is missing or empty. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /documentation/endpoint`","tags":["API reference"]}},"/documentation/endpoint":{"get":{"operationId":"DocumentationController_endpoint","parameters":[{"name":"method","required":true,"in":"query","schema":{"type":"string"},"example":"GET"},{"name":"path","required":true,"in":"query","schema":{"type":"string"},"description":"OpenAPI-style path with `{param}` placeholders.","example":"/repository/find/{datatype}/{dataId}"},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["md","json"],"default":"md"}}],"responses":{"200":{"description":"Markdown, or `{ method, path, tag, operation, components }` with format=json","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Pass ?method= and ?path=, e.g. /documentation/endpoint?method=GET&path=/repository/find/{datatype}/{dataId} — `method` or `path` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Pass ?method= and ?path=, e.g. /documentation/endpoint?method=GET&path=/repository/find/{datatype}/{dataId}","path":"/documentation/endpoint","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No documented endpoint for GET /nope — No documented operation matches.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No documented endpoint for GET /nope","path":"/documentation/endpoint","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"One endpoint in full","description":"One endpoint, addressed by method and path (operation ids are not unique across modules). Markdown by default; `format=json` returns the OpenAPI operation with the components it uses.\n\n#### Signature\n\n```http\nGET /documentation/endpoint (method?: string, path?: string, format?: string) -> Markdown, or `{ method, path, tag, operation, components }` with format=json\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | METHOD_AND_PATH_REQUIRED | Pass ?method= and ?path=, e.g. /documentation/endpoint?method=GET&path=/repository/find/{datatype}/{dataId} | `method` or `path` is missing. | — |\n| `404` | ENDPOINT_NOT_FOUND | No documented endpoint for GET /nope | No documented operation matches. | — |\n\nPlus the standard platform errors: `429`, `500`.","tags":["API reference"]}},"/documentation-json":{"get":{"operationId":"DocumentationController_json","parameters":[],"responses":{"200":{"description":"OpenAPI 3 document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"API documentation is not ready yet — The server has just started and has not built the document yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"API documentation is not ready yet","path":"/documentation-json","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"The OpenAPI document","description":"The complete OpenAPI 3 document, for code generators and Postman. Large — the page does not load it. Same as `/openapi.json`. Cached for 5 minutes.\n\n#### Signature\n\n```http\nGET /documentation-json () -> OpenAPI 3 document\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `503` | DOCS_NOT_READY | API documentation is not ready yet | The server has just started and has not built the document yet. | Retry in a few seconds. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /openapi.json`","tags":["API reference"]}},"/openapi.json":{"get":{"operationId":"DocumentationController_json","parameters":[],"responses":{"200":{"description":"OpenAPI 3 document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"API documentation is not ready yet — The server has just started and has not built the document yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"API documentation is not ready yet","path":"/openapi.json","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"The OpenAPI document","description":"The complete OpenAPI 3 document, for code generators and Postman. Same as `/documentation-json`. Cached for 5 minutes.\n\n#### Signature\n\n```http\nGET /openapi.json () -> OpenAPI 3 document\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `503` | DOCS_NOT_READY | API documentation is not ready yet | The server has just started and has not built the document yet. | Retry in a few seconds. |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /documentation-json`","tags":["API reference"]}},"/documentation/index.json":{"get":{"operationId":"DocumentationController_indexJson","parameters":[],"responses":{"200":{"description":"Index","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"API documentation is not ready yet — The server has just started and has not built the document yet.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":503,"error":"API documentation is not ready yet","path":"/documentation/index.json","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"summary":"The reference's navigation index","description":"The sections and a line per endpoint — what the reference page loads before it draws anything. Cached for 5 minutes.\n\n#### Signature\n\n```http\nGET /documentation/index.json () -> Index\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `503` | DOCS_NOT_READY | API documentation is not ready yet | The server has just started and has not built the document yet. | Retry in a few seconds. |\n\nPlus the standard platform errors: `429`, `500`.","tags":["API reference"]}},"/documentation/tag/{slug}.json":{"get":{"operationId":"DocumentationController_tag","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"},"description":"Section slug — the tag name lowercased with dashes, as listed in `/documentation.md` or `/documentation/index.json`.","example":"ai-employees"}],"responses":{"200":{"description":"OpenAPI 3 document for the section","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"No documented endpoints for \"ai-employees\" — No section has that slug.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No documented endpoints for \"ai-employees\"","path":"/documentation/tag/{slug}.json","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"One section as an OpenAPI document","description":"One section's operations as a standalone OpenAPI document — what the reference page fetches when a section is opened.\n\n#### Signature\n\n```http\nGET /documentation/tag/{slug}.json (slug: string) -> OpenAPI 3 document for the section\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SECTION_NOT_FOUND | No documented endpoints for \"ai-employees\" | No section has that slug. | — |\n\nPlus the standard platform errors: `429`, `500`.","tags":["API reference"]}},"/robots.txt":{"get":{"operationId":"DocumentationController_robots","parameters":[],"responses":{"200":{"description":"robots.txt","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Crawler rules","description":"The reference is meant to be indexed; the API is not. Allows `/documentation`, `/documentation.md`, `/llms.txt` and `/openapi.json`, disallows everything else, and names `/documentation.md` as the sitemap.\n\n#### Signature\n\n```http\nGET /robots.txt () -> robots.txt\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.","tags":["API reference"]}},"/tools/tailwind-css/{siteName}/{pageName}":{"post":{"operationId":"ToolsController_tailwindCss","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"siteName","required":true,"in":"path","schema":{"type":"string"},"description":"Site name.","example":"acme-shop"},{"name":"pageName","required":true,"in":"path","schema":{"type":"string"},"description":"Page name.","example":"home"}],"responses":{"201":{"description":"The generated CSS","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate Tailwind CSS for a page","description":"Builds the Tailwind stylesheet a page actually needs from its markup — the compile step behind a published page.\n\n#### Signature\n\n```http\nPOST /tools/tailwind-css/{siteName}/{pageName} (siteName: string, pageName: string, body) -> The generated CSS\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/tailwind-map/{siteName}/{pageName}`","tags":["Tools"],"requestBody":{"description":"The page markup or build options.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"html":"<div class=\"p-4 text-lg\">…</div>"}}}}}},"/tools/tailwind-map/{siteName}/{pageName}":{"post":{"operationId":"ToolsController_tailwindMap","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"siteName","required":true,"in":"path","schema":{"type":"string"},"description":"Site name.","example":"acme-shop"},{"name":"pageName","required":true,"in":"path","schema":{"type":"string"},"description":"Page name.","example":"home"}],"responses":{"201":{"description":"The class map","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate a Tailwind class map for a page","description":"Returns the class-to-rule map for a page, for tooling that needs to know which utilities resolved to what.\n\n#### Signature\n\n```http\nPOST /tools/tailwind-map/{siteName}/{pageName} (siteName: string, pageName: string, body) -> The class map\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/tailwind-css/{siteName}/{pageName}`","tags":["Tools"],"requestBody":{"description":"The page markup or build options.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"html":"<div class=\"p-4\">…</div>"}}}}}},"/tools/default-templates":{"get":{"operationId":"ToolsController_listDefaultTemplates","parameters":[{"name":"deliveryType","required":false,"in":"query","schema":{"type":"string"},"example":"web"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List default templates","description":"The built-in site templates, optionally filtered by delivery type.\n\n#### Signature\n\n```http\nGET /tools/default-templates (deliveryType?: string) -> Templates\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/default-templates/{name}`","tags":["Tools"]}},"/tools/default-templates/{name}":{"get":{"operationId":"ToolsController_getDefaultTemplate","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Template name.","example":"storefront-basic"},{"name":"variant","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a default template","description":"One built-in template by name.\n\n#### Signature\n\n```http\nGET /tools/default-templates/{name} (name: string) -> The template\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/default-templates`","tags":["Tools"]}},"/tools/index-site/{siteName}":{"post":{"operationId":"ToolsController_indexSite","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"siteName","in":"path","required":true,"description":"Site name.","schema":{"type":"string"},"example":"acme-shop"}],"responses":{"201":{"description":"The indexing result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Index a site","description":"Rebuilds the search index for a site. Worth running after a bulk content change; on a large site it is not cheap.\n\n#### Signature\n\n```http\nPOST /tools/index-site/{siteName} (siteName: string) -> The indexing result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/create-page-image/{siteName}/{pageName}`","tags":["Tools"]}},"/tools/create-page-image/{siteName}/{pageName}":{"post":{"operationId":"ToolsController_generatePageImage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"siteName","in":"path","required":true,"description":"Site name.","schema":{"type":"string"},"example":"acme-shop"},{"name":"pageName","in":"path","required":true,"description":"Page name.","schema":{"type":"string"},"example":"home"}],"responses":{"201":{"description":"The generated image","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate a page image","description":"Renders a page to an image — the preview or social card for it. Rendering a page is slow, so treat this as a background job rather than a request-path call.\n\n#### Signature\n\n```http\nPOST /tools/create-page-image/{siteName}/{pageName} (siteName: string, pageName: string, body) -> The generated image\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/create-site-favicon/{siteName}`","tags":["Tools"],"requestBody":{"description":"Rendering options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"width":1200,"height":630}}}}}},"/tools/web-visit-direct":{"post":{"operationId":"ToolsController_webVisitDirect","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"`true` recorded, `false` ignored","content":{"application/json":{"schema":{"type":"boolean"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Record a direct web visit","description":"Records a page view measured from this request: the caller's IP, user agent and forwarding headers are read here and merged with `data`. `data.url` must be the full page URL — a missing or relative URL, or one on the API's own host, is ignored. Answers `true` when recorded (or already recorded), `false` when ignored.\n\nVisits from bots, crawlers, scanners and uptime probes, requests for files or probe paths (assets, `.env`, `wp-*`, `_next`, `static/chunks`), local development hosts, internal IPs, and any IP past 60 visits a minute are dropped without error — the call answers `false`. An identical visit within 30 seconds is recorded once. Location is looked up from the IP before the row is written.\n\n#### Signature\n\n```http\nPOST /tools/web-visit-direct (body) -> `true` recorded, `false` ignored\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/web-visit-indirect`","tags":["Tools"],"requestBody":{"description":"The visit.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"required":["url"],"properties":{"url":{"type":"string"},"referrer":{"type":"string"},"pageTitle":{"type":"string"},"siteName":{"type":"string"},"deviceId":{"type":"string"},"sessionId":{"type":"string"},"type":{"type":"string","example":"pageview"}}}}},"example":{"data":{"url":"https://shop.example.com/pricing?utm_source=facebook","referrer":"https://www.facebook.com/","pageTitle":"Pricing","deviceId":"dev_7Kq2M9"}}}}}}},"/tools/web-visit-indirect":{"post":{"operationId":"ToolsController_webVisitIndirect","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"x-client-info","in":"header","required":false,"description":"JSON client context from base-app's proxy (real IP, user agent, host). Fills gaps in `data`.","schema":{"type":"string"}}],"responses":{"201":{"description":"`true` recorded, `false` ignored","content":{"application/json":{"schema":{"type":"boolean"}}}},"404":{"description":"Site not found: acme-shop shop.example.com  in org acme — The site named by `configSite` / `host` does not belong to the org (not checked for `source: \"chat-client\"`).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Site not found: acme-shop shop.example.com  in org acme","path":"/tools/web-visit-indirect","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Record a page view from the browser","description":"The page-view beacon — base-app's browser tracker sends one per view (pageview, unload, click and chat events alike, by `data.type`), and it is the only place a page view is recorded. A browser cannot see its own IP, so when base-app's proxy forwards `x-client-info` its IP, user agent and site fill whatever `data` left out; what the page sent wins. The site (`configSite` / `host`) must belong to the org, except for `source: \"chat-client\"` events. Answers `true` when recorded (or already recorded in the last 30 seconds), `false` when ignored.\n\nVisits from bots, crawlers, scanners and uptime probes, requests for files or probe paths (assets, `.env`, `wp-*`, `_next`, `static/chunks`), local development hosts, internal IPs, and any IP past 60 visits a minute are dropped without error — the call answers `false`. An identical visit within 30 seconds is recorded once. Location is looked up from the IP before the row is written.\n\n#### Signature\n\n```http\nPOST /tools/web-visit-indirect (body) -> `true` recorded, `false` ignored\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Self-reported data on a public route — figures can be inflated by anyone; the filters above only stop the obvious.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SITE_NOT_FOUND | Site not found: acme-shop shop.example.com  in org acme | The site named by `configSite` / `host` does not belong to the org (not checked for `source: \"chat-client\"`). | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/web-visit-direct`\n- `GET /analytics/live-view`","tags":["Tools"],"requestBody":{"description":"The visit.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string"},"host":{"type":"string"},"configSite":{"type":"string"},"type":{"type":"string","example":"pageview"},"deviceId":{"type":"string"},"sessionId":{"type":"string"},"referrer":{"type":"string"},"source":{"type":"string"}}}}},"example":{"data":{"url":"https://shop.example.com/news/summer-gala","host":"shop.example.com","configSite":"acme-shop","type":"pageview","deviceId":"dev_7Kq2M9","sessionId":"ses_41"}}}}}}},"/tools/web-activity":{"post":{"operationId":"ToolsController_webActivity","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Nothing (empty body)"},"404":{"description":"Site not found: acme-shop in org acme — Neither `siteName` nor `domain` matches a site of the org.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"Site not found: acme-shop in org acme","path":"/tools/web-activity","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Record web activity","description":"Stores the body as a record in the org, after checking that `siteName` or `domain` names one of the org's sites. The body is written as sent — it is a full record, including its `datatype`.\n\n#### Signature\n\n```http\nPOST /tools/web-activity (body) -> Nothing (empty body)\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Public, and the body decides what is written — treat as unsafe until it is restricted to activity records.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | SITE_NOT_FOUND | Site not found: acme-shop in org acme | Neither `siteName` nor `domain` matches a site of the org. | — |\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/web-visit-indirect`","tags":["Tools"],"requestBody":{"description":"The record to store, with the site it belongs to.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","datatype":"web_visit","data":{"type":"click","url":"https://shop.example.com/pricing"}}}}}}},"/tools/create-site-favicon/{siteName}":{"post":{"operationId":"ToolsController_createSiteFavicon","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"siteName","in":"path","required":true,"description":"Site name.","schema":{"type":"string"},"example":"acme-shop"}],"responses":{"201":{"description":"The favicon","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate a site favicon","description":"Produces a favicon for a site from its branding.\n\n#### Signature\n\n```http\nPOST /tools/create-site-favicon/{siteName} (siteName: string, body) -> The favicon\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/create-page-image/{siteName}/{pageName}`","tags":["Tools"],"requestBody":{"description":"Options.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}}},"/tools/fake-generate":{"post":{"operationId":"ToolsController_generateFakeData","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"What was generated","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate fake data","description":"Produces synthetic records for a data type — for populating a demo or testing a UI.\n\nIt writes real records into the org, so pointing it at production creates data that has to be cleaned up afterwards.\n\n#### Signature\n\n```http\nPOST /tools/fake-generate (body) -> What was generated\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Writes records into the org.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/default-templates`","tags":["Tools"],"requestBody":{"description":"What to generate.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"datatype":"customer","count":25}}}}}},"/tools/domain/search/{domainName}/{tld}":{"get":{"operationId":"ToolsController_domainSearch","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domainName","required":true,"in":"path","schema":{"type":"string"},"description":"Name to check, without the TLD.","example":"acme"},{"name":"tld","required":true,"in":"path","schema":{"type":"string"},"description":"TLD. Optional.","example":"com"},{"name":"suggest","required":false,"in":"query","schema":{"type":"boolean"},"description":"Include alternative suggestions.","example":true},{"name":"provider","required":false,"in":"query","schema":{"type":"string"},"example":"namecheap"}],"responses":{"200":{"description":"Availability and suggestions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search for a domain","description":"Checks a domain's availability with the registrar, optionally returning suggestions. `tld` is an optional second segment; `provider` selects the registrar when more than one is configured.\n\n#### Signature\n\n```http\nGET /tools/domain/search/{domainName}/{tld} (domainName: string, tld: string, suggest?: boolean, provider?: string) -> Availability and suggestions\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/search/advanced`","tags":["Tools"]}},"/tools/domain/search/advanced":{"post":{"operationId":"ToolsController_domainSearchAdvanced","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"Availability and suggestions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Search domains across TLDs","description":"Checks several keywords against several TLDs in one call, with suggestions capped by `maxSuggestions` (default 50). Each keyword × TLD is a registrar lookup, so a wide search is a slow one.\n\n#### Signature\n\n```http\nPOST /tools/domain/search/advanced (body) -> Availability and suggestions\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/buy`","tags":["Tools"],"requestBody":{"description":"The search.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["keywords"],"properties":{"keywords":{"description":"One keyword or several.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"example":["acme","acmeshop"]},"tlds":{"type":"array","items":{"type":"string"},"example":["com","io"]},"includeSuggestions":{"type":"boolean","description":"Default true.","example":true},"maxSuggestions":{"type":"integer","description":"Default 50.","example":50},"provider":{"type":"string","example":"namecheap"}}},"example":{"keywords":["acme","acmeshop"],"tlds":["com","io"],"maxSuggestions":20}}}}}},"/tools/domain/dns/add":{"post":{"operationId":"ToolsController_addDNSRecord","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Add a DNS record","description":"Adds a record to a domain's zone. Live DNS: a wrong record can send traffic somewhere else or break mail delivery, and propagation means the mistake outlives the fix by the record's TTL.\n\n#### Signature\n\n```http\nPOST /tools/domain/dns/add (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Changes live DNS.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/dns/modify`","tags":["Tools"],"requestBody":{"description":"The record.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","example":"ORD-4821"},"domain":{"type":"string","example":"example.com"},"type":{"type":"string","example":"A"},"name":{"type":"string","example":"www"},"values":{"type":"array","items":{"type":"string"},"example":["203.0.113.10"]},"provider":{"type":"string","example":"namecheap"}}},"example":{"domain":"example.com","type":"A","name":"www","values":["203.0.113.10"]}}}}}},"/tools/domain/dns/modify":{"post":{"operationId":"ToolsController_modifyDNSRecord","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Modify a DNS record","description":"Changes an existing DNS record. Same caution as adding one — this is live resolution, and MX or A record mistakes are outages.\n\n#### Signature\n\n```http\nPOST /tools/domain/dns/modify (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Changes live DNS.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/dns/delete`","tags":["Tools"],"requestBody":{"description":"The record change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"example.com","type":"A","name":"www","values":["203.0.113.11"]}}}}}},"/tools/domain/dns/delete":{"post":{"operationId":"ToolsController_deleteDNSRecord","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Delete a DNS record","description":"Removes a DNS record. Deleting an A or MX record takes a site or its mail off the internet immediately — read the zone first.\n\n#### Signature\n\n```http\nPOST /tools/domain/dns/delete (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Removes live DNS resolution.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/dns/{domainName}/{type}`","tags":["Tools"],"requestBody":{"description":"Which record.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"example.com","type":"A","name":"www"}}}}}},"/tools/domain/dns/{domainName}/{type}":{"get":{"operationId":"ToolsController_getDNSRecords","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domainName","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"},{"name":"type","required":true,"in":"path","schema":{"type":"string"},"description":"Record type — `A`, `CNAME`, `MX`. Optional.","example":"A"},{"name":"provider","required":false,"in":"query","schema":{"type":"string"},"example":"namecheap"}],"responses":{"200":{"description":"DNS records","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get DNS records","description":"The DNS records for a domain, optionally narrowed to one record type.\n\n#### Signature\n\n```http\nGET /tools/domain/dns/{domainName}/{type} (domainName: string, type: string, provider?: string) -> DNS records\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/dns/add`","tags":["Tools"]}},"/tools/domain/buy":{"post":{"operationId":"ToolsController_domainBuy","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The registration order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Buy a domain","description":"Registers a domain with the registrar. **This spends money** and the registration is generally non-refundable — a typo in the domain name buys the typo.\n\nOn a public route, so treat access to this endpoint as the only control preventing arbitrary registrations against the account.\n\n#### Signature\n\n```http\nPOST /tools/domain/buy (body) -> The registration order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Spends money; non-refundable.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/list/{domainName}/{orderId}`","tags":["Tools"],"requestBody":{"description":"What to register.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"acme.com","years":1,"provider":"namecheap"}}}}}},"/tools/domain/list/{domainName}/{orderId}":{"get":{"operationId":"ToolsController_domainList","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domainName","required":true,"in":"path","schema":{"type":"string"},"description":"Optional domain filter.","example":"example.com"},{"name":"orderId","required":true,"in":"path","schema":{"type":"string"},"description":"Optional order filter.","example":"ORD-4821"},{"name":"provider","required":false,"in":"query","schema":{"type":"string"},"example":"namecheap"}],"responses":{"200":{"description":"Domains or the order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List domains or get an order","description":"Lists registered domains; both path segments are optional, narrowing to one domain or one registration order.\n\n#### Signature\n\n```http\nGET /tools/domain/list/{domainName}/{orderId} (domainName: string, orderId: string, provider?: string) -> Domains or the order\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/manage`","tags":["Tools"]}},"/tools/domain/manage":{"post":{"operationId":"ToolsController_domainManage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Manage a domain","description":"Registrar-side management — locks, auto-renew, contacts, nameservers. Changing nameservers moves where the domain resolves, which takes effect globally as caches expire.\n\n#### Signature\n\n```http\nPOST /tools/domain/manage (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Nameserver changes affect live resolution.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/dns/{domainName}/{type}`","tags":["Tools"],"requestBody":{"description":"The management action.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"example.com","action":"setNameservers","nameservers":["ns1.example.net","ns2.example.net"]}}}}}},"/tools/presentation/to-pdf":{"post":{"operationId":"ToolsController_pageToPdf","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The PDF result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Convert a page to PDF","description":"Renders a page to PDF. Rendering is slow — expect seconds, not milliseconds.\n\n#### Signature\n\n```http\nPOST /tools/presentation/to-pdf (body) -> The PDF result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/presentation/to-pptx`","tags":["Tools"],"requestBody":{"description":"What to convert.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","pageName":"deck"}}}}}},"/tools/presentation/to-pptx":{"post":{"operationId":"ToolsController_pageToPptx","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The PPTX result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Convert a page to PowerPoint","description":"Renders a page to a PPTX deck.\n\n#### Signature\n\n```http\nPOST /tools/presentation/to-pptx (body) -> The PPTX result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/presentation/to-pdf`","tags":["Tools"],"requestBody":{"description":"What to convert.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"siteName":"acme-shop","pageName":"deck"}}}}}},"/tools/presentation/publish":{"post":{"operationId":"ToolsController_hostHtmlPresentation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The hosted presentation and its URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Publish an HTML presentation","description":"Hosts an HTML presentation at a shareable URL. **The published page is publicly reachable** by anyone with the link — do not publish anything confidential.\n\n#### Signature\n\n```http\nPOST /tools/presentation/publish (body) -> The hosted presentation and its URL\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Publishes to a public URL.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/presentation/unpublish`","tags":["Tools"],"requestBody":{"description":"The presentation.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"q3-review","html":"<html>…</html>"}}}}}},"/tools/presentation/unpublish":{"post":{"operationId":"ToolsController_removeHostedPresentation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Unpublish a hosted presentation","description":"Removes a hosted presentation, so its URL stops resolving. Anyone who already downloaded it keeps their copy.\n\n#### Signature\n\n```http\nPOST /tools/presentation/unpublish (body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/presentation/publish`","tags":["Tools"],"requestBody":{"description":"Which presentation.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"q3-review"}}}}}},"/tools/email-templates":{"get":{"operationId":"ToolsController_listEmailTemplates","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List default email templates","description":"The platform's built-in email templates — the registry an org customises from, not the org's own overrides.\n\n#### Signature\n\n```http\nGET /tools/email-templates () -> Templates\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/email-templates/{name}`","tags":["Tools"]}},"/tools/email-templates/{name}":{"get":{"operationId":"ToolsController_getEmailTemplate","parameters":[{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Template name.","example":"booking-confirmation"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a default email template","description":"One built-in email template by name, with its body.\n\n#### Signature\n\n```http\nGET /tools/email-templates/{name} (name: string) -> The template\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/email-templates`","tags":["Tools"]}},"/tools/remove-background":{"post":{"operationId":"ToolsController_removeBackground","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The processed image","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Remove an image background by URL","description":"Fetches an image by URL and returns it with the background removed.\n\nThe server fetches whatever URL it is given, which on a public route makes this usable to probe hosts the server can reach — treat the URL as untrusted input.\n\n#### Signature\n\n```http\nPOST /tools/remove-background (body) -> The processed image\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Server-side fetch of a caller-supplied URL.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/remove-background-file`","tags":["Tools"],"requestBody":{"description":"The image URL.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"url":"https://cdn.example.com/product.jpg"}}}}}},"/tools/remove-background-file":{"post":{"operationId":"ToolsController_removeBackgroundFromFile","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The processed image","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Remove an image background from an upload","description":"Takes an uploaded image as `multipart/form-data` under the field name `file` and returns it with the background removed. The safer of the two forms, since nothing is fetched by the server.\n\n#### Signature\n\n```http\nPOST /tools/remove-background-file (body) -> The processed image\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/remove-background`","tags":["Tools"],"requestBody":{"description":"Multipart form with a `file` field.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}}}},"/tools/domain/cloudflare/zone/create":{"post":{"operationId":"ToolsController_createCloudflareZone","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The zone, with its nameservers","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a Cloudflare zone","description":"Creates a zone in Cloudflare for a domain. The zone is not live until the domain's nameservers point at the ones Cloudflare issues.\n\n#### Signature\n\n```http\nPOST /tools/domain/cloudflare/zone/create (body) -> The zone, with its nameservers\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/cloudflare/zone/{domain}/nameservers`","tags":["Tools"],"requestBody":{"description":"The domain.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"example.com"}}}}}},"/tools/domain/cloudflare/zone/{domain}":{"get":{"operationId":"ToolsController_getCloudflareZone","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"}],"responses":{"200":{"description":"The zone","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get a Cloudflare zone","description":"The zone record for a domain.\n\n#### Signature\n\n```http\nGET /tools/domain/cloudflare/zone/{domain} (domain: string) -> The zone\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/cloudflare/zone/{domain}/activation`","tags":["Tools"]}},"/tools/domain/cloudflare/zone/{domain}/activation":{"get":{"operationId":"ToolsController_checkCloudflareActivation","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"}],"responses":{"200":{"description":"Activation status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Check Cloudflare zone activation","description":"Whether Cloudflare has seen the domain's nameservers change and activated the zone. Activation is what makes proxying and SSL start working, and it is not instant.\n\n#### Signature\n\n```http\nGET /tools/domain/cloudflare/zone/{domain}/activation (domain: string) -> Activation status\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/cloudflare/zone/{domain}/nameservers`","tags":["Tools"]}},"/tools/domain/cloudflare/zone/{domain}/nameservers":{"post":{"operationId":"ToolsController_updateCloudflareNameservers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update Cloudflare nameservers","description":"Points the domain's nameservers at Cloudflare. This is the switch that moves DNS authority; until caches expire, both the old and new answers circulate.\n\n#### Signature\n\n```http\nPOST /tools/domain/cloudflare/zone/{domain}/nameservers (domain: string, body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Moves DNS authority for the domain.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/cloudflare/zone/{domain}/activation`","tags":["Tools"],"requestBody":{"description":"The nameservers.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{}}}}},"get":{"operationId":"ToolsController_getCloudflareNameservers","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"}],"responses":{"200":{"description":"The nameservers","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get Cloudflare nameservers","description":"The nameservers Cloudflare assigned to the zone — what has to be set at the registrar for the zone to activate.\n\n#### Signature\n\n```http\nGET /tools/domain/cloudflare/zone/{domain}/nameservers (domain: string) -> The nameservers\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/manage`","tags":["Tools"]}},"/tools/domain/cloudflare/transfer":{"post":{"operationId":"ToolsController_transferToCloudflare","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The transfer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Transfer a domain to Cloudflare","description":"Starts a registrar transfer into Cloudflare. Transfers are slow, need an auth code, and are refused inside 60 days of registration — check the status endpoint rather than expecting an immediate result.\n\n#### Signature\n\n```http\nPOST /tools/domain/cloudflare/transfer (body) -> The transfer\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Registrar transfer — slow and gated by registry rules.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/cloudflare/transfer/{domain}`","tags":["Tools"],"requestBody":{"description":"The transfer.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"example.com","authCode":"<auth code>"}}}}}},"/tools/domain/cloudflare/transfer/{domain}":{"get":{"operationId":"ToolsController_getCloudflareTransferStatus","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"}],"responses":{"200":{"description":"Transfer status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get Cloudflare transfer status","description":"Where a registrar transfer has got to.\n\n#### Signature\n\n```http\nGET /tools/domain/cloudflare/transfer/{domain} (domain: string) -> Transfer status\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/cloudflare/transfer`","tags":["Tools"]}},"/tools/domain/cloudflare/ssl/{domain}":{"get":{"operationId":"ToolsController_getCloudflareSSL","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"}],"responses":{"200":{"description":"SSL settings","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Get Cloudflare SSL settings","description":"The zone's SSL mode and certificate state.\n\n#### Signature\n\n```http\nGET /tools/domain/cloudflare/ssl/{domain} (domain: string) -> SSL settings\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/cloudflare/ssl/{domain}`","tags":["Tools"]},"post":{"operationId":"ToolsController_setCloudflareSSL","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"domain","required":true,"in":"path","schema":{"type":"string"},"description":"Domain name.","example":"example.com"}],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Update Cloudflare SSL settings","description":"Changes the zone's SSL mode. Getting this wrong breaks the site for every visitor at once — `full (strict)` against an origin with no valid certificate returns errors to everyone, and `flexible` in front of an HTTPS origin can loop.\n\n#### Signature\n\n```http\nPOST /tools/domain/cloudflare/ssl/{domain} (domain: string, body) -> The result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- A wrong mode breaks the site immediately.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `GET /tools/domain/cloudflare/ssl/{domain}`","tags":["Tools"],"requestBody":{"description":"The SSL setting.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"mode":"full"}}}}}},"/tools/domain/cloudflare/dns/import":{"post":{"operationId":"ToolsController_importCloudflareDNS","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"201":{"description":"The import result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Import DNS records into Cloudflare","description":"Bulk-imports records into a zone, typically from an existing provider's export. Import before switching nameservers — importing afterwards leaves a window where records are missing and the domain half-resolves.\n\n#### Signature\n\n```http\nPOST /tools/domain/cloudflare/dns/import (body) -> The import result\n```\n\n#### Access\n\nPublic — no credentials required.\n\n#### Notes\n\n- Unauthenticated — the entire `tools` controller is a public route.\n- Import before the nameserver switch, not after.\n\n#### Errors\n\nPlus the standard platform errors: `429`, `500`.\n\n#### See also\n\n- `POST /tools/domain/cloudflare/zone/{domain}/nameservers`","tags":["Tools"],"requestBody":{"description":"The records to import.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"domain":"example.com","records":[{"type":"A","name":"www","content":"203.0.113.10"}]}}}}}},"/usage/shared":{"get":{"operationId":"UsageController_getSharedUsage","summary":"Get shared services used by this org","description":"Every shared platform service: whether this org runs it on the shared account or its own (`account`), whether its agreement is accepted, and what it was charged in the window (default: this month). Our cost and margin are not included.\n\n#### Signature\n\n```http\nGET /usage/shared (from?: string, to?: string) -> Shared service usage\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/statement`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"from","required":false,"in":"query","description":"Start (ISO date). Default: start of this month.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End (ISO date). Default: now.","schema":{"type":"string"}}],"responses":{"200":{"description":"Shared service usage","content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string"},"period":{"type":"object","additionalProperties":true},"balance":{"type":"number"},"totals":{"type":"object","properties":{"charged":{"type":"number"},"count":{"type":"number"}}},"services":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"unitName":{"type":"string"},"pricingDisplay":{"type":"string"},"account":{"type":"string","nullable":true,"description":"shared or own, per provider."},"agreementAccepted":{"type":"boolean"},"count":{"type":"number"},"quantity":{"type":"number"},"charged":{"type":"number"},"lastUsedAt":{"type":"string","nullable":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/admin/service-usage":{"get":{"operationId":"UsageController_serviceUsage","summary":"Get service usage across the platform","description":"Who used the shared services in the window, from the charges each org recorded: platform totals (billed, our cost, margin), each service across all orgs, each org (searched, sorted, paged), the daily trend, uses with no cost recorded, refusals, and orgs using a service without its agreement.\n\n#### Signature\n\n```http\nGET /usage/admin/service-usage (from?: string, to?: string, q?: string, service?: string, sort?: string, dir?: string, page?: integer, pageSize?: integer) -> { period, totals, services, trend, orgs: { total, page, pageSize, data } }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | — | Service usage across organizations is only available to the platform (root or shared) organization. | The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one. | — |\n| `400` | — | from and to must be ISO dates | `from`/`to` do not parse, or `from` is after `to` (\"from must be before to\"). | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer"}},{"name":"dir","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"sort","required":false,"in":"query","schema":{"type":"string","enum":["name","uses","billed","cost","margin","uncosted","balance","refused","lastUsedAt"]}},{"name":"service","required":false,"in":"query","description":"Only orgs that used this service.","schema":{"type":"string"}},{"name":"q","required":false,"in":"query","description":"Org name or id contains.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End (ISO date). Default: now.","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Start (ISO date). Default: start of this month.","schema":{"type":"string"}}],"responses":{"200":{"description":"{ period, totals, services, trend, orgs: { total, page, pageSize, data } }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"from and to must be ISO dates — `from`/`to` do not parse, or `from` is after `to` (\"from must be before to\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"from and to must be ISO dates","path":"/usage/admin/service-usage","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Service usage across organizations is only available to the platform (root or shared) organization. — The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Service usage across organizations is only available to the platform (root or shared) organization.","path":"/usage/admin/service-usage","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Platform admin"]}},"/usage/admin/credits":{"get":{"operationId":"UsageController_credits","summary":"List every organization’s credit","description":"Each org’s balance (dollars), plan, status, what it was billed for shared services this month and when it last used one — searched, sorted and paged by the server — with platform totals.\n\n#### Signature\n\n```http\nGET /usage/admin/credits (q?: string, filter?: string, sort?: string, dir?: string, page?: integer, pageSize?: integer) -> { month, totals: { credit, owed, billedThisMonth, … }, total, page, pageSize, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | — | Service usage across organizations is only available to the platform (root or shared) organization. | The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer"}},{"name":"dir","required":false,"in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"sort","required":false,"in":"query","schema":{"type":"string","enum":["name","plan","balance","billedThisMonth","usesThisMonth","lastUsedAt","createdAt"]}},{"name":"filter","required":false,"in":"query","schema":{"type":"string","enum":["with-credit","no-credit","using"]}},{"name":"q","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ month, totals: { credit, owed, billedThisMonth, … }, total, page, pageSize, data }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Service usage across organizations is only available to the platform (root or shared) organization. — The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Service usage across organizations is only available to the platform (root or shared) organization.","path":"/usage/admin/credits","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Platform admin"]}},"/usage/admin/service-usage/orgs/{orgId}":{"get":{"operationId":"UsageController_orgServiceUsage","summary":"Get one organization’s service usage","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgId","required":true,"in":"path","description":"Organization to read.","schema":{"type":"string"},"example":"org_4821"},{"name":"from","required":false,"in":"query","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ orgId, name, balance, period, totals: { uses, billed, cost, margin, uncosted, refused, servicesUsed }, services, … }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"from and to must be ISO dates — `from`/`to` do not parse, or `from` is after `to` (\"from must be before to\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"from and to must be ISO dates","path":"/usage/admin/service-usage/orgs/{orgId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Service usage across organizations is only available to the platform (root or shared) organization. — The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Service usage across organizations is only available to the platform (root or shared) organization.","path":"/usage/admin/service-usage/orgs/{orgId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No organization \"<orgId>\" — The org does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No organization \"<orgId>\"","path":"/usage/admin/service-usage/orgs/{orgId}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Platform admin"],"description":"For one org: every catalog service with whether it runs on the shared account or its own, its agreement, uses, our cost, billed and margin, plus its trend and refusals.\n\n#### Signature\n\n```http\nGET /usage/admin/service-usage/orgs/{orgId} (orgId: string, from?: string, to?: string) -> { orgId, name, balance, period, totals: { uses, billed, cost, margin, uncosted, refused, servicesUsed }, services, … }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | — | Service usage across organizations is only available to the platform (root or shared) organization. | The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one. | — |\n| `400` | — | from and to must be ISO dates | `from`/`to` do not parse, or `from` is after `to` (\"from must be before to\"). | — |\n| `404` | — | No organization \"<orgId>\" | The org does not exist. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/admin/service-usage/orgs/{orgId}/charges`"}},"/usage/admin/service-usage/orgs/{orgId}/charges":{"get":{"operationId":"UsageController_orgServiceCharges","summary":"List one organization’s charges","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgId","required":true,"in":"path","description":"Organization to read.","schema":{"type":"string"},"example":"org_4821"},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer"}},{"name":"service","required":false,"in":"query","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ orgId, period, page, pageSize, total, data }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"from and to must be ISO dates — `from`/`to` do not parse, or `from` is after `to` (\"from must be before to\").","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"from and to must be ISO dates","path":"/usage/admin/service-usage/orgs/{orgId}/charges","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Service usage across organizations is only available to the platform (root or shared) organization. — The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"Service usage across organizations is only available to the platform (root or shared) organization.","path":"/usage/admin/service-usage/orgs/{orgId}/charges","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Platform admin"],"description":"The org’s individual service charges in the window, newest first, paged.\n\n#### Signature\n\n```http\nGET /usage/admin/service-usage/orgs/{orgId}/charges (orgId: string, from?: string, to?: string, service?: string, page?: integer, pageSize?: integer) -> { orgId, period, page, pageSize, total, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootSystem`, `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | — | Service usage across organizations is only available to the platform (root or shared) organization. | The caller is signed in to any org other than the root or shared org — a tenant ConfigAdmin passes the role check but not this one. | — |\n| `400` | — | from and to must be ISO dates | `from`/`to` do not parse, or `from` is after `to` (\"from must be before to\"). | — |\n\nPlus the standard platform errors: `401`, `429`, `500`."}},"/usage/endpoints":{"get":{"operationId":"UsageController_getTokenizedEndpoints","summary":"List tokenized endpoints","description":"Every endpoint that consumes tokens, with its cost. The table behind what a call charges an org.\n\n#### Signature\n\n```http\nGET /usage/endpoints () -> Endpoints and their costs\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /usage/endpoints`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Endpoints and their costs","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]},"post":{"operationId":"UsageController_setEndpointCost","summary":"Set an endpoint cost","description":"Sets the token cost for an endpoint. Affects pricing for every organization, not just the caller. A cost set too high starts refusing calls for orgs with small balances; too low, and usage stops being paid for.\n\n#### Signature\n\n```http\nPOST /usage/endpoints (body) -> Confirmation\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Affects pricing for every organization, not just the caller.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /usage/endpoints/{endpoint}`","parameters":[{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"The endpoint and its cost.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["endpoint","cost"],"properties":{"endpoint":{"type":"string","example":"POST /ai/chat"},"cost":{"type":"number","description":"Tokens per call.","example":10}}},"example":{"endpoint":"POST /ai/chat","cost":10}}}},"responses":{"201":{"description":"Confirmation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"message":"Cost for POST /ai/chat set to 10 tokens"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/endpoints/{endpoint}":{"delete":{"operationId":"UsageController_removeEndpoint","summary":"Remove an endpoint from tokenization","description":"Stops charging for an endpoint — it becomes free for every organization. Affects pricing for every organization, not just the caller.\n\n#### Signature\n\n```http\nDELETE /usage/endpoints/{endpoint} (endpoint: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Affects pricing for every organization, not just the caller.\n- Makes the endpoint free platform-wide.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/endpoints`","parameters":[{"name":"endpoint","required":true,"in":"path","description":"The endpoint identifier.","schema":{"type":"string"},"example":"POST%20%2Fai%2Fchat"},{"name":"orgid","in":"header","required":true,"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/stats":{"get":{"operationId":"UsageController_getUsageStats","summary":"Get usage records","description":"The org's usage records (`usage`), optionally within a date range on `data.timestamp`, in the repository's paged list shape. `all=true` drops the org scope.\n\n#### Signature\n\n```http\nGET /usage/stats (startDate?: string, endDate?: string, all?: boolean) -> Paged usage records\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- `all=true` is not restricted to operators: any signed-in caller can pass it.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/statement`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"startDate","required":false,"in":"query","description":"ISO date.","schema":{"type":"string"},"example":"2026-08-01"},{"name":"endDate","required":false,"in":"query","schema":{"type":"string"},"example":"2026-08-31"},{"name":"all","required":false,"in":"query","schema":{"type":"boolean"},"description":"Read without the org scope.","example":false}],"responses":{"200":{"description":"Paged usage records","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/statement":{"get":{"operationId":"UsageController_getStatement","summary":"Get the organization statement","description":"Every change to the balance in the window (default: the last 30 days), newest first and labelled with what each charge was for. Back-to-back charges for the same service are one row. `breakdown` totals spending by service. Amounts are full precision.\n\n#### Signature\n\n```http\nGET /usage/statement (from?: string, to?: string) -> The statement\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | — | from/to must be ISO dates | `from` or `to` does not parse. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/balance`\n- `GET /usage/shared`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"from","required":false,"in":"query","description":"Start (ISO date).","schema":{"type":"string"},"example":"2026-09-01"},{"name":"to","required":false,"in":"query","description":"End (ISO date). Default: now.","schema":{"type":"string"},"example":"2026-09-30"}],"responses":{"200":{"description":"The statement","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"balance":{"type":"number","nullable":true},"totals":{"type":"object","properties":{"spent":{"type":"number"},"credited":{"type":"number"},"charges":{"type":"number"}}},"breakdown":{"type":"array","items":{"type":"object","additionalProperties":true}},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"from/to must be ISO dates — `from` or `to` does not parse.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"from/to must be ISO dates","path":"/usage/statement","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/spend-controls":{"get":{"operationId":"UsageController_getSpendControls","summary":"Spend controls (Account › Plan limits): the monthly spend limit, this month's spend, the spend notifications, the last Contact sales request","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Usage"]},"post":{"operationId":"UsageController_saveSpendControls","summary":"Change the monthly spend limit (0 = none) and/or the spend notifications [{ id?, amount, emails? }]. Owner or admin.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Usage"]}},"/usage/contact-sales":{"post":{"operationId":"UsageController_contactSales","summary":"Contact sales: { topic: higher_limits | custom_plan | billing_question | other, message, phone? }. Saved as a lead for the sales team; the sender gets a confirmation email.","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization ID","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Usage"]}},"/usage/balance":{"get":{"operationId":"UsageController_getBalance","summary":"Get the organization balance","description":"The org's credit balance (dollars), its spend rate (the multiplier applied to every charge), plan, whether it is active, and any promotion it qualifies for. Check it before a bulk AI job — a run that exhausts the balance part-way leaves the work half done.\n\n#### Signature\n\n```http\nGET /usage/balance () -> The balance\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Without the `orgid` header it answers `{ success: false, error: 'Missing orgid header' }` with status 200.\n- The response includes the full company record.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/statement`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The balance","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"number"},"spendRate":{"type":"number"},"plan":{"type":"string"},"active":{"type":"boolean"},"orgId":{"type":"string"},"promotions":{"type":"array","items":{"type":"object","additionalProperties":true}},"company":{"type":"object","additionalProperties":true}}},"example":{"balance":42.18,"spendRate":1,"plan":"pro","active":true,"orgId":"org_4821","promotions":[]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/ai/provider-key":{"get":{"operationId":"UsageController_getAIProviderKey","summary":"Get an AI provider key and balance","description":"Returns the API key for an AI provider along with the org's balance, so a client can call the provider directly.\n\n**This hands out a provider credential.** Anything holding it can spend against that provider outside this platform's accounting — treat the response as a secret and prefer the server-side `/ai/*` endpoints where possible.\n\n#### Signature\n\n```http\nGET /usage/ai/provider-key (provider?: string) -> { success, orgId, provider, apiKey, balance, spendRate, plan, active }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Returns a live provider credential.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /usage/ai/charge`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"provider","required":true,"in":"query","description":"openai, anthropic, gemini, deepseek…","schema":{"type":"string"},"example":"openai"}],"responses":{"200":{"description":"{ success, orgId, provider, apiKey, balance, spendRate, plan, active }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/ai/models":{"get":{"operationId":"UsageController_getSupportedModels","summary":"List AI models and pricing","description":"Supported models and what each costs — read this to work out what a job will cost before running it.\n\n#### Signature\n\n```http\nGET /usage/ai/models () -> Models and pricing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /usage/ai/charge`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"Models and pricing","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/ai/charge":{"post":{"operationId":"UsageController_chargeAiUsage","summary":"Charge AI usage","description":"Records AI consumption and **deducts it from the org's balance**. Token models are charged on `promptTokens` and `completionTokens`; image models on `imageCount` and `imageQuality` tiers. The org's spend rate is applied on top.\n\nCall it **after** a successful provider call, not before — charging for a call that failed bills the customer for nothing. It is also not idempotent: calling it twice for one completion charges twice.\n\n#### Signature\n\n```http\nPOST /usage/ai/charge (body) -> The charge result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- Deducts real balance. Not idempotent.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/balance`","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"requestBody":{"description":"What was consumed.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","model"],"properties":{"provider":{"type":"string","example":"openai"},"model":{"type":"string","example":"gpt-5"},"promptTokens":{"type":"number","example":1200},"completionTokens":{"type":"number","example":800},"imageCount":{"type":"number","description":"Image models.","example":2},"imageQuality":{"type":"string","enum":["low","medium","high"],"description":"Image models.","example":"medium"},"metadata":{"type":"object","additionalProperties":true}}},"examples":{"tokens":{"summary":"A token model","value":{"provider":"openai","model":"gpt-5","promptTokens":1200,"completionTokens":800}},"images":{"summary":"An image model","value":{"provider":"openai","model":"gpt-image-2","imageCount":2,"imageQuality":"medium"}}}}}},"responses":{"201":{"description":"The charge result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/gift":{"post":{"operationId":"UsageController_giftCredit","summary":"Gift credit to another organization","description":"Moves `amount` of the calling org's balance to `toOrg`: the caller is debited, the recipient credited, and a `gift_deduction` transaction is recorded on the caller. Nothing is created from nothing — the caller must hold the amount.\n\n#### Signature\n\n```http\nPOST /usage/gift (body) -> { success, message }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- A refused gift (amount ≤ 0, same org, unknown org, insufficient balance) is not an error: it answers `success: false`.\n- `notes` is recorded as who gifted it (`giftedBy`), and the transaction's own notes stay empty.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/balance`","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"requestBody":{"description":"The gift.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","toOrg"],"properties":{"amount":{"type":"number"},"toOrg":{"type":"string"},"notes":{"type":"string"}}},"example":{"toOrg":"org_4821","amount":20,"notes":"Trial extension"}}}},"responses":{"201":{"description":"{ success, message }","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"]}},"/usage/{orgId}/current/{type}":{"get":{"operationId":"UsageController_getCurrentUsage","parameters":[{"name":"orgId","required":true,"in":"path","schema":{"type":"string"},"description":"Org to read.","example":"org_4821"},{"name":"type","required":true,"in":"path","schema":{"type":"string"},"description":"Usage type. Optional.","example":"ai"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"}],"responses":{"200":{"description":"{ orgId, type, usage: [{ year, month, count }] }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"],"summary":"Get an organization's usage counts","description":"Usage counts for a named org over the last six months, optionally for one usage type — the same data as usage history, despite the name. The path org is explicit, so a caller with content read permission can read any org.\n\n#### Signature\n\n```http\nGET /usage/{orgId}/current/{type} (orgId: string, type: string) -> { orgId, type, usage: [{ year, month, count }] }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/history/{type}`"}},"/usage/history/{type}":{"get":{"operationId":"UsageController_getUsageHistory","parameters":[{"name":"orgid","required":true,"in":"header","schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"type","required":true,"in":"path","schema":{"type":"string"},"description":"Usage type. Optional.","example":"ai"},{"name":"months","required":false,"in":"query","schema":{"type":"integer","default":6},"example":6}],"responses":{"200":{"description":"{ orgId, type, history: [{ year, month, count }] }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage"],"summary":"Get usage history","description":"Usage counts for each of the last `months` months, optionally for one usage type. Requires content read permission.\n\n#### Signature\n\n```http\nGET /usage/history/{type} (type: string, months?: integer) -> { orgId, type, history: [{ year, month, count }] }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Notes\n\n- The route reads the org from a path parameter it does not declare, so `orgId` is empty and the counts are not scoped as intended; every month also reports the same all-time count.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/statement`"}},"/service-pricing/initialize":{"post":{"operationId":"ServicePricingController_initializeDefaults","summary":"Initialize default service pricing","parameters":[],"responses":{"201":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"Seeds the default pricing catalogue. Intended for a fresh platform — run against a populated catalogue it may overwrite deliberate pricing decisions, so check what exists first.\n\n#### Signature\n\n```http\nPOST /service-pricing/initialize () -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Notes\n\n- Can overwrite existing pricing.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /service-pricing/list`"}},"/service-pricing/providers":{"get":{"operationId":"ServicePricingController_providers","summary":"The providers that have service pricing, for the list filter","parameters":[],"responses":{"200":{"description":""}},"tags":["Service Pricing"]}},"/service-pricing/list":{"get":{"operationId":"ServicePricingController_list","summary":"List service pricing","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string"},"example":"active"},{"name":"provider","required":false,"in":"query","schema":{"type":"string"},"example":"openai"}],"responses":{"200":{"description":"Service pricing","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"Every priced service, optionally filtered by provider.\n\n#### Signature\n\n```http\nGET /service-pricing/list (provider?: string, status?: string) -> Service pricing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /service-pricing/active`"}},"/service-pricing":{"post":{"operationId":"ServicePricingController_create","summary":"Create service pricing","parameters":[],"responses":{"201":{"description":"The pricing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"Adds a priced service to the catalogue. Affects pricing for every organization, not just the caller.\n\n#### Signature\n\n```http\nPOST /service-pricing (body) -> The pricing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Notes\n\n- Affects pricing for every organization, not just the caller.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /service-pricing/{name}`","requestBody":{"description":"The pricing.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"ai-chat","provider":"openai","cost":10}}}}}},"/service-pricing/{name}":{"put":{"operationId":"ServicePricingController_update","summary":"Update service pricing","parameters":[{"name":"name","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"ai-chat"}],"responses":{"200":{"description":"The updated pricing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"Changes a service's price. Takes effect on the next call — it does not re-rate usage already charged, and every organization sees the new price at once.\n\n#### Signature\n\n```http\nPUT /service-pricing/{name} (name: string, body) -> The updated pricing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Notes\n\n- Affects pricing for every organization, not just the caller.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /service-pricing/list`","requestBody":{"description":"Fields to change.","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"cost":12}}}}},"delete":{"operationId":"ServicePricingController_delete","summary":"Delete service pricing","parameters":[{"name":"name","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"ai-chat"}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"Removes a service's pricing. Anything that charges for it loses its price — check what depends on the entry before deleting it.\n\n#### Signature\n\n```http\nDELETE /service-pricing/{name} (name: string) -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Notes\n\n- Affects pricing for every organization, not just the caller.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /service-pricing/all`"}},"/service-pricing/all":{"delete":{"operationId":"ServicePricingController_deleteAll","summary":"Delete all service pricing","parameters":[],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"**Empties the entire pricing catalogue** for every organization. Nothing is priced afterwards, so charging stops working platform-wide until the catalogue is rebuilt.\n\nThere is no confirmation and no undo. Almost certainly not what you want — delete a single entry instead.\n\n#### Signature\n\n```http\nDELETE /service-pricing/all () -> The result\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `RootAdmin`, `RootPowerUser`, `ConfigAdmin`.\n\n#### Notes\n\n- Destroys the whole catalogue platform-wide. No undo.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `DELETE /service-pricing/{name}`\n- `POST /service-pricing/initialize`"}},"/service-pricing/active":{"get":{"operationId":"ServicePricingController_getActiveServices","summary":"Get active services","parameters":[],"responses":{"200":{"description":"Active services","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"The services currently priced and available.\n\n#### Signature\n\n```http\nGET /service-pricing/active () -> Active services\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /service-pricing/catalog`"}},"/service-pricing/catalog":{"get":{"operationId":"ServicePricingController_getServicesCatalog","summary":"Get the services catalog","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"}],"responses":{"200":{"description":"The catalog","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"The catalogue as it applies to an organization — what it can use and at what price.\n\n#### Signature\n\n```http\nGET /service-pricing/catalog () -> The catalog\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /service-pricing/check-balance/{service}`"}},"/service-pricing/check-balance/{service}":{"get":{"operationId":"ServicePricingController_checkBalance","summary":"Check the balance for a service","parameters":[{"name":"orgid","required":true,"in":"header","description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","schema":{"type":"string"},"example":"acme-retail"},{"name":"service","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"ai-chat"},{"name":"amount","required":true,"in":"query","schema":{"type":"number"},"description":"Amount needed, in dollars. Unparseable values count as 0.","example":2.5}],"responses":{"200":{"description":"{ sufficient, balance }","content":{"application/json":{"schema":{"type":"object","properties":{"sufficient":{"type":"boolean"},"balance":{"type":"number"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"Whether the org's balance covers `amount` right now — the pre-flight check before starting work that would fail part-way for lack of balance. When it does not, the org's admins are sent an insufficient-credit alert (throttled).\n\n#### Signature\n\n```http\nGET /service-pricing/check-balance/{service} (service: string, amount?: number) -> { sufficient, balance }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /usage/balance`"}},"/service-pricing/{service}":{"get":{"operationId":"ServicePricingController_get","summary":"Get service pricing","parameters":[{"name":"service","required":true,"in":"path","description":"Service name.","schema":{"type":"string"},"example":"ai-chat"}],"responses":{"200":{"description":"The pricing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["Usage · Service pricing"],"description":"The price of one service.\n\n#### Signature\n\n```http\nGET /service-pricing/{service} (service: string) -> The pricing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`).\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /service-pricing/{name}`"}},"/ai-employees/me/hello":{"post":{"operationId":"AIEmployeeController_hello","summary":"Say hello from its runtime","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"{ ok, you, status, next }","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"you":{"type":"string","description":"Its title."},"status":{"type":"string"},"next":{"type":"string","example":"GET /ai-employees/me/briefing"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"This is for AI employees, signed in as themselves. — The caller is not an AI employee's own user.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This is for AI employees, signed in as themselves.","path":"/ai-employees/me/hello","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"The AI employee, once running and signed in as itself, says what runs it. This is the proof from its side that it exists and can reach the platform; it marks the employee connected and is shown on its setup checklist.\n\n#### Signature\n\n```http\nPOST /ai-employees/me/hello (body) -> { ok, you, status, next }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `AI (the employee itself)`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | AI_EMPLOYEE_ONLY | This is for AI employees, signed in as themselves. | The caller is not an AI employee's own user. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `GET /ai-employees/me/briefing`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"agentId":{"type":"string"},"model":{"type":"string"},"version":{"type":"string"}}},"example":{"provider":"session-manager","agentId":"ag_4821","model":"claude-sonnet-5","version":"1.4.0"}}}}}},"/ai-employees/me/briefing":{"get":{"operationId":"AIEmployeeController_briefing","summary":"Get its briefing","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The briefing","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"identity":{"type":"object","additionalProperties":true},"functions":{"type":"object","properties":{"api":{"type":"string"},"reference":{"type":"string"},"everything":{"type":"string"}}},"company":{"type":"object","additionalProperties":true},"knowledge":{"type":"object","additionalProperties":true},"status":{"type":"string"},"work":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":true},"open":{"type":"array","items":{"type":"object","additionalProperties":true}},"waitingOnAPerson":{"type":"array","items":{"type":"object","additionalProperties":true}},"recentDecisions":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"now":{"type":"object","properties":{"iso":{"type":"string"},"local":{"type":"string"},"timezone":{"type":"string"}}},"notes":{"type":"array","items":{"type":"object","additionalProperties":true}},"team":{"type":"object","additionalProperties":true},"meetings":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"This is for AI employees, signed in as themselves. — The caller is not an AI employee's own user.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"This is for AI employees, signed in as themselves.","path":"/ai-employees/me/briefing","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No AI employee uses this sign-in. — The signed-in AI user belongs to no employee (it was removed).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee uses this sign-in.","path":"/ai-employees/me/briefing","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Everything the employee needs on every sign-in and job, current: who it is (identity, supervisor, what it listens to, its approval policy, its phone numbers and voice), the company and its knowledge, its instructions (platform, org, its own job description), where to find the API reference, where its work stands (open jobs, what waits on a person, recent decisions), the time where it works, its own notes, the AI team workspace and its meetings in the next day.\n\n#### Signature\n\n```http\nGET /ai-employees/me/briefing () -> The briefing\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `AI (the employee itself)`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `403` | AI_EMPLOYEE_ONLY | This is for AI employees, signed in as themselves. | The caller is not an AI employee's own user. | — |\n| `404` | NO_EMPLOYEE_FOR_SIGN_IN | No AI employee uses this sign-in. | The signed-in AI user belongs to no employee (it was removed). | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /ai-employees/worker/{name}/lease`"}},"/ai-employees/worker/{name}/summary":{"get":{"operationId":"AIEmployeeController_summary","summary":"What an employee did over a period","description":"For its reports: job counts by outcome, approvals asked / approved / rejected / waiting, cost, check-ins (pings), and each job it finished. Pings on which it did nothing are not counted as work. An AI employee may call this only for itself.\n\n#### Signature\n\n```http\nGET /ai-employees/worker/{name}/summary (name: string, since?: string) -> { since, until, counts, approvals, costUsd, pings, items }\n```\n\n#### Access\n\nRequires either a bearer JWT or an API key. Required role(s): `System`, `AI (for its own jobs)`, `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `403` | NOT_OWN_JOB | An AI employee can only work on its own jobs. | An AI employee called this for another employee or another employee's job. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"},{"name":"since","required":false,"in":"query","description":"ISO date-time; default 24 hours ago.","schema":{"type":"string"},"example":"2026-09-28T00:00:00Z"}],"responses":{"200":{"description":"{ since, until, counts, approvals, costUsd, pings, items }","content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string"},"until":{"type":"string"},"counts":{"type":"object","properties":{"done":{"type":"integer"},"failed":{"type":"integer"},"cancelled":{"type":"integer"},"waitingApproval":{"type":"integer"},"queued":{"type":"integer"},"inProgress":{"type":"integer"}}},"approvals":{"type":"object","properties":{"asked":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"},"waiting":{"type":"integer"}}},"costUsd":{"type":"number"},"pings":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"result":{"type":"string"},"finishedAt":{"type":"string"},"costUsd":{"type":"number"},"ref":{"type":"object","additionalProperties":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"An AI employee can only work on its own jobs. — An AI employee called this for another employee or another employee's job.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"An AI employee can only work on its own jobs.","path":"/ai-employees/worker/{name}/summary","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/worker/{name}/summary","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"]}},"/ai-employees/worker/{name}/lease":{"post":{"operationId":"AIEmployeeController_lease","summary":"Lease the next job","description":"The runtime asks for the employee's next job. The platform decides when it works: when it is not active, off shift, over today's budget, at its concurrency limit, or has nothing queued, the answer is `{ job: null, reason }` (still a success). A job this worker already held and was interrupted on is handed back first; otherwise in-progress work whose lease lapsed, then queued work by priority (high, normal, low), oldest first. A queued job that has used its attempts is failed and the next one is tried.\n\nA lease lasts 15 minutes and is extended by each step reported. The answer carries the job, the employee's profile and approval policy, the company context and the budget left today.\n\n#### Signature\n\n```http\nPOST /ai-employees/worker/{name}/lease (name: string, body) -> The leased job, or `{ job: null, reason }`\n```\n\n#### Access\n\nRequires either a bearer JWT or an API key. Required role(s): `System`, `AI (for its own jobs)`, `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `403` | NOT_OWN_JOB | An AI employee can only work on its own jobs. | An AI employee called this for another employee or another employee's job. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /ai-employees/worker/work/{id}/step`\n- `POST /ai-employees/worker/work/{id}/complete`","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"The leased job, or `{ job: null, reason }`","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}},"nullable":true},"reason":{"type":"string","description":"Only when `job` is null: why nothing was leased."},"leaseUntil":{"type":"string","format":"date-time"},"organization":{"type":"object","nullable":true,"properties":{"company":{"type":"object","additionalProperties":true},"knowledge":{"type":"object","additionalProperties":true},"escalation":{"type":"object","additionalProperties":true}}},"employee":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"jobTitle":{"type":"string"},"jobDescription":{"type":"string"},"supervisor":{"type":"string","nullable":true},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"runtime":{"type":"object","additionalProperties":true},"remainingBudgetUsd":{"type":"number","nullable":true}}}}},"examples":{"idle":{"summary":"Nothing to do","value":{"job":null,"reason":"Outside its working hours."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"An AI employee can only work on its own jobs. — An AI employee called this for another employee or another employee's job.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"An AI employee can only work on its own jobs.","path":"/ai-employees/worker/{name}/lease","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/worker/{name}/lease","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"worker":{"type":"string","description":"Which runtime process holds the lease. Defaults to the caller's identity."}}},"example":{"worker":"runner-1"}}}}}},"/ai-employees/worker/work/{id}/step":{"post":{"operationId":"AIEmployeeController_step","summary":"Report a step on a job","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"201":{"description":"The job with the new step","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"400":{"description":"A step needs text. — `text` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"A step needs text.","path":"/ai-employees/worker/work/{id}/step","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"An AI employee can only work on its own jobs. — An AI employee called this for another employee or another employee's job.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"An AI employee can only work on its own jobs.","path":"/ai-employees/worker/work/{id}/step","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/worker/work/{id}/step","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This job is queued, not in progress. — The job is not in progress (queued, waiting for approval, or finished).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This job is queued, not in progress.","path":"/ai-employees/worker/work/{id}/step","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Adds a step to the job's timeline and extends the lease by 15 minutes. `costUsd` is added to the job's cost (and counts against today's budget). An unknown `kind` is recorded as `note`.\n\n#### Signature\n\n```http\nPOST /ai-employees/worker/work/{id}/step (id: string, body) -> The job with the new step\n```\n\n#### Access\n\nRequires either a bearer JWT or an API key. Required role(s): `System`, `AI (for its own jobs)`, `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n| `403` | NOT_OWN_JOB | An AI employee can only work on its own jobs. | An AI employee called this for another employee or another employee's job. | — |\n| `409` | JOB_NOT_IN_PROGRESS | This job is queued, not in progress. | The job is not in progress (queued, waiting for approval, or finished). | Lease it first. |\n| `400` | STEP_TEXT_REQUIRED | A step needs text. | `text` is missing. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"worker":{"type":"string","description":"Which runtime process holds the lease. Defaults to the caller's identity."},"kind":{"type":"string","enum":["note","thinking","action","check","screen","error"],"default":"note"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"costUsd":{"type":"number","minimum":0}}},"example":{"kind":"action","text":"Replied to the customer with the delivery date.","costUsd":0.012}}}}}},"/ai-employees/worker/work/{id}/approval":{"post":{"operationId":"AIEmployeeController_requestApproval","summary":"Ask for approval before an action","description":"The runtime asks before an action its policy may reserve for a person. Answered at once with `{ allowed: true }` when the employee's approval policy allows the action, or when the same request was already approved (on this job, or on another job in the last day — for money, up to the amount approved). Otherwise the job waits: status `waiting_approval`, lease released, `{ allowed: false, waiting: true }`. It is leased back with the decision in its steps once a person decides. `other` (or any unknown action) always needs a person.\n\n#### Signature\n\n```http\nPOST /ai-employees/worker/work/{id}/approval (id: string, body) -> `{ allowed: true, approvedBy? }` or `{ allowed: false, waiting: true }`\n```\n\n#### Access\n\nRequires either a bearer JWT or an API key. Required role(s): `System`, `AI (for its own jobs)`, `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n| `403` | NOT_OWN_JOB | An AI employee can only work on its own jobs. | An AI employee called this for another employee or another employee's job. | — |\n| `409` | JOB_NOT_IN_PROGRESS | This job is queued, not in progress. | The job is not in progress (queued, waiting for approval, or finished). | Lease it first. |\n| `400` | SUMMARY_REQUIRED | Say what it wants to do (summary). | `summary` is missing. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.\n\n#### See also\n\n- `POST /ai-employees/work/{id}/decide`","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"201":{"description":"`{ allowed: true, approvedBy? }` or `{ allowed: false, waiting: true }`","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean"},"approvedBy":{"type":"string"},"waiting":{"type":"boolean"}}}}}},"400":{"description":"Say what it wants to do (summary). — `summary` is missing.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Say what it wants to do (summary).","path":"/ai-employees/worker/work/{id}/approval","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"An AI employee can only work on its own jobs. — An AI employee called this for another employee or another employee's job.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"An AI employee can only work on its own jobs.","path":"/ai-employees/worker/work/{id}/approval","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/worker/work/{id}/approval","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This job is queued, not in progress. — The job is not in progress (queued, waiting for approval, or finished).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This job is queued, not in progress.","path":"/ai-employees/worker/work/{id}/approval","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["summary"],"properties":{"worker":{"type":"string","description":"Which runtime process holds the lease. Defaults to the caller's identity."},"action":{"type":"string","enum":["delete","bulkSend","calls","money","usersAndPermissions","other"],"default":"other"},"summary":{"type":"string","description":"What it wants to do, in words a person can decide on."},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"}}},"example":{"action":"money","summary":"Refund order #1043 ($42.50) — the item arrived broken.","amountUsd":42.5}}}}}},"/ai-employees/worker/work/{id}/complete":{"post":{"operationId":"AIEmployeeController_complete","summary":"Finish a job","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"201":{"description":"The finished job","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"An AI employee can only work on its own jobs. — An AI employee called this for another employee or another employee's job.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"An AI employee can only work on its own jobs.","path":"/ai-employees/worker/work/{id}/complete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/worker/work/{id}/complete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This job is queued, not in progress. — The job is not in progress (queued, waiting for approval, or finished).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This job is queued, not in progress.","path":"/ai-employees/worker/work/{id}/complete","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Marks the job done with its result and releases the lease. `costUsd` is added to the job's cost. A ping on which it took an action is retitled \"On its own: <first line of the result>\" and counted as work.\n\n#### Signature\n\n```http\nPOST /ai-employees/worker/work/{id}/complete (id: string, body) -> The finished job\n```\n\n#### Access\n\nRequires either a bearer JWT or an API key. Required role(s): `System`, `AI (for its own jobs)`, `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n| `403` | NOT_OWN_JOB | An AI employee can only work on its own jobs. | An AI employee called this for another employee or another employee's job. | — |\n| `409` | JOB_NOT_IN_PROGRESS | This job is queued, not in progress. | The job is not in progress (queued, waiting for approval, or finished). | Lease it first. |\n\nPlus the standard platform errors: `401`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"worker":{"type":"string","description":"Which runtime process holds the lease. Defaults to the caller's identity."},"result":{"type":"string"},"costUsd":{"type":"number","minimum":0}}},"example":{"result":"Confirmed the reservation for 7pm and emailed the guest.","costUsd":0.03}}}}}},"/ai-employees/worker/work/{id}/fail":{"post":{"operationId":"AIEmployeeController_fail","summary":"Report a failed attempt","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"201":{"description":"The job — queued again, or failed","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"An AI employee can only work on its own jobs. — An AI employee called this for another employee or another employee's job.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"An AI employee can only work on its own jobs.","path":"/ai-employees/worker/work/{id}/fail","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/worker/work/{id}/fail","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This job is queued, not in progress. — The job is not in progress (queued, waiting for approval, or finished).","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This job is queued, not in progress.","path":"/ai-employees/worker/work/{id}/fail","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"A failed attempt goes back in the queue until the job has used the employee's `limits.maxAttempts`; then (or with `retry: false`) the job is failed with the error.\n\n#### Signature\n\n```http\nPOST /ai-employees/worker/work/{id}/fail (id: string, body) -> The job — queued again, or failed\n```\n\n#### Access\n\nRequires either a bearer JWT or an API key. Required role(s): `System`, `AI (for its own jobs)`, `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n| `403` | NOT_OWN_JOB | An AI employee can only work on its own jobs. | An AI employee called this for another employee or another employee's job. | — |\n| `409` | JOB_NOT_IN_PROGRESS | This job is queued, not in progress. | The job is not in progress (queued, waiting for approval, or finished). | Lease it first. |\n\nPlus the standard platform errors: `401`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"worker":{"type":"string","description":"Which runtime process holds the lease. Defaults to the caller's identity."},"error":{"type":"string"},"retry":{"type":"boolean","default":true},"costUsd":{"type":"number","minimum":0}}},"example":{"error":"The customer record is locked by another user."}}}}}},"/ai-employees/config":{"get":{"operationId":"AIEmployeeController_getConfig","summary":"Get the org's AI employee settings","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"{ config, from, isPlatform }","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","additionalProperties":true},"from":{"type":"object","additionalProperties":{"type":"string","enum":["org","platform","none"]}},"isPlatform":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"The settings in force, section by section (`company`, `knowledge`, `defaults`, `escalation`): the org's own, else the platform's (the shared org's), else empty — and where each came from.\n\n#### Signature\n\n```http\nGET /ai-employees/config () -> { config, from, isPlatform }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."},"put":{"operationId":"AIEmployeeController_saveConfig","summary":"Save the org's AI employee settings","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The settings in force after saving (as GET)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"\"owner@\" is not an email address. — An escalation contact that is not an email, whenStuck not ask/fail/pause, a knowledge source without a valid type or reference (a url that is not http(s)), a knowledge entry without title or content, an unknown timezone, `system` from an org other than the platform, or minutes out of range. Every problem is listed, joined; the body also carries `problems[]`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"\"owner@\" is not an email address.","path":"/ai-employees/config","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Saves the sections sent; a section sent as `null` goes back to inheriting; a section left out is untouched. `system` (unclaimed and handling minutes) is the platform's only — the shared org may set it. Check-ins are not a setting here: they are the `ai-employee-ping` scheduled job, which pings every switched-on employee once per run and stamps its `lastPingAt`. It runs every 5 minutes per org by default; the org reads and changes how often with GET/PUT /jobs/scheduled/ai-employee-ping.\n\n#### Signature\n\n```http\nPUT /ai-employees/config (body) -> The settings in force after saving (as GET)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | AI_EMPLOYEE_INVALID | \"owner@\" is not an email address. | An escalation contact that is not an email, whenStuck not ask/fail/pause, a knowledge source without a valid type or reference (a url that is not http(s)), a knowledge entry without title or content, an unknown timezone, `system` from an org other than the platform, or minutes out of range. Every problem is listed, joined; the body also carries `problems[]`. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","additionalProperties":true},"knowledge":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"sourceType":{"type":"string","enum":["collection","document","url","custom"]},"reference":{"type":"string"}}}},"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"}}}}}},"defaults":{"type":"object","description":"Defaults for new hires: runtime, workingHours, limits, approvals."},"escalation":{"type":"object","properties":{"contact":{"type":"string","format":"email"},"whenStuck":{"type":"string","enum":["ask","fail","pause"]}}},"system":{"type":"object","properties":{"unclaimedMinutes":{"type":"integer","minimum":1},"handlingMinutes":{"type":"integer","minimum":5}}}}},"example":{"escalation":{"contact":"owner@example.com","whenStuck":"ask"},"knowledge":null}}}}}},"/ai-employees/templates":{"get":{"operationId":"AIEmployeeController_templates","summary":"List templates to hire from","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"{ data, isPlatform }","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sk":{"type":"string"},"source":{"type":"string","enum":["platform","org"],"description":"platform: the shared org's, read-only here. org: this org's own."},"name":{"type":"string"},"title":{"type":"string"},"category":{"type":"string","enum":["front-desk","sales","support","finance","marketing","operations","other"]},"icon":{"type":"string"},"summary":{"type":"string"},"jobTitle":{"type":"string"},"jobDescription":{"type":"string"},"suggestedGroups":{"type":"array","items":{"type":"string"}},"listensTo":{"type":"array","items":{"type":"string"}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"avatar":{"type":"string"}}}},"isPlatform":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Every template this org can hire from in one list: the platform's (the shared org's — read-only here: use it or copy it) and the org's own. Sorted by category and title.\n\n#### Signature\n\n```http\nGET /ai-employees/templates () -> { data, isPlatform }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai-employees`"},"put":{"operationId":"AIEmployeeController_saveTemplate","summary":"Save one of the org's templates","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The saved template","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Give the template a name. Give the template a title. — No name/title. Every problem is listed, joined; the body also carries `problems[]`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Give the template a name. Give the template a title.","path":"/ai-employees/templates","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"An AI employee is already called \"night-desk\". Give the template another name. — An employee has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"An AI employee is already called \"night-desk\". Give the template another name.","path":"/ai-employees/templates","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Creates or changes one of the org's own templates (in the shared org: one of the platform's). Only template fields are kept. An org saving a new template under a platform template's name gets a `-copy` name instead of shadowing it.\n\n#### Signature\n\n```http\nPUT /ai-employees/templates (body) -> The saved template\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | AI_EMPLOYEE_INVALID | Give the template a name. Give the template a title. | No name/title. Every problem is listed, joined; the body also carries `problems[]`. | — |\n| `409` | NAME_TAKEN_BY_EMPLOYEE | An AI employee is already called \"night-desk\". Give the template another name. | An employee has that handle. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sk":{"type":"string"},"source":{"type":"string","enum":["platform","org"],"description":"platform: the shared org's, read-only here. org: this org's own."},"name":{"type":"string"},"title":{"type":"string"},"category":{"type":"string","enum":["front-desk","sales","support","finance","marketing","operations","other"]},"icon":{"type":"string"},"summary":{"type":"string"},"jobTitle":{"type":"string"},"jobDescription":{"type":"string"},"suggestedGroups":{"type":"array","items":{"type":"string"}},"listensTo":{"type":"array","items":{"type":"string"}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"avatar":{"type":"string"}}},"example":{"title":"Night desk","category":"front-desk","jobTitle":"Night receptionist","listensTo":["chat_queue","sms"]}}}}}},"/ai-employees/templates/{name}":{"get":{"operationId":"AIEmployeeController_template","summary":"Get one template","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Template name.","example":"front-desk"}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object","properties":{"sk":{"type":"string"},"source":{"type":"string","enum":["platform","org"],"description":"platform: the shared org's, read-only here. org: this org's own."},"name":{"type":"string"},"title":{"type":"string"},"category":{"type":"string","enum":["front-desk","sales","support","finance","marketing","operations","other"]},"icon":{"type":"string"},"summary":{"type":"string"},"jobTitle":{"type":"string"},"jobDescription":{"type":"string"},"suggestedGroups":{"type":"array","items":{"type":"string"}},"listensTo":{"type":"array","items":{"type":"string"}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"avatar":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No template \"front-desk\" — Neither the org nor the platform has a template by that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No template \"front-desk\"","path":"/ai-employees/templates/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"One template by name; the org's own wins over the platform's of the same name.\n\n#### Signature\n\n```http\nGET /ai-employees/templates/{name} (name: string) -> The template\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TEMPLATE_NOT_FOUND | No template \"front-desk\" | Neither the org nor the platform has a template by that name. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."},"delete":{"operationId":"AIEmployeeController_deleteTemplate","summary":"Delete one of the org's templates","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"Template name.","example":"night-desk"}],"responses":{"200":{"description":"{ deleted }","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"This organization has no template \"night-desk\" of its own to delete. — No template of the org's own by that name.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"This organization has no template \"night-desk\" of its own to delete.","path":"/ai-employees/templates/{name}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Deletes one of the org's own templates. The platform's are not the org's to delete.\n\n#### Signature\n\n```http\nDELETE /ai-employees/templates/{name} (name: string) -> { deleted }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | TEMPLATE_NOT_FOUND | This organization has no template \"night-desk\" of its own to delete. | No template of the org's own by that name. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/instructions":{"get":{"operationId":"AIEmployeeController_instructions","summary":"Get the org's instructions to its AI employees","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"{ data, platform, isPlatform }","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"enabled":{"type":"boolean","default":true},"who":{"type":"string","enum":["all","only","except"],"default":"all"},"employees":{"type":"array","items":{"type":"string"},"description":"Handles, for only / except."},"order":{"type":"integer","readOnly":true}}}},"platform":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"enabled":{"type":"boolean","default":true},"who":{"type":"string","enum":["all","only","except"],"default":"all"},"employees":{"type":"array","items":{"type":"string"},"description":"Handles, for only / except."},"order":{"type":"integer","readOnly":true}}}},"isPlatform":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"The instructions the org gives its AI employees, in order. The platform's own system instructions also apply to every employee but are shown only in the shared org (`platform` is empty elsewhere).\n\n#### Signature\n\n```http\nGET /ai-employees/instructions () -> { data, platform, isPlatform }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /ai-employees/{name}/instructions`"},"put":{"operationId":"AIEmployeeController_saveInstructions","summary":"Replace the org's instructions","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The instructions after saving (as GET)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Send the instructions as a list. — `instructions` is not an array.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Send the instructions as a list.","path":"/ai-employees/instructions","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Replaces the whole list, in the order given. Each employee the change affects is told which instruction is new, changed or no longer applies to it (in its next briefing). In the shared org these are the platform's system instructions.\n\n#### Signature\n\n```http\nPUT /ai-employees/instructions (body) -> The instructions after saving (as GET)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | INSTRUCTIONS_NOT_A_LIST | Send the instructions as a list. | `instructions` is not an array. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["instructions"],"properties":{"instructions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"enabled":{"type":"boolean","default":true},"who":{"type":"string","enum":["all","only","except"],"default":"all"},"employees":{"type":"array","items":{"type":"string"},"description":"Handles, for only / except."},"order":{"type":"integer","readOnly":true}}}}}},"example":{"instructions":[{"title":"Refunds","content":"Never promise a refund; ask for approval with the order number.","who":"all"},{"title":"Spanish","content":"Answer in Spanish when the customer writes in Spanish.","who":"only","employees":["ava"]}]}}}}}},"/ai-employees/team":{"get":{"operationId":"AIEmployeeController_getTeam","summary":"Get the AI team workspace","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"{ workspace }","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"title":{"type":"string"},"isPrivate":{"type":"boolean"},"memberCount":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"The org's AI team workspace — where its AI employees get goals, tasks and meetings, report, and ask for approvals. Made by the first hire.\n\n#### Signature\n\n```http\nGET /ai-employees/team () -> { workspace }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."},"put":{"operationId":"AIEmployeeController_setTeam","summary":"Set the AI team workspace","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"{ workspace } (as GET)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Choose a workspace, not a conversation. — The id is missing or is a conversation.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Choose a workspace, not a conversation.","path":"/ai-employees/team","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Uses the workspace given (one the caller can see), or makes a new private one when none is given. Every AI employee and the caller are added to it.\n\n#### Signature\n\n```http\nPUT /ai-employees/team (body) -> { workspace } (as GET)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | NOT_A_WORKSPACE | Choose a workspace, not a conversation. | The id is missing or is a conversation. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string"}}},"example":{"workspaceId":"6710c0ffee0000000000beef"}}}}}},"/ai-employees/work":{"get":{"operationId":"AIEmployeeController_listWork","summary":"List work items","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"source","required":false,"in":"query","schema":{"type":"string","enum":["assigned","ping","direct","message","call","config"]}},{"name":"pings","required":false,"in":"query","schema":{"type":"boolean","default":false}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"integer","default":25},"description":"Up to 200."},{"name":"page","required":false,"in":"query","schema":{"type":"integer","default":1}},{"name":"q","required":false,"in":"query","schema":{"type":"string"},"description":"Text in the title."},{"name":"status","required":false,"in":"query","description":"Comma-separated statuses.","schema":{"type":"string"},"example":"queued,in_progress"},{"name":"employee","required":false,"in":"query","schema":{"type":"string"},"description":"Handle."}],"responses":{"200":{"description":"{ page, pageSize, total, data }","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"data":{"type":"array","items":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Work across employees, most recently changed first. Pings on which the employee did nothing are left out unless `pings=true`.\n\n#### Signature\n\n```http\nGET /ai-employees/work (employee?: string, status?: string, q?: string, source?: string, pings?: boolean, page?: integer, pageSize?: integer) -> { page, pageSize, total, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/work/approvals":{"get":{"operationId":"AIEmployeeController_approvals","summary":"List what waits for an approval","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"{ total, data }","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"data":{"type":"array","items":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Every work item waiting for a person to approve, oldest first (up to 200).\n\n#### Signature\n\n```http\nGET /ai-employees/work/approvals () -> { total, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai-employees/work/{id}/decide`"}},"/ai-employees/work/{id}":{"get":{"operationId":"AIEmployeeController_getWork","summary":"Get a work item","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"200":{"description":"The work item","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/work/{id}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"One work item with its full timeline. Attached records are described from the records themselves.\n\n#### Signature\n\n```http\nGET /ai-employees/work/{id} (id: string) -> The work item\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/work/{id}/decide":{"post":{"operationId":"AIEmployeeController_decide","summary":"Approve or reject a request","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"201":{"description":"The work item","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"400":{"description":"decision must be \"approved\" or \"rejected\". — `decision` is anything else.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"decision must be \"approved\" or \"rejected\".","path":"/ai-employees/work/{id}/decide","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"An AI employee cannot decide approvals. — The caller is an AI employee.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":403,"error":"An AI employee cannot decide approvals.","path":"/ai-employees/work/{id}/decide","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/work/{id}/decide","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"This work is not waiting for an approval. — The job is not `waiting_approval`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"This work is not waiting for an approval.","path":"/ai-employees/work/{id}/decide","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"A person's answer to what the employee asked permission for. The job goes back to its runtime either way (in progress, unleased) with the decision in its steps. The same request waiting on the employee's other jobs (same action, summary and amount) gets the same answer.\n\n#### Signature\n\n```http\nPOST /ai-employees/work/{id}/decide (id: string, body) -> The work item\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | DECISION_INVALID | decision must be \"approved\" or \"rejected\". | `decision` is anything else. | — |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n| `403` | AI_CANNOT_DECIDE | An AI employee cannot decide approvals. | The caller is an AI employee. | — |\n| `409` | NOT_WAITING | This work is not waiting for an approval. | The job is not `waiting_approval`. | — |\n\nPlus the standard platform errors: `401`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approved","rejected"]},"note":{"type":"string"}}},"example":{"decision":"approved","note":"Fine — refund to the original card."}}}}}},"/ai-employees/work/{id}/cancel":{"post":{"operationId":"AIEmployeeController_cancel","summary":"Cancel a work item","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"201":{"description":"The cancelled work item","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/work/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"It is already done. — The job is done, failed or cancelled.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"It is already done.","path":"/ai-employees/work/{id}/cancel","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"#### Signature\n\n```http\nPOST /ai-employees/work/{id}/cancel (id: string) -> The cancelled work item\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n| `409` | ALREADY_FINISHED | It is already done. | The job is done, failed or cancelled. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/work/{id}/retry":{"post":{"operationId":"AIEmployeeController_retry","summary":"Put failed or cancelled work back in the queue","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"Work item id (`ai_employee_work` sk).","example":"6710c0ffee0000000000abcd"}],"responses":{"201":{"description":"The queued work item","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No such work item — No `ai_employee_work` has that id.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No such work item","path":"/ai-employees/work/{id}/retry","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Only failed or cancelled work can be retried. — The job is queued, in progress, waiting or done.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Only failed or cancelled work can be retried.","path":"/ai-employees/work/{id}/retry","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Queues the job again with its attempts reset and its error cleared.\n\n#### Signature\n\n```http\nPOST /ai-employees/work/{id}/retry (id: string) -> The queued work item\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | WORK_NOT_FOUND | No such work item | No `ai_employee_work` has that id. | — |\n| `409` | NOT_RETRYABLE | Only failed or cancelled work can be retried. | The job is queued, in progress, waiting or done. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees":{"get":{"operationId":"AIEmployeeController_list","summary":"List AI employees","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"{ totals, data }","content":{"application/json":{"schema":{"type":"object","properties":{"totals":{"type":"object","properties":{"employees":{"type":"integer"},"active":{"type":"integer"},"queued":{"type":"integer"},"inProgress":{"type":"integer"},"waitingApproval":{"type":"integer"},"spentTodayUsd":{"type":"number"}}},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"jobTitle":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","active","paused"]},"runtime":{"type":"string","enum":["stub","session-manager","external"]},"supervisor":{"type":"string","nullable":true},"connection":{"type":"object","additionalProperties":true,"description":"When its runtime was first and last heard from, and whether it is connected now."},"queue":{"type":"object","additionalProperties":{"type":"integer"},"description":"Work counts by status."},"spentTodayUsd":{"type":"number"},"budgetEnabled":{"type":"boolean"},"dailyBudgetUsd":{"type":"number","nullable":true,"description":"Today's budget including credit; null when the budget is off."},"budgetToday":{"type":"object","properties":{"creditUsd":{"type":"number"},"resetAt":{"type":"string","nullable":true}}},"onShift":{"type":"boolean"},"idleReason":{"type":"string","nullable":true,"description":"Why it takes no work now, e.g. \"Outside its working hours.\" — null when it can work."},"activity":{"type":"object","nullable":true,"properties":{"text":{"type":"string"},"at":{"type":"string"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Every AI employee (templates excluded) with its queue, spend today, whether it is on shift, why it is idle, and totals across all of them.\n\n#### Signature\n\n```http\nGET /ai-employees () -> { totals, data }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."},"post":{"operationId":"AIEmployeeController_create","summary":"Hire an AI employee","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"The created employee","content":{"application/json":{"schema":{"type":"object","description":"An AI employee (`ai_employee`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","readOnly":true}}}}}}}},"400":{"description":"Give it a name people will call it (title). — No title; handle characters; a supervisor that is not an email; unknown listensTo channels; voice platform/voice/greeting/eagerness/speakingSpeed/tools invalid; unknown timezone. Every problem is listed, joined; the body also carries `problems[]`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Give it a name people will call it (title).","path":"/ai-employees","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No template \"front-desk\" — The named template does not exist.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No template \"front-desk\"","path":"/ai-employees","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"There is already an AI employee called \"ava\". Choose another handle. — An employee or template has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"There is already an AI employee called \"ava\". Choose another handle.","path":"/ai-employees","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Creates the employee and the user it works as (`<name>@<orgId>.ai-employee.local`, no password, locked until switched on, in the `AI` group only). It starts from the org's defaults, then the `template` if one is named, then what is sent. It starts as `draft`: give it groups (`PUT /ai-employees/{name}/access`) and switch it on. Its supervisor gets a direct conversation with it, and it joins (or creates) the AI team workspace with the person who hired it.\n\n#### Signature\n\n```http\nPOST /ai-employees (body) -> The created employee\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | AI_EMPLOYEE_INVALID | Give it a name people will call it (title). | No title; handle characters; a supervisor that is not an email; unknown listensTo channels; voice platform/voice/greeting/eagerness/speakingSpeed/tools invalid; unknown timezone. Every problem is listed, joined; the body also carries `problems[]`. | — |\n| `404` | TEMPLATE_NOT_FOUND | No template \"front-desk\" | The named template does not exist. | — |\n| `409` | HANDLE_TAKEN | There is already an AI employee called \"ava\". Choose another handle. | An employee or template has that handle. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /ai-employees/templates`\n- `PUT /ai-employees/{name}/access`\n- `POST /ai-employees/{name}/switch-on`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","description":"Template name to start from."}}},"example":{"title":"Ava","template":"front-desk","supervisor":"owner@example.com","listensTo":["chat_queue","sms"],"workingHours":{"alwaysOn":false,"timezone":"America/Chicago","days":["mon","tue","wed","thu","fri"],"start":"08:00","end":"18:00"}}}}}}},"/ai-employees/{name}/instructions":{"get":{"operationId":"AIEmployeeController_instructionsFor","summary":"Everything an employee is told","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"200":{"description":"{ data: [{ title, content, from }] }","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"from":{"type":"string","enum":["platform","org","employee"]}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/instructions","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Its instructions in the order it gets them: the org's that apply to it (`from: org`), then its own job description (`from: employee`). The platform's system instructions come first too, but are listed only in the shared org.\n\n#### Signature\n\n```http\nGET /ai-employees/{name}/instructions (name: string) -> { data: [{ title, content, from }] }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/{name}/provision":{"post":{"operationId":"AIEmployeeController_provision","summary":"Create the agent on its provider","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"The provider status after provisioning","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"}}},"status":{"type":"object","properties":{"exists":{"type":"boolean","nullable":true},"state":{"type":"string"},"detail":{"type":"string"},"checkedAt":{"type":"string"}}},"connection":{"type":"object","additionalProperties":true,"description":"What the agent itself last reported (hello / briefing / lease / step)."}}}}}},"400":{"description":"There is no connection to the provider \"external\" yet. — The employee's `runtime.provider` has no connection here.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"There is no connection to the provider \"external\" yet.","path":"/ai-employees/{name}/provision","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/provision","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The provider refused. — The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"The provider refused.","path":"/ai-employees/{name}/provision","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["AI Employees"],"description":"Creates the agent on its runtime provider with its brief (and, for a provider that signs in as it, a fresh sign-in). `stub` records the provisioning and does no work.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/provision (name: string) -> The provider status after provisioning\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | NO_PROVIDER | There is no connection to the provider \"external\" yet. | The employee's `runtime.provider` has no connection here. | — |\n| `502` | PROVIDER_ERROR | The provider refused. | The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `GET /ai-employees/{name}/provider-status`"}},"/ai-employees/{name}/provider-status":{"get":{"operationId":"AIEmployeeController_providerStatus","summary":"Ask its provider whether the agent is running","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"200":{"description":"{ provider, status, connection }","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"}}},"status":{"type":"object","properties":{"exists":{"type":"boolean","nullable":true},"state":{"type":"string"},"detail":{"type":"string"},"checkedAt":{"type":"string"}}},"connection":{"type":"object","additionalProperties":true,"description":"What the agent itself last reported (hello / briefing / lease / step)."}}}}}},"400":{"description":"There is no connection to the provider \"external\" yet. — The employee's `runtime.provider` has no connection here.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"There is no connection to the provider \"external\" yet.","path":"/ai-employees/{name}/provider-status","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/provider-status","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"What the provider says (exists, state), beside when the agent itself was last heard from. A provider that does not answer gives `state: error` with the reason, not an HTTP error.\n\n#### Signature\n\n```http\nGET /ai-employees/{name}/provider-status (name: string) -> { provider, status, connection }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | NO_PROVIDER | There is no connection to the provider \"external\" yet. | The employee's `runtime.provider` has no connection here. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/{name}/handover/sign-in":{"post":{"operationId":"AIEmployeeController_issueSignIn","summary":"Issue a sign-in for the system that runs it","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"The sign-in, shown once","content":{"application/json":{"schema":{"type":"object","properties":{"apiBaseUrl":{"type":"string"},"orgId":{"type":"string"},"email":{"type":"string"},"password":{"type":"string"},"authenticatorSecret":{"type":"string"},"otpauthUrl":{"type":"string"},"shownOnce":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/handover/sign-in","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Its user record is missing — recreate the employee. — The employee's user was deleted.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Its user record is missing — recreate the employee.","path":"/ai-employees/{name}/handover/sign-in","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"A new password and a new authenticator secret for its user, replacing any earlier ones (earlier sign-ins stop working). Returned **once** and never stored in the clear — lose it and issue another. Give it only to the system that runs this employee; that system signs in as the employee and gets its own token.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/handover/sign-in (name: string) -> The sign-in, shown once\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Notes\n\n- Treat the response as a credential.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `409` | USER_MISSING | Its user record is missing — recreate the employee. | The employee's user was deleted. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/{name}":{"get":{"operationId":"AIEmployeeController_detail","summary":"Get an AI employee","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","description":"The employee's handle (`ai_employee.name`).","schema":{"type":"string"},"example":"ava"}],"responses":{"200":{"description":"The employee","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"jobTitle":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","active","paused"]},"runtime":{"type":"string","enum":["stub","session-manager","external"]},"supervisor":{"type":"string","nullable":true},"connection":{"type":"object","additionalProperties":true,"description":"When its runtime was first and last heard from, and whether it is connected now."},"queue":{"type":"object","additionalProperties":{"type":"integer"},"description":"Work counts by status."},"spentTodayUsd":{"type":"number"},"budgetEnabled":{"type":"boolean"},"dailyBudgetUsd":{"type":"number","nullable":true,"description":"Today's budget including credit; null when the budget is off."},"budgetToday":{"type":"object","properties":{"creditUsd":{"type":"number"},"resetAt":{"type":"string","nullable":true}}},"onShift":{"type":"boolean"},"idleReason":{"type":"string","nullable":true,"description":"Why it takes no work now, e.g. \"Outside its working hours.\" — null when it can work."},"activity":{"type":"object","nullable":true,"properties":{"text":{"type":"string"},"at":{"type":"string"}}},"setup":{"type":"array","description":"The setup checklist: created, given access, (sign-in issued, for external), provisioned, switched on, connected, first job finished.","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"done":{"type":"boolean"}}}},"record":{"type":"object","description":"An AI employee (`ai_employee`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","readOnly":true}}}}},"access":{"type":"object","nullable":true,"properties":{"userId":{"type":"string"},"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"type":"string"}},"locked":{"type":"boolean"}}},"contact":{"type":"object","properties":{"email":{"type":"string"},"phones":{"type":"array","items":{"type":"object","additionalProperties":true}},"numbers":{"type":"object","additionalProperties":true}}},"team":{"type":"object","nullable":true,"properties":{"workspaceId":{"type":"string"},"title":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"One employee: its state (as in the list), its setup checklist, its record, its user's access, its contact details and phone numbers, and the AI team workspace.\n\n#### Signature\n\n```http\nGET /ai-employees/{name} (name: string) -> The employee\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."},"put":{"operationId":"AIEmployeeController_update","summary":"Change an AI employee","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"200":{"description":"The updated employee","content":{"application/json":{"schema":{"type":"object","description":"An AI employee (`ai_employee`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","readOnly":true}}}}}}}},"400":{"description":"\"Mars/Olympus\" is not a timezone. — As on create. Every problem is listed, joined; the body also carries `problems[]`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"\"Mars/Olympus\" is not a timezone.","path":"/ai-employees/{name}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Changes its profile, hours, limits, approvals, voice and job description. `name`, `userId`, `userEmail`, `status`, `kind` and `voiceAgent` are the server's and ignored here — status changes through switch-on / pause / shut-down. `limits` and `voice` merge into what it has. The employee is told what changed in its next briefing; a new title also renames its user.\n\n#### Signature\n\n```http\nPUT /ai-employees/{name} (name: string, body) -> The updated employee\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | AI_EMPLOYEE_INVALID | \"Mars/Olympus\" is not a timezone. | As on create. Every problem is listed, joined; the body also carries `problems[]`. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","readOnly":true}}},"example":{"limits":{"dailyBudgetUsd":10},"approvals":{"money":"allow","moneyThresholdUsd":50}}}}}},"delete":{"operationId":"AIEmployeeController_remove","summary":"Remove an AI employee","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"200":{"description":"{ removed, cancelledWork, provider }","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"string"},"cancelledWork":{"type":"integer"},"provider":{"nullable":true,"description":"What the provider said on removal; null when it was never provisioned."}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}","method":"DELETE","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Takes the agent off its provider, cancels its open work, locks and deactivates its user, removes its voice agent and takes it out of the AI team workspace. Work history stays.\n\n#### Signature\n\n```http\nDELETE /ai-employees/{name} (name: string) -> { removed, cancelledWork, provider }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/{name}/phones":{"post":{"operationId":"AIEmployeeController_setPhone","summary":"Assign a phone number, or release it","description":"Gives one of the org's numbers to the employee (calls to it are then answered by it, and its outbound calls come from it), or takes it away with `assign: false`. Other people on the number keep it. The employee is told.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/phones (name: string, body) -> { phoneNumber, assigned, phones }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `409` | NO_USER | Ava has no user yet, so no number can be assigned to it. | The employee has no login identity. | — |\n| `400` | NUMBER_REQUIRED | Say which number (phoneId or phoneNumber). | Neither given. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"{ phoneNumber, assigned, phones }","content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string"},"assigned":{"type":"boolean"},"phones":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Say which number (phoneId or phoneNumber). — Neither given.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Say which number (phoneId or phoneNumber).","path":"/ai-employees/{name}/phones","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/phones","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Ava has no user yet, so no number can be assigned to it. — The employee has no login identity.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Ava has no user yet, so no number can be assigned to it.","path":"/ai-employees/{name}/phones","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneId":{"type":"string"},"phoneNumber":{"type":"string","example":"+15125550143"},"assign":{"type":"boolean","default":true},"release":{"type":"object","description":"Free the number from the AI line it is on first.","properties":{"source":{"type":"string"},"ref":{"type":"string"}}}}},"example":{"phoneNumber":"+15125550143","assign":true}}}}}},"/ai-employees/{name}/access":{"get":{"operationId":"AIEmployeeController_access","summary":"Get its access","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"200":{"description":"{ email, groups, always, available }","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"always":{"type":"array","items":{"type":"string"},"example":["AI"]},"available":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/access","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"The groups its user holds (besides `AI`, which it always has), and the org's groups it could be given (platform/Root groups never).\n\n#### Signature\n\n```http\nGET /ai-employees/{name}/access (name: string) -> { email, groups, always, available }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."},"put":{"operationId":"AIEmployeeController_setAccess","summary":"Set its access","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"200":{"description":"Its access after the change (as GET)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"groups must be a list of group names. — `groups` is not an array.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"groups must be a list of group names.","path":"/ai-employees/{name}/access","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/access","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Its user record is missing — recreate the employee. — The employee's user was deleted.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Its user record is missing — recreate the employee.","path":"/ai-employees/{name}/access","method":"PUT","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Gives its user exactly these groups (plus `AI`), through the same user service User Management uses. The employee is told its new groups.\n\n#### Signature\n\n```http\nPUT /ai-employees/{name}/access (name: string, body) -> Its access after the change (as GET)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `400` | GROUPS_NOT_A_LIST | groups must be a list of group names. | `groups` is not an array. | — |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `409` | USER_MISSING | Its user record is missing — recreate the employee. | The employee's user was deleted. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["groups"],"properties":{"groups":{"type":"array","items":{"type":"string"}}}},"example":{"groups":["FrontDesk","Reservations"]}}}}}},"/ai-employees/{name}/switch-on":{"post":{"operationId":"AIEmployeeController_switchOn","summary":"Switch it on","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"The employee (as GET)","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"jobTitle":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","active","paused"]},"runtime":{"type":"string","enum":["stub","session-manager","external"]},"supervisor":{"type":"string","nullable":true},"connection":{"type":"object","additionalProperties":true,"description":"When its runtime was first and last heard from, and whether it is connected now."},"queue":{"type":"object","additionalProperties":{"type":"integer"},"description":"Work counts by status."},"spentTodayUsd":{"type":"number"},"budgetEnabled":{"type":"boolean"},"dailyBudgetUsd":{"type":"number","nullable":true,"description":"Today's budget including credit; null when the budget is off."},"budgetToday":{"type":"object","properties":{"creditUsd":{"type":"number"},"resetAt":{"type":"string","nullable":true}}},"onShift":{"type":"boolean"},"idleReason":{"type":"string","nullable":true,"description":"Why it takes no work now, e.g. \"Outside its working hours.\" — null when it can work."},"activity":{"type":"object","nullable":true,"properties":{"text":{"type":"string"},"at":{"type":"string"}}},"setup":{"type":"array","description":"The setup checklist: created, given access, (sign-in issued, for external), provisioned, switched on, connected, first job finished.","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"done":{"type":"boolean"}}}},"record":{"type":"object","description":"An AI employee (`ai_employee`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","readOnly":true}}}}},"access":{"type":"object","nullable":true,"properties":{"userId":{"type":"string"},"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"type":"string"}},"locked":{"type":"boolean"}}},"contact":{"type":"object","properties":{"email":{"type":"string"},"phones":{"type":"array","items":{"type":"object","additionalProperties":true}},"numbers":{"type":"object","additionalProperties":true}}},"team":{"type":"object","nullable":true,"properties":{"workspaceId":{"type":"string"},"title":{"type":"string"}}}}}}}},"400":{"description":"Give Ava access first: choose at least one group for it under Access. Without one it can do nothing. — Its user has no group or role besides `AI`.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Give Ava access first: choose at least one group for it under Access. Without one it can do nothing.","path":"/ai-employees/{name}/switch-on","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/switch-on","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Its user record is missing — recreate the employee. — The employee's user was deleted.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Its user record is missing — recreate the employee.","path":"/ai-employees/{name}/switch-on","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Status `active`: it takes work, its user is unlocked, it is pinged on schedule, and a shut-down agent is started again on its provider. It needs at least one group first.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/switch-on (name: string) -> The employee (as GET)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `409` | USER_MISSING | Its user record is missing — recreate the employee. | The employee's user was deleted. | — |\n| `400` | NO_ACCESS | Give Ava access first: choose at least one group for it under Access. Without one it can do nothing. | Its user has no group or role besides `AI`. | Set its access, then switch it on. |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `PUT /ai-employees/{name}/access`"}},"/ai-employees/{name}/budget":{"post":{"operationId":"AIEmployeeController_budget","summary":"Adjust today's budget","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"The employee (as GET)","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"jobTitle":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","active","paused"]},"runtime":{"type":"string","enum":["stub","session-manager","external"]},"supervisor":{"type":"string","nullable":true},"connection":{"type":"object","additionalProperties":true,"description":"When its runtime was first and last heard from, and whether it is connected now."},"queue":{"type":"object","additionalProperties":{"type":"integer"},"description":"Work counts by status."},"spentTodayUsd":{"type":"number"},"budgetEnabled":{"type":"boolean"},"dailyBudgetUsd":{"type":"number","nullable":true,"description":"Today's budget including credit; null when the budget is off."},"budgetToday":{"type":"object","properties":{"creditUsd":{"type":"number"},"resetAt":{"type":"string","nullable":true}}},"onShift":{"type":"boolean"},"idleReason":{"type":"string","nullable":true,"description":"Why it takes no work now, e.g. \"Outside its working hours.\" — null when it can work."},"activity":{"type":"object","nullable":true,"properties":{"text":{"type":"string"},"at":{"type":"string"}}},"setup":{"type":"array","description":"The setup checklist: created, given access, (sign-in issued, for external), provisioned, switched on, connected, first job finished.","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"done":{"type":"boolean"}}}},"record":{"type":"object","description":"An AI employee (`ai_employee`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","readOnly":true}}}}},"access":{"type":"object","nullable":true,"properties":{"userId":{"type":"string"},"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"type":"string"}},"locked":{"type":"boolean"}}},"contact":{"type":"object","properties":{"email":{"type":"string"},"phones":{"type":"array","items":{"type":"object","additionalProperties":true}},"numbers":{"type":"object","additionalProperties":true}}},"team":{"type":"object","nullable":true,"properties":{"workspaceId":{"type":"string"},"title":{"type":"string"}}}}}}}},"400":{"description":"action must be \"reset\" or \"credit\". — Any other action.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"action must be \"reset\" or \"credit\".","path":"/ai-employees/{name}/budget","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/budget","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"`reset` counts spend again from now; `credit` adds `amountUsd` on top of today's budget. Both lapse at midnight in its timezone. Budget alerts can fire again after either.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/budget (name: string, body) -> The employee (as GET)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | BUDGET_ACTION_INVALID | action must be \"reset\" or \"credit\". | Any other action. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["reset","credit"]},"amountUsd":{"type":"number","description":"For credit; more than 0."}}},"examples":{"reset":{"summary":"Start today's count again","value":{"action":"reset"}},"credit":{"summary":"Add $5 for today","value":{"action":"credit","amountUsd":5}}}}}}}},"/ai-employees/{name}/pause":{"post":{"operationId":"AIEmployeeController_pause","summary":"Pause it","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"The employee (as GET)","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"jobTitle":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","active","paused"]},"runtime":{"type":"string","enum":["stub","session-manager","external"]},"supervisor":{"type":"string","nullable":true},"connection":{"type":"object","additionalProperties":true,"description":"When its runtime was first and last heard from, and whether it is connected now."},"queue":{"type":"object","additionalProperties":{"type":"integer"},"description":"Work counts by status."},"spentTodayUsd":{"type":"number"},"budgetEnabled":{"type":"boolean"},"dailyBudgetUsd":{"type":"number","nullable":true,"description":"Today's budget including credit; null when the budget is off."},"budgetToday":{"type":"object","properties":{"creditUsd":{"type":"number"},"resetAt":{"type":"string","nullable":true}}},"onShift":{"type":"boolean"},"idleReason":{"type":"string","nullable":true,"description":"Why it takes no work now, e.g. \"Outside its working hours.\" — null when it can work."},"activity":{"type":"object","nullable":true,"properties":{"text":{"type":"string"},"at":{"type":"string"}}},"setup":{"type":"array","description":"The setup checklist: created, given access, (sign-in issued, for external), provisioned, switched on, connected, first job finished.","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"done":{"type":"boolean"}}}},"record":{"type":"object","description":"An AI employee (`ai_employee`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"name":{"type":"string","description":"Handle; made from `title` when not given (lowercase, letters/numbers/-/_). Unique among employees and templates.","example":"ava"},"title":{"type":"string","description":"What people call it.","example":"Ava"},"jobTitle":{"type":"string","example":"Front desk"},"jobDescription":{"type":"string","description":"Its standing instructions (rich text)."},"supervisor":{"type":"string","description":"Email of the person it reports to — approvals and reports go there."},"listensTo":{"type":"array","items":{"type":"string","enum":["chat_queue","email","sms","social","ticket","order","form"]},"description":"Where it is alerted from. Always on: direct messages, mentions, work assigned to it."},"avatar":{"type":"string"},"runtime":{"type":"object","properties":{"provider":{"type":"string","enum":["stub","session-manager","external"],"default":"stub","description":"stub records what it would do and does no work."},"model":{"type":"string"}}},"workingHours":{"type":"object","properties":{"alwaysOn":{"type":"boolean","default":true},"timezone":{"type":"string","default":"UTC","example":"America/Chicago"},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"17:00"}}},"limits":{"type":"object","properties":{"budgetEnabled":{"type":"boolean","default":true,"description":"Off: never stopped for spend."},"dailyBudgetUsd":{"type":"number","default":5},"maxConcurrentJobs":{"type":"integer","default":1,"minimum":1,"maximum":20},"maxAttempts":{"type":"integer","default":2,"minimum":1,"maximum":10}}},"approvals":{"type":"object","description":"Which actions wait for a person. Each is `require` (default) or `allow`.","properties":{"delete":{"type":"string","enum":["require","allow"]},"bulkSend":{"type":"string","enum":["require","allow"],"description":"Messages to more than a few people at once."},"calls":{"type":"string","enum":["require","allow"],"description":"Placing a phone call."},"money":{"type":"string","enum":["require","allow"],"description":"Refunds, payments, charges, credits."},"moneyThresholdUsd":{"type":"number","description":"With money on allow, amounts above this still need an OK."},"usersAndPermissions":{"type":"string","enum":["require","allow"]}}},"voice":{"type":"object","description":"How it sounds on the phone. Calls to a number assigned to it are answered by it.","properties":{"enabled":{"type":"boolean","default":true},"voice":{"type":"string","description":"An ElevenLabs voice_id or an OpenAI voice name, from the voice list."},"platform":{"type":"string","enum":["elevenlabs","openai-realtime"],"description":"Set with the voice."},"voiceName":{"type":"string"},"language":{"type":"string","default":"en"},"greeting":{"type":"string","maxLength":300},"eagerness":{"type":"string","enum":["low","medium","high"],"default":"medium"},"speakingSpeed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"How fast it talks; blank or 1 = the voice's own pace."},"tools":{"type":"array","items":{"type":"string"},"description":"What it can do during a call."}}},"status":{"type":"string","enum":["draft","active","paused"],"readOnly":true,"description":"Changed only by switch-on / pause / shut-down."},"userId":{"type":"string","readOnly":true},"userEmail":{"type":"string","readOnly":true,"description":"Its login identity: `<name>@<orgId>.ai-employee.local`."},"template":{"type":"string","readOnly":true}}}}},"access":{"type":"object","nullable":true,"properties":{"userId":{"type":"string"},"email":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"type":"string"}},"locked":{"type":"boolean"}}},"contact":{"type":"object","properties":{"email":{"type":"string"},"phones":{"type":"array","items":{"type":"object","additionalProperties":true}},"numbers":{"type":"object","additionalProperties":true}}},"team":{"type":"object","nullable":true,"properties":{"workspaceId":{"type":"string"},"title":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/pause","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Status `paused`: it takes no work and its login is locked, so a runtime holding a token is stopped at its next call. A running session is not ended — use shut-down for that.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/pause (name: string, body) -> The employee (as GET)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.\n\n#### See also\n\n- `POST /ai-employees/{name}/shut-down`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Reviewing its refunds"}}}}}},"/ai-employees/{name}/shut-down":{"post":{"operationId":"AIEmployeeController_shutDown","summary":"Shut it down","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"Provider status plus `requeued` (jobs put back)","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"}}},"status":{"type":"object","properties":{"exists":{"type":"boolean","nullable":true},"state":{"type":"string"},"detail":{"type":"string"},"checkedAt":{"type":"string"}}},"connection":{"type":"object","additionalProperties":true,"description":"What the agent itself last reported (hello / briefing / lease / step)."},"requeued":{"type":"integer"}}}}}},"400":{"description":"There is no connection to the provider \"external\" yet. — The employee's `runtime.provider` has no connection here.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"There is no connection to the provider \"external\" yet.","path":"/ai-employees/{name}/shut-down","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/shut-down","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The session manager did not stop it. — The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"The session manager did not stop it.","path":"/ai-employees/{name}/shut-down","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["AI Employees"],"description":"Harder than pause: its running session is ended now, what it had taken goes back in the queue, and it is paused (login locked). Switch it on to start it again.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/shut-down (name: string) -> Provider status plus `requeued` (jobs put back)\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | NO_PROVIDER | There is no connection to the provider \"external\" yet. | The employee's `runtime.provider` has no connection here. | — |\n| `502` | PROVIDER_ERROR | The session manager did not stop it. | The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/{name}/restart":{"post":{"operationId":"AIEmployeeController_restart","summary":"Restart it","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"Provider status plus `requeued` and `forgotten`","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"}}},"status":{"type":"object","properties":{"exists":{"type":"boolean","nullable":true},"state":{"type":"string"},"detail":{"type":"string"},"checkedAt":{"type":"string"}}},"connection":{"type":"object","additionalProperties":true,"description":"What the agent itself last reported (hello / briefing / lease / step)."},"requeued":{"type":"integer"},"forgotten":{"type":"integer"}}}}}},"400":{"description":"There is no connection to the provider \"external\" yet. — The employee's `runtime.provider` has no connection here.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"There is no connection to the provider \"external\" yet.","path":"/ai-employees/{name}/restart","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/restart","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The session manager did not restart it. — The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"The session manager did not restart it.","path":"/ai-employees/{name}/restart","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["AI Employees"],"description":"Ends its session now and starts a fresh one that reads its briefing anew; what it had taken goes back in the queue. `forget: true` also drops the conversations it would resume.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/restart (name: string, body) -> Provider status plus `requeued` and `forgotten`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | NO_PROVIDER | There is no connection to the provider \"external\" yet. | The employee's `runtime.provider` has no connection here. | — |\n| `502` | PROVIDER_ERROR | The session manager did not restart it. | The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"forget":{"type":"boolean","default":false}}},"example":{"forget":true}}}}}},"/ai-employees/{name}/memory":{"get":{"operationId":"AIEmployeeController_memory","summary":"Get its working memory","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"200":{"description":"{ notes, rememberedSessions, canForgetSessions }","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","nullable":true},"author":{"type":"string"},"text":{"type":"string"}}}},"rememberedSessions":{"nullable":true,"description":"Conversations its provider would resume; null when the provider does not say."},"canForgetSessions":{"type":"boolean"}}}}}},"400":{"description":"There is no connection to the provider \"external\" yet. — The employee's `runtime.provider` has no connection here.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"There is no connection to the provider \"external\" yet.","path":"/ai-employees/{name}/memory","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/memory","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"409":{"description":"Ava has no user, so it keeps no notes. — The employee has no user.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":409,"error":"Ava has no user, so it keeps no notes.","path":"/ai-employees/{name}/memory","method":"GET","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"The notes it wrote for itself (newest first) and, when its provider says, the conversations it would resume.\n\n#### Signature\n\n```http\nGET /ai-employees/{name}/memory (name: string) -> { notes, rememberedSessions, canForgetSessions }\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | NO_PROVIDER | There is no connection to the provider \"external\" yet. | The employee's `runtime.provider` has no connection here. | — |\n| `409` | NO_USER | Ava has no user, so it keeps no notes. | The employee has no user. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/{name}/memory/notes/remove":{"post":{"operationId":"AIEmployeeController_forgetNotes","summary":"Remove notes from its memory","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"Its notes after the change","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"400":{"description":"Say which note (its time). — `at` is not a date.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Say which note (its time).","path":"/ai-employees/{name}/memory/notes/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/memory/notes/remove","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"`at` removes the note written at that time; `all: true` clears every note. A call with neither is refused (400) — it never clears notes by default.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/memory/notes/remove (name: string, body) -> Its notes after the change\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | NOTE_TIME_INVALID | Say which note (its time). | `at` is not a date. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"at":{"type":"string","format":"date-time","description":"The note's time, from GET memory."}}},"example":{"at":"2026-09-28T14:03:11.000Z"}}}}}},"/ai-employees/{name}/memory/forget-sessions":{"post":{"operationId":"AIEmployeeController_forgetSessions","summary":"Drop the conversations it would resume","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"Its memory (as GET) plus `forgotten`","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","nullable":true},"author":{"type":"string"},"text":{"type":"string"}}}},"rememberedSessions":{"nullable":true,"description":"Conversations its provider would resume; null when the provider does not say."},"canForgetSessions":{"type":"boolean"},"forgotten":{"type":"integer"}}}}}},"400":{"description":"There is no connection to the provider \"external\" yet. — The employee's `runtime.provider` has no connection here.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"There is no connection to the provider \"external\" yet.","path":"/ai-employees/{name}/memory/forget-sessions","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/memory/forget-sessions","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"The session manager did not answer. — The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":502,"error":"The session manager did not answer.","path":"/ai-employees/{name}/memory/forget-sessions","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}}},"tags":["AI Employees"],"description":"So its next job starts clean.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/memory/forget-sessions (name: string) -> Its memory (as GET) plus `forgotten`\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | NO_PROVIDER | There is no connection to the provider \"external\" yet. | The employee's `runtime.provider` has no connection here. | — |\n| `502` | PROVIDER_ERROR | The session manager did not answer. | The runtime provider (session manager) refused or did not answer; the text is its reason when it gave one. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`."}},"/ai-employees/{name}/work":{"post":{"operationId":"AIEmployeeController_enqueue","summary":"Give an employee work","parameters":[{"name":"orgid","in":"header","required":true,"schema":{"type":"string"},"description":"Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials.","example":"acme-retail"},{"name":"orgid","required":true,"in":"header","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"},"description":"The employee's handle (`ai_employee.name`).","example":"ava"}],"responses":{"201":{"description":"The queued work item","content":{"application/json":{"schema":{"type":"object","description":"A work item (`ai_employee_work`).","properties":{"id":{"type":"string","description":"Record identifier.","example":"66f1a2b3c4d5e6f708192a3b"},"sk":{"type":"string","description":"Storage sort key."},"datatype":{"type":"string","description":"Record type discriminator.","example":"category"},"name":{"type":"string","description":"Machine name, unique within the datatype."},"title":{"type":"string","description":"Display title."},"createdate":{"type":"string","format":"date-time","description":"Creation timestamp."},"modifydate":{"type":"string","format":"date-time","description":"Last modification timestamp."},"author":{"type":"string","description":"Email or username of the last writer."},"data":{"type":"object","properties":{"employee":{"type":"string"},"title":{"type":"string"},"instructions":{"type":"string"},"source":{"type":"string","enum":["assigned","ping","direct","message","call","config"]},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"thread":{"type":"string"}}},"attachments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["record","file"]},"datatype":{"type":"string","description":"record: its collection."},"id":{"type":"string","description":"record: its id."},"label":{"type":"string","description":"For a record the server reads its own label; the caller's is not trusted."},"path":{"type":"string","description":"file: where it is stored."},"url":{"type":"string"},"mime":{"type":"string"},"comment":{"type":"string","description":"What it is for."}}}},"requestedBy":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string","enum":["queued","in_progress","waiting_approval","done","failed","cancelled"]},"lease":{"type":"object","nullable":true,"properties":{"worker":{"type":"string"},"until":{"type":"string","format":"date-time"}}},"attempts":{"type":"integer"},"steps":{"type":"array","description":"The timeline, in order.","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"text":{"type":"string"},"detail":{"type":"object","additionalProperties":true}}}},"pendingApproval":{"type":"object","nullable":true,"properties":{"action":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"amountUsd":{"type":"number"},"requestedAt":{"type":"string"}}},"decisions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"summary":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"by":{"type":"string"},"note":{"type":"string"},"at":{"type":"string"}}}},"result":{"type":"string"},"error":{"type":"string"},"costUsd":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}}}}}}},"400":{"description":"Say what the work is. — No title and no instructions.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":400,"error":"Say what the work is.","path":"/ai-employees/{name}/work","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No AI employee \"ava\" — No employee (templates excluded) has that handle.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","path","method","timeStamp"],"additionalProperties":true,"properties":{"statusCode":{"type":"integer","description":"HTTP status code, repeated in the body.","example":404},"error":{"type":"string","description":"Human-readable failure description.","example":"Category not found"},"path":{"type":"string","description":"Request path that failed, including query string.","example":"/storefront/categories"},"method":{"type":"string","description":"HTTP method of the failed request.","example":"POST"},"timeStamp":{"type":"string","format":"date-time","description":"Server time the error was produced.","example":"2026-08-29T14:03:22.118Z"}}},"example":{"statusCode":404,"error":"No AI employee \"ava\"","path":"/ai-employees/{name}/work","method":"POST","timeStamp":"2026-08-29T14:03:22.118Z"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"tags":["AI Employees"],"description":"Queues a direct request. The title defaults to the first line of the instructions. Attachments are records (`kind: record`, datatype, id) and documents (`kind: file`, path or url), each with a comment on what it is for; a record is described from the record itself.\n\n#### Signature\n\n```http\nPOST /ai-employees/{name}/work (name: string, body) -> The queued work item\n```\n\n#### Access\n\nRequires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `Owner`, `ConfigAdmin`, `RootAdmin`, `RootSystem`, `RootPowerUser`.\n\n#### Errors\n\n| Status | Code | Message | When | What to do |\n| --- | --- | --- | --- | --- |\n| `404` | AI_EMPLOYEE_NOT_FOUND | No AI employee \"ava\" | No employee (templates excluded) has that handle. | — |\n| `400` | WORK_TITLE_REQUIRED | Say what the work is. | No title and no instructions. | — |\n\nPlus the standard platform errors: `401`, `403`, `429`, `500`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":140},"instructions":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"],"default":"normal"},"ref":{"type":"object","properties":{"datatype":{"type":"string"},"id":{"type":"string"},"label"