{"openapi":"3.1.0","info":{"title":"Mobiari Admin API","description":"The merchant API behind the Mobiari admin and mobile apps, open to your own integrations. Authenticate with `Authorization: Bearer <token>`: a session token from `POST /auth/login` or a store API token (`mobi_st_…`) issued under `/stores/{store_id}/api-tokens`, which works only for that store.\n\nConventions that hold for every endpoint (errors, pagination, idempotency, rate limits, versioning) are described at https://docs.mobiari.com/docs/api-conventions.","license":{"name":""},"version":"1.0.0"},"servers":[{"url":"https://api.mobiari.com/v1","description":"Production"},{"url":"http://localhost:4000/v1","description":"Local development"}],"paths":{"/assistant/conversations/{conversation_id}":{"delete":{"tags":["Assistant"],"summary":"Delete a conversation","description":"Stops a running turn and deletes the conversation with its messages and\npending proposals. Actions already applied stay (and stay undoable).","operationId":"deleteAssistantConversation","parameters":[{"name":"conversation_id","in":"path","description":"Assistant conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Assistant"],"summary":"Rename a conversation","operationId":"renameAssistantConversation","parameters":[{"name":"conversation_id","in":"path","description":"Assistant conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameAssistantConversationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty or longer than 120 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/assistant/conversations/{conversation_id}/messages":{"get":{"tags":["Assistant"],"summary":"Get a conversation's messages","description":"The full transcript, lossless (tool calls and results included), and the\nproposals still waiting for a decision.","operationId":"getAssistantConversationMessages","parameters":[{"name":"conversation_id","in":"path","description":"Assistant conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversationMessages"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/assistant/conversations/{conversation_id}/stop":{"post":{"tags":["Assistant"],"summary":"Stop the assistant","description":"Asks the turn running in the conversation to stop; what it generated so\nfar is kept and its stream ends with `stopped` and `done`. Nothing\nhappens when no turn is running.","operationId":"stopAssistant","parameters":[{"name":"conversation_id","in":"path","description":"Assistant conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Stop requested (or nothing was running)"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/assistant/proposals/{proposal_id}/approve":{"post":{"tags":["Assistant"],"summary":"Approve a proposal","description":"Applies the write the assistant proposed (with the permission the write\nneeds, checked now), records it as an undoable action, and streams the\nassistant's follow-up turn. The first event after `conversation` is the\n`tool_result` saying whether it was applied. Proposals expire after an\nhour. Server-sent events as in `chatWithAssistant`.","operationId":"approveAssistantProposal","parameters":[{"name":"proposal_id","in":"path","description":"Proposal id (from a `proposal` event)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"confirmed","in":"query","description":"The admin ticked the confirmation of a destructive / money /\nexternal change. Without it such proposals answer 428.","required":false,"schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"The follow-up turn, as server-sent events","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`missing_permission`: the caller lacks the permission the write needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such pending proposal in your conversations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`assistant_busy`: a turn is already running in this conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"428":{"description":"`confirmation_required`: a destructive, money or external change; approve again with `confirmed=true`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/assistant/proposals/{proposal_id}/decline":{"post":{"tags":["Assistant"],"summary":"Decline a proposal","description":"Nothing is applied; the assistant is told and its follow-up turn is\nstreamed as in `chatWithAssistant`.","operationId":"declineAssistantProposal","parameters":[{"name":"proposal_id","in":"path","description":"Proposal id (from a `proposal` event)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"The follow-up turn, as server-sent events","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such pending proposal in your conversations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/auth/2fa/totp/verify":{"post":{"tags":["Auth"],"summary":"Finish signing in with an authenticator code","description":"Exchanges the challenge from `POST /auth/login` and a current TOTP\ncode for a session.","operationId":"verifyTotp","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyTotpRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"`totp_not_enabled`: the account has no authenticator app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`invalid_challenge`: challenge invalid, expired or already used, sign in again. `invalid_code`: wrong code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`account_disabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts; a challenge allows 5","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/auth/login":{"post":{"tags":["Auth"],"summary":"Sign in","description":"Checks e-mail and password. Without two-factor authentication the\nresponse has `status: \"authenticated\"` and a session (access token,\nrefresh token, user). With it, `status: \"two_factor_required\"` and a\nchallenge valid for 5 minutes: finish with\n`POST /auth/2fa/totp/verify` or `POST /auth/otp/send` +\n`POST /auth/otp/verify`, depending on `methods`.","operationId":"login","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"401":{"description":"`invalid_credentials`: unknown e-mail or wrong password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`account_disabled`: the account was deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts from this address or for this account","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/auth/logout":{"post":{"tags":["Auth"],"summary":"Sign out","description":"Revokes the session the refresh token belongs to: its refresh tokens\nstop working and so do access tokens issued for it. Succeeds for\nunknown or already revoked tokens, so it is safe to retry.","operationId":"logout","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutRequest"}}},"required":true},"responses":{"204":{"description":"Signed out"},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/auth/otp/send":{"post":{"tags":["Auth"],"summary":"Send a sign-in code over WhatsApp","description":"Sends a 6-digit code, valid for 5 minutes, to the WhatsApp number\nregistered for two-factor sign-in. Requesting again sends a new code;\nonly the newest one is accepted.","operationId":"sendLoginOtp","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpSendRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpSendResponse"}}}},"400":{"description":"`whatsapp_2fa_not_enabled`: the account has no WhatsApp number for sign-in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`invalid_challenge`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many codes requested","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`otp_delivery_failed`: WhatsApp did not accept the message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/auth/otp/verify":{"post":{"tags":["Auth"],"summary":"Finish signing in with a WhatsApp code","description":"Exchanges the challenge from `POST /auth/login` and the code from\n`POST /auth/otp/send` for a session. The code must have been sent for\nthis challenge. After 5 wrong attempts the code is burned and a new one\nmust be requested.","operationId":"verifyLoginOtp","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOtpRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"`no_pending_code`: request a code first. `too_many_attempts`: request a new code. `whatsapp_2fa_not_enabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`invalid_challenge`: challenge invalid, expired or already used. `invalid_code`: wrong or expired code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`account_disabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts; a challenge allows 5","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/auth/refresh":{"post":{"tags":["Auth"],"summary":"Refresh a session","description":"Trades a refresh token for a new access token and a new refresh token.\nThe presented refresh token stops working (rotation), so keep only the\nnewest one and do not send two refreshes with the same token.\n\nIf the response to a refresh is lost, retrying with the same token\nwithin 30 seconds is safe: a fresh pair is issued and the one the client\nnever received is retired. Otherwise, presenting a refresh token that was\nalready used signs the whole session out on every device holding it\n(`refresh_token_reused`). A token whose session ended (sign-out, device\nrevoked, password changed) or expired is `invalid_refresh_token`. Both\nmean: sign in again.","operationId":"refreshSession","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"401":{"description":"`invalid_refresh_token`: unknown, expired, or its session was ended. `refresh_token_reused`: already used outside the retry window; the session was signed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/auth/register":{"post":{"tags":["Auth"],"summary":"Create an account","description":"Registers a user with e-mail and password. The account starts without\nstores; create a tenant (`POST /tenants`) and a store (`POST /stores`)\nnext, or accept an invite. Emits the `user.created` webhook. Does not\nsign in: call `POST /auth/login` afterwards.","operationId":"register","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"409":{"description":"`email_taken`: an account with this e-mail exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: invalid e-mail or password too short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many registrations from this address or for this e-mail","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/billing/plans":{"get":{"tags":["Billing"],"summary":"List plans","description":"The plans on sale with their monthly and annual prices and limits. Every\nplan includes every module; they differ in size. Public, for pricing\npages.","operationId":"listPlans","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanCatalog"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/docs/ask":{"post":{"tags":["Help"],"summary":"Ask the documentation","description":"Answers a question about Mobiari from its documentation, streamed. Public\n(the docs site and the admin's help panel call it); limited to 20\nquestions per hour per visitor and a daily total. The response is the AI\nSDK UI message stream (`text/event-stream`, header\n`x-vercel-ai-ui-message-stream: v1`): `data:` lines carrying JSON objects\nwith `type` `start`, `text-start`, `text-delta` {id, delta}, `text-end`,\n`source-url` {sourceId, url, title} for each documentation page the\nanswer cites, then `finish` or `error` {errorText}, and a final\n`data: [DONE]`.","operationId":"askDocs","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocsAskRequest"}}},"required":true},"responses":{"200":{"description":"The answer, as an AI SDK UI message stream (see the description)","content":{"text/event-stream":{"schema":{"type":"string"}}}},"422":{"description":"`validation_failed`: no question, or the last message is not the user's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`: no model configured, or the docs could not be loaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/events/catalog":{"get":{"tags":["Events"],"summary":"Get the event catalog","description":"Every domain event with its payload keys, for webhook subscriptions and\nworkflow triggers. With `store_id`, also how many workflows, webhooks\nand team alerts listen to each in that store.","operationId":"getEventCatalog","parameters":[{"name":"store_id","in":"query","description":"Also count this store's subscribers per event.","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/invites/accept":{"post":{"tags":["Team"],"summary":"Accept an invite","description":"Joins the store with the invited roles and signs in. If the invited\ne-mail has no account yet, one is created with `full_name` and\n`password`; if it has one, `password` must be that account's password.","operationId":"acceptInvite","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInviteRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInviteResponse"}}}},"400":{"description":"`invalid_invite`: unknown, used, cancelled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`invalid_credentials`: the e-mail has an account and the password is not its password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`account_disabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: password too short for a new account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/me":{"get":{"tags":["Me"],"summary":"Get my profile","description":"The signed-in user. Stores and permissions are at `GET /me/access`.","operationId":"getMe","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Me"],"summary":"Update my profile","description":"Changes the caller's name, phone or language. Fields left out stay as\nthey are.","operationId":"updateMe","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMeRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: a field is out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/2fa/totp/disable":{"post":{"tags":["Me"],"summary":"Turn off the authenticator app","description":"Requires the current password or a current code from the app. A fresh\nsecret is generated, so turning it on again needs a new QR code.","operationId":"disableTotp","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disable2FARequest"}}},"required":true},"responses":{"204":{"description":"Authenticator app disabled"},"400":{"description":"`reauthentication_required`: no valid password or code was given","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/2fa/totp/enable":{"post":{"tags":["Me"],"summary":"Turn on the authenticator app","description":"Requires a current code from the app set up with\n`GET /me/2fa/totp/setup`. From then on, sign-in asks for a code.","operationId":"enableTotp","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableTotpRequest"}}},"required":true},"responses":{"204":{"description":"Authenticator app enabled"},"400":{"description":"`invalid_code`: the code does not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`totp_already_enabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/2fa/totp/setup":{"get":{"tags":["Me"],"summary":"Start setting up an authenticator app","description":"Returns the secret and an `otpauth://` URL to show as a QR code. Confirm\nwith `POST /me/2fa/totp/enable` and a code from the app.","operationId":"getTotpSetup","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotpSetupResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`totp_already_enabled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/2fa/whatsapp/confirm-setup":{"post":{"tags":["Me"],"summary":"Turn on WhatsApp sign-in codes","description":"Confirms the code sent by `start-setup`; the phone becomes the account's\nWhatsApp second factor.","operationId":"confirmWhatsapp2faSetup","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmWhatsappSetupRequest"}}},"required":true},"responses":{"204":{"description":"WhatsApp sign-in enabled"},"400":{"description":"`no_pending_code`, `too_many_attempts` (request a new code) or `invalid_code`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/2fa/whatsapp/disable":{"post":{"tags":["Me"],"summary":"Turn off WhatsApp sign-in codes","operationId":"disableWhatsapp2fa","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disable2FARequest"}}},"required":true},"responses":{"204":{"description":"WhatsApp sign-in disabled"},"400":{"description":"`reauthentication_required`: no valid password or code was given","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/2fa/whatsapp/start-setup":{"post":{"tags":["Me"],"summary":"Start setting up WhatsApp sign-in codes","description":"Sends a 6-digit code to `phone`. Confirm with\n`POST /me/2fa/whatsapp/confirm-setup`.","operationId":"startWhatsapp2faSetup","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWhatsappSetupRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpSendResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: the phone needs 10 to 20 digits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many codes requested","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`otp_delivery_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/access":{"get":{"tags":["Me"],"summary":"Get my stores and permissions","description":"Every store the caller can reach (as owner of the store or its tenant,\nor through a role), with the tenant it belongs to, the caller's roles\nthere and the effective permission codes. Load it once per session to\nbuild a store switcher and to hide what the user cannot do; the server\nenforces the same permissions on every call.","operationId":"getMyAccess","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MyAccess"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/change-password":{"post":{"tags":["Me"],"summary":"Change my password","description":"Requires the current password. Every other session of the account is\nsigned out; the one making the request stays signed in.","operationId":"changePassword","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordRequest"}}},"required":true},"responses":{"204":{"description":"Password changed"},"400":{"description":"`incorrect_password`: the current password is wrong","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: the new password is too short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/devices":{"get":{"tags":["Push Notifications"],"summary":"List my devices","description":"Devices registered for push by the signed-in user, most recently\nregistered first. `current` marks the one registered by this session.","operationId":"listPushDevices","parameters":[{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_PushDevice"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Push Notifications"],"summary":"Register a device for push","description":"Call after every sign-in, whenever the OS hands the app a new token\n(APNs `didRegisterForRemoteNotificationsWithDeviceToken`, FCM\n`onNewToken`), and on app start if the token or the language changed.\nUpserts by `(platform, token)` and binds the device to the calling user\nand session: a token registered by another account moves to this one,\nand an earlier token of this session on the same platform is dropped\n(token rotation). Pushes stop when the session ends: sign-out or\n`DELETE /me/sessions/{id}` deletes its devices.\n\nNeeds a session access token (`sid`); store API tokens cannot\nregister devices.","operationId":"registerPushDevice","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPushDeviceRequest"}}},"required":true},"responses":{"200":{"description":"Already registered; updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDevice"}}}},"201":{"description":"Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDevice"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`session_required`: called with a store API token or a token without a session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: malformed token or a field too long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/devices/{device_id}":{"delete":{"tags":["Push Notifications"],"summary":"Unregister a device","description":"Stops pushes to it. Call before signing out, or when the user turns\nnotifications off in the app.","operationId":"deletePushDevice","parameters":[{"name":"device_id","in":"path","description":"Device id from `POST /me/devices`","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Unregistered"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such device of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/devices/{device_id}/test":{"post":{"tags":["Push Notifications"],"summary":"Send a test push","description":"Sends \"Notifications are working on this device\" (in the device's\nlanguage) right away, not through the queue, and reports what the\nprovider said. Data: `{\"kind\": \"test\"}`. Accepted by the provider does\nnot guarantee display: the user may have notifications off.","operationId":"testPushDevice","parameters":[{"name":"device_id","in":"path","description":"Device id from `POST /me/devices`","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushTestResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such device of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"`push_token_invalid`: the provider rejected the token (app uninstalled, wrong app or environment); the device was deleted, register again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`push_provider_error`: the provider refused or did not answer; `error` has its reason","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`push_not_configured`: push for this platform is not set up on the server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/sessions":{"get":{"tags":["Me"],"summary":"List my sessions","description":"Devices signed in to the caller's account (active refresh-token\nfamilies), most recently used first. Store API tokens are not\nsessions; see `/stores/{store_id}/api-tokens`.","operationId":"listMySessions","parameters":[{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_DeviceSession"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/sessions/revoke-others":{"post":{"tags":["Me"],"summary":"Sign out my other sessions","description":"Revokes every session of the caller except the one this request was\nmade with: those devices' refresh tokens and access tokens stop\nworking. When the request is not tied to a session (a store API\ntoken, or an access token issued before sessions existed), every\nsession is revoked. Idempotent: with nothing else signed in it does\nnothing and still answers 204.","operationId":"revokeMyOtherSessions","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Other sessions revoked"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me/sessions/{session_id}":{"delete":{"tags":["Me"],"summary":"Revoke one of my sessions","description":"Signs the device out: its refresh token and access tokens stop\nworking. Revoking the current session signs this client out too.","operationId":"revokeMySession","parameters":[{"name":"session_id","in":"path","description":"Session id from `GET /me/sessions`","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Session revoked"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No active session with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/permissions/catalog":{"get":{"tags":["Team"],"summary":"Get the permission catalog","description":"Every permission code, grouped, for role editors and token scopes. A\nfixed list that changes only with releases.","operationId":"getPermissionCatalog","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionCatalog"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/places/autocomplete":{"get":{"tags":["Places"],"summary":"Suggest addresses","description":"Brazilian address suggestions for what the user typed, from Google\nPlaces. Debounce calls; each one is billed. 503\n`places_not_configured` when the server has no Google key, in which\ncase fall back to plain address fields.","operationId":"autocompleteAddress","parameters":[{"name":"q","in":"query","description":"What the user typed; under 3 characters returns no predictions.","required":false,"schema":{"type":"string"}},{"name":"session","in":"query","description":"A client-generated id (e.g. a UUID) shared by the autocomplete\ncalls and the final details call of one address entry, so Google\nbills them as one session.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Prediction"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`places_upstream_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`places_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/places/details/{place_id}":{"get":{"tags":["Places"],"summary":"Get an address","description":"The chosen suggestion as structured address fields (street, number,\nneighborhood, city, state, postal code).","operationId":"getAddressDetails","parameters":[{"name":"place_id","in":"path","description":"`place_id` of a prediction","required":true,"schema":{"type":"string"}},{"name":"session","in":"query","description":"The same session id used for the autocomplete calls.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParsedAddress"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown place","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`places_upstream_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`places_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/preview-auth/grant":{"post":{"tags":["Storefront"],"summary":"Grant a preview session","description":"Mints a 24-hour token that lets the caller view the store's preview\ndeployments (`<ref>--<store>.<preview suffix>`). Needs\n`storefront.read` in the store. `return_url` must be an https URL on a\npreview host of this deployment; the UI then submits the token in a\nform POST to that host's `/__preview/grant`.","operationId":"grantStorefrontPreview","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewGrantRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewGrant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No store with this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: neither `store_id` nor `store_slug` sent, or `return_url` missing or not a preview host (`invalid_return_url`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores":{"get":{"tags":["Stores"],"summary":"List a tenant's stores","description":"The stores of `tenant_id` the caller can reach (owner, or a role in the\nstore), by name. For every store across tenants with the caller's\npermissions in each, use `GET /me/access`.","operationId":"listStores","parameters":[{"name":"tenant_id","in":"query","description":"The tenant whose stores to list.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Store"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Stores"],"summary":"Create a store","description":"Creates a store in the tenant, with the tenant's currency, language and\ntime zone. The caller becomes its owner. The built-in roles (Owner,\nManager, Cashier, Marketing) and a Storefront sales channel are created\nwith it. Counts against the plan's store limit. Emits the\n`store.created` webhook.","operationId":"createStore","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStoreRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`plan_limit_reached`: the plan's store limit is reached (`details` has `limit`, `max`, `used`, `plan`); `subscription_inactive`: the subscription is suspended or canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`slug_taken`: a store with this name's slug exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/ads/connection":{"get":{"tags":["Ads"],"summary":"Get the ads connection","operationId":"getAdsConnection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsConnection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/ads/performance":{"get":{"tags":["Ads"],"summary":"Get ads performance","description":"Daily spend, impressions, clicks and purchases from the Meta ad account\nnext to the orders our own first-touch attribution assigns to Meta.\nA Meta failure is reported in `meta.error`, not as an error response.","operationId":"getAdsPerformance","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","description":"Days back, 1 to 90. Defaults to 30.","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsPerformance"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/alert-subscriptions":{"get":{"tags":["Notifications"],"summary":"List team alert subscriptions","description":"Every member of the store with the sale alerts they get on WhatsApp\n(from Mobiari's account, to their profile phone), whether or not they\nwere ever set.","operationId":"listAlertSubscriptions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AlertSubscription"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/alert-subscriptions/{user_id}":{"put":{"tags":["Notifications"],"summary":"Set a member's team alerts","description":"Which sale alerts a member of the store gets on WhatsApp. Members\nwithout a profile phone are skipped at send time.","operationId":"updateAlertSubscription","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"path","description":"The member's user id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAlertSubscription"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertSubscription"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not a member of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/api-tokens":{"get":{"tags":["API Tokens"],"summary":"List API tokens","description":"The store's active tokens, newest first. Raw tokens are never returned.","operationId":"listApiTokens","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ApiTokenSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["API Tokens"],"summary":"Create an API token","description":"Issues a store API token acting as the caller in this store,\nlimited to `scopes`. The raw `token` is only in this response; store it.","operationId":"createApiToken","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiTokenRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiTokenResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`missing_permission`, or `grant_exceeds_actor`: a scope the caller does not hold","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: bad name, empty or unknown scopes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/api-tokens/{token_id}":{"delete":{"tags":["API Tokens"],"summary":"Revoke an API token","description":"The token stops working immediately.","operationId":"revokeApiToken","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token_id","in":"path","description":"Token id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Token revoked"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No active token with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/api-tokens/{token_id}/rotate":{"post":{"tags":["API Tokens"],"summary":"Rotate an API token","description":"Replaces the token's secret; the old one stops working at once. Only\nthe user the token acts as may rotate it, since the new secret is\nreturned to the caller.","operationId":"rotateApiToken","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token_id","in":"path","description":"Token id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiTokenResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`not_token_owner`: the token acts as another user; revoke it instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No active token with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/actions":{"get":{"tags":["Assistant"],"summary":"List assistant actions","description":"Writes the assistant applied in the store, newest first: only those\nwhose permission the caller holds.","operationId":"listAssistantActions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AssistantAction"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/actions/{action_id}/undo":{"post":{"tags":["Assistant"],"summary":"Undo an assistant action","description":"Restores what the write changed, from the snapshot taken before it.\nSupported for `update_product`, `mark_order_paid`, `fulfill_order`,\n`cancel_order` and `bulk_update_variant_prices`; anything else has to be\nreverted by hand. Needs the permission the write needed.","operationId":"undoAssistantAction","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"action_id","in":"path","description":"Assistant action id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantAction"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such action in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`action_already_undone`, or `undo_conflict`: the record changed since the action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`undo_not_supported`: this kind of write cannot be undone automatically","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/chat":{"post":{"tags":["Assistant"],"summary":"Talk to the assistant","description":"Sends a message and streams the assistant's turn: text, tool calls and their results, and proposals for writes, which wait for `approveAssistantProposal` / `declineAssistantProposal`. A proposal left unanswered expires when the next message is sent. Counts toward the store's monthly message cap, set by the organization's plan.\n\nThe response is `text/event-stream`. Server-sent events, each `event: <type>` with a JSON `data` object carrying the same `type`: `conversation` {conversation_id} (always first), `message_start` {message_id}, `text_delta` {message_id, text}, `thinking_delta` {message_id, text}, `tool_call` {message_id, tool_use_id, tool_name, input}, `tool_result` {tool_use_id, content, is_error} (`content` is the tool's JSON output as a string; report tools may include `chart_png_b64`), `proposal` {message_id, proposal_id, tool_use_id, tool_name, preview, expires_at} (a write waiting for approval), `message_end` {message_id, stop_reason}, `title` {title}, `usage` {input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens}, `stopped`, `error` {message} and `done` (always last).","operationId":"chatWithAssistant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantChatRequest"}}},"required":true},"responses":{"200":{"description":"The turn, as server-sent events (see the description)","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`subscription_inactive`: the organization's subscription is suspended or canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`assistant_busy`: a turn is already running in this conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: blank or too long message (32000 characters), or context over 64 kB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`assistant_cap_reached`: the store used its plan's monthly messages (also `rate_limited`, see the other 429s)","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`: no model configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/conversations":{"get":{"tags":["Assistant"],"summary":"List your assistant conversations","description":"Your own conversations in the store (web and WhatsApp), most recently\nactive first.","operationId":"listAssistantConversations","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Search titles and your own messages.","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Same as `search` (older clients). Deprecated.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AssistantConversation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/phones":{"get":{"tags":["Assistant"],"summary":"List your assistant phones","description":"Your WhatsApp numbers linked to the assistant in this store.","operationId":"listAssistantPhones","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AssistantLinkedPhone"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/phones/verify-complete":{"post":{"tags":["Assistant"],"summary":"Verify a phone","description":"Checks the code; from then on messages from the number reach the\nassistant as you, in this store.","operationId":"completeAssistantPhoneVerification","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteAssistantPhoneVerificationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantLinkedPhone"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No verification of this number pending for you in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`phone_already_verified`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_verification_code`: wrong or expired code; `validation_failed`: not a phone number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`too_many_attempts`: 5 wrong codes; request a new one","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/phones/verify-start":{"post":{"tags":["Assistant"],"summary":"Send a phone verification code","description":"Sends a 6-digit code over WhatsApp to link the number to you (the caller)\nin this store. Starting again replaces your previous code; a number\nalready linked to another account is refused.","operationId":"startAssistantPhoneVerification","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAssistantPhoneVerificationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantPhoneVerification"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`phone_linked_elsewhere`: the number is linked to another account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: not a phone number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`whatsapp_send_failed`: the code could not be sent; `error` says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/prefs":{"get":{"tags":["Assistant"],"summary":"Get the assistant preferences","operationId":"getAssistantPreferences","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantPreferences"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Assistant"],"summary":"Update the assistant preferences","description":"The extra instructions go into every turn of every member, so this needs\n`stores.write`.","operationId":"updateAssistantPreferences","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAssistantPreferencesRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantPreferences"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/assistant/usage":{"get":{"tags":["Assistant"],"summary":"Get the assistant usage","description":"Tokens and messages this month, and the monthly message cap set by the\norganization's plan.","operationId":"getAssistantUsage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantUsage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/audiences":{"get":{"tags":["Ads"],"summary":"List ad audiences","description":"Segments mirrored to Meta Custom Audiences, newest first.","operationId":"listAdAudiences","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AdAudience"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Ads"],"summary":"Create an ad audience","description":"Mirrors a segment to a new Meta Custom Audience and starts the first sync\nin the background (hashed e-mail and name of members who accepted\nmarketing).","operationId":"createAdAudience","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdAudienceRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdAudience"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `segment_id` is not a segment of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/audiences/{audience_id}":{"delete":{"tags":["Ads"],"summary":"Delete an ad audience","description":"Also deletes the audience on Meta (best effort), so hashed data does not\nlinger there.","operationId":"deleteAdAudience","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"audience_id","in":"path","description":"Ad audience id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such audience in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/audiences/{audience_id}/sync":{"post":{"tags":["Ads"],"summary":"Sync an ad audience now","description":"Replaces the Meta audience with the segment's current members and waits\nfor Meta to accept it.","operationId":"syncAdAudience","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"audience_id","in":"path","description":"Ad audience id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Synced; `last_count` is how many contacts went","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdAudience"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such audience in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`meta_sync_failed`: Meta is not configured or refused the sync; `error` says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/audit":{"get":{"tags":["Audit"],"summary":"List the audit log","description":"Who did what in the store (assistant writes, campaign sends, settings\nchanges, customer data rights), newest first.","operationId":"listAuditEvents","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"action","in":"query","description":"Only actions starting with this, e.g. `customers.` or `customers.merged`.","required":false,"schema":{"type":"string"}},{"name":"actor","in":"query","description":"Only actions by this user.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AuditEvent"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/audit/actions":{"get":{"tags":["Audit"],"summary":"List audited action names","description":"The distinct actions recorded in this store, alphabetically, for a\nfilter menu. A small list; not paged.","operationId":"listAuditActions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-kit":{"get":{"tags":["Brand"],"summary":"Get the e-mail brand kit","description":"The store's brand profile as e-mails use it, and the font presets.","operationId":"getEmailBrandKit","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBrandKitResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Brand"],"summary":"Save the e-mail brand kit","description":"Replaces the stored kit. Templates with a block design pick it up the\nnext time they are saved or rendered.","operationId":"updateEmailBrandKit","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailBrandKitRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBrandKitResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-kit/ai":{"post":{"tags":["Brand"],"summary":"Revise the e-mail brand kit with the assistant","description":"Revise the brand profile from a free-text instruction (\"mais quente e artesanal\",\n\"botões arredondados e títulos em serifa\"). Returns the full patched kit plus notes on\nwhat changed; nothing is saved.","operationId":"reviseEmailBrandKitWithAssistant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseEmailBrandKitRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBrandKitRevision"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`assistant_error`: the model failed or answered something unusable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`: no model configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-kit/import":{"post":{"tags":["Brand"],"summary":"Suggest a brand kit from a website","description":"Reads a public page and suggests colors, fonts and a logo on top of the\ncurrent kit. Nothing is saved.","operationId":"importEmailBrandKit","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportEmailBrandKitRequest"}}},"required":true},"responses":{"200":{"description":"The suggestion: the patched kit and what was found","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`brand_import_failed`: the page could not be read or is not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system":{"get":{"tags":["Brand"],"summary":"Get the brand system","description":"The store's design system (identity, voice, colors, typography,\nspacing, effects, imagery, components, assets, guide), its version\nhistory and any job still running.","operationId":"getBrandSystem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSystemState"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Brand"],"summary":"Save the brand system","description":"Replaces the current system and records a new version. The e-mail\nbrand kit is derived from it in the same write.","operationId":"saveBrandSystem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveBrandSystemRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSystemSaved"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/ai":{"post":{"tags":["Brand"],"summary":"Revise the brand system with AI","description":"Has the assistant apply the instruction to the system and save a new\nversion; runs in the background.","operationId":"reviseBrandSystem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseBrandSystemRequest"}}},"required":true},"responses":{"202":{"description":"Job started (or already running)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandJobStarted"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`brand_system_missing`: generate the system first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`: AI is not configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/assets":{"post":{"tags":["Brand"],"summary":"Upload a brand asset","description":"`multipart/form-data` with one file (logo, image or font). Stores it\nand answers its public URL; the system is not changed until it is saved\nwith the URL.","operationId":"uploadBrandAsset","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/BrandAssetUploadForm"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadedBrandAsset"}}}},"400":{"description":"Malformed multipart body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Over 15 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`file_missing`: no file part; `invalid_asset`: unsupported type or over 12 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/export":{"get":{"tags":["Brand"],"summary":"Export the brand system","description":"A `.zip` design-system package: the system as JSON, CSS tokens, the\nguide and a rendered e-mail preview, named `<brand>-design-system.zip`.","operationId":"exportBrandSystem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The package","content":{"application/zip":{"schema":{"$ref":"#/components/schemas/BrandPackageFile"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`brand_system_missing`: nothing to export yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/generate":{"post":{"tags":["Brand"],"summary":"Generate the brand system","description":"Crawls the pages, reads the repositories and attachments, and has the\nassistant write the system; runs in the background (a few minutes) and\nsaves a new version when done. With `from_kit`, derives the system from\nthe e-mail brand kit at once instead and answers 200 with it.","operationId":"generateBrandSystem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateBrandSystemRequest"}}},"required":true},"responses":{"200":{"description":"`from_kit`: saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSystemSaved"}}}},"202":{"description":"Job started (or already running)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandJobStarted"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`brand_sources_missing`: no URL, notes or storefront to start from","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`: AI is not configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/import":{"post":{"tags":["Brand"],"summary":"Import a design-system package","description":"`multipart/form-data` with the `.zip` in `file`. Hosts the package's\nimages and fonts, has the assistant map it onto the brand system and\nsaves a new version; runs in the background.","operationId":"importBrandSystem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/BrandImportForm"}}},"required":true},"responses":{"202":{"description":"Job started (or already running)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandJobStarted"}}}},"400":{"description":"Malformed multipart body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Over 40 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`file_missing`: no `file` part; `invalid_package`: not a readable .zip package","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`: AI is not configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/jobs/{job_id}":{"get":{"tags":["Brand"],"summary":"Get a brand job","description":"Poll this after starting a generation, revision or import until\n`status` leaves `running`.","operationId":"getBrandJob","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"job_id","in":"path","description":"Job id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandJob"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`brand_job_not_found`: unknown job, or lost in a server restart (check the versions list)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/versions/{version}":{"get":{"tags":["Brand"],"summary":"Get a brand system version","operationId":"getBrandSystemVersion","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","description":"Version number","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSystemVersionDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/brand-system/versions/{version}/restore":{"post":{"tags":["Brand"],"summary":"Restore a brand system version","description":"Saves the old version's system as a new version.","operationId":"restoreBrandSystemVersion","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","description":"Version number","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSystemSaved"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/build-jobs":{"get":{"tags":["Manufacturing"],"summary":"List build jobs","description":"Newest first, with the product, the order and live parts readiness.","operationId":"listBuildJobs","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","in_progress","ready","cancelled"]}},{"name":"variant_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_BuildJob"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/build-jobs/{job_id}":{"get":{"tags":["Manufacturing"],"summary":"Get a build job","operationId":"getBuildJob","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"job_id","in":"path","description":"Build job id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildJob"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`build_job_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Manufacturing"],"summary":"Update a build job","description":"Changes the status, notes or target date. Moving the status stamps\n`started_at` / `completed_at` / `cancelled_at`; to start part of a queued\njob use `startBuildJob`.","operationId":"updateBuildJob","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"job_id","in":"path","description":"Build job id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildJobUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildJob"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`build_job_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/build-jobs/{job_id}/start":{"post":{"tags":["Manufacturing"],"summary":"Start a build job","description":"Moves units of a `queued` job to the bench. Starting fewer than the job\nquantity splits it: a new `in_progress` batch carries the started units\nand the original keeps the rest, queued. Answers with the started batch.","operationId":"startBuildJob","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"job_id","in":"path","description":"Build job id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildJobStartRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildJob"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`build_job_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`build_job_not_queued`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_quantity`: not between 1 and the job quantity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/canned-replies":{"get":{"tags":["Conversation Settings"],"summary":"List canned replies","description":"Ordered by shortcut.","operationId":"listCannedReplies","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches shortcut, title and text.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_CannedReply"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Conversation Settings"],"summary":"Create a canned reply","description":"A reply with the same shortcut is replaced.","operationId":"createCannedReply","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CannedReplyInput"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CannedReply"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: missing shortcut or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/canned-replies/{reply_id}":{"delete":{"tags":["Conversation Settings"],"summary":"Delete a canned reply","operationId":"deleteCannedReply","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"reply_id","in":"path","description":"Canned reply id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such canned reply in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Conversation Settings"],"summary":"Update a canned reply","operationId":"updateCannedReply","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"reply_id","in":"path","description":"Canned reply id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CannedReplyInput"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CannedReply"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such canned reply in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`canned_reply_shortcut_taken`: another reply uses the shortcut","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: missing shortcut or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/capabilities":{"get":{"tags":["Integrations"],"summary":"Get store capabilities","description":"How the store runs inventory, payments and freight: the registry of\ncapabilities and modules, and which modules the store has active.","operationId":"getStoreCapabilities","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCapabilities"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/capabilities/inventory":{"put":{"tags":["Integrations"],"summary":"Choose the inventory module","description":"`mobi`: Mobiari owns stock and reserves it at checkout. `tiny`: the ERP\nowns stock and Mobiari does not reserve.","operationId":"setInventoryMode","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetInventoryModeRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryModeResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_module`: not an inventory module","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/carts":{"get":{"tags":["Carts"],"summary":"List carts","description":"Most recently updated first. Storefront carts by default; pass\n`kind=quote` for carts built as quotes.","operationId":"listCarts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"`open` (being filled), `abandoned` (no activity for a while; recovery\nmessages go out) or `converted` (became an order).","enum":["open","abandoned","converted"]}},{"name":"kind","in":"query","description":"Defaults to `storefront`.","required":false,"schema":{"type":"string","description":"`storefront` (a shopper's cart) or `quote` (built at the counter and\nshared as a link; see Quotes).","enum":["storefront","quote"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_CartSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/carts/{cart_id}":{"get":{"tags":["Carts"],"summary":"Get a cart","description":"The cart with its lines, oldest line first.","operationId":"getCart","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cart_id","in":"path","description":"Cart id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such cart in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Carts"],"summary":"Delete a cart","description":"Removes the cart and its lines, freight quotes and stock reservations.\nAn order the cart became keeps its record. For clearing out test or\nstale carts.","operationId":"deleteCart","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cart_id","in":"path","description":"Cart id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such cart in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/categories":{"get":{"tags":["Categories"],"summary":"List categories","description":"Every category of the store by name, or only the children of\n`parent_id`, or only the top-level ones with `root_only=true`.","operationId":"listCategories","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"parent_id","in":"query","description":"Only the direct children of this category.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"root_only","in":"query","description":"Only top-level categories. Ignored with `parent_id`.","required":false,"schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Matches part of the name, case-insensitively.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Category"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Categories"],"summary":"Create a category","operationId":"createCategory","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`category_not_found`: the parent is not in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/categories/{category_id}":{"get":{"tags":["Categories"],"summary":"Get a category","operationId":"getCategory","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"category_id","in":"path","description":"Category id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`category_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Categories"],"summary":"Update a category","description":"Renaming also changes the slug.","operationId":"updateCategory","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"category_id","in":"path","description":"Category id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`category_not_found` (the category or the new parent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`, also when the parent would create a cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Categories"],"summary":"Delete a category","description":"Products lose the category; the products themselves are kept. Refused\nwhile the category has subcategories. Emits the `category.deleted`\nwebhook.","operationId":"deleteCategory","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"category_id","in":"path","description":"Category id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`category_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`category_has_children`: delete or move its subcategories first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/cms/collections":{"get":{"tags":["Content"],"summary":"List content collections","description":"The store's content collections by name.","operationId":"listCmsCollections","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include_archived","in":"query","description":"Include archived collections. Defaults to `false`.","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_CmsCollection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/cms/collections/{collection_slug}":{"get":{"tags":["Content"],"summary":"Get a content collection","description":"Archived collections are returned too.","operationId":"getCmsCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_slug","in":"path","description":"Collection slug, e.g. `hero_videos`","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsCollection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/cms/collections/{collection_slug}/documents":{"get":{"tags":["Content"],"summary":"List a collection's documents","description":"In display order (`position`, then creation).","operationId":"listCmsDocuments","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_slug","in":"path","description":"Collection slug, e.g. `hero_videos`","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_CmsDocument"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Content"],"summary":"Create a document","description":"Appends a document to the collection (or at `position`).","operationId":"createCmsDocument","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_slug","in":"path","description":"Collection slug, e.g. `hero_videos`","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDocumentRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsDocument"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/cms/collections/{collection_slug}/documents/reorder":{"post":{"tags":["Content"],"summary":"Reorder documents","description":"Sets `position` to each document's index in `document_ids`. Ids not in\nthe collection are ignored; documents left out keep their position.","operationId":"reorderCmsDocuments","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_slug","in":"path","description":"Collection slug, e.g. `hero_videos`","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderRequest"}}},"required":true},"responses":{"204":{"description":"Reordered"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection, or it is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/cms/collections/{collection_slug}/documents/{document_id}":{"get":{"tags":["Content"],"summary":"Get a document","operationId":"getCmsDocument","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_slug","in":"path","description":"Collection slug, e.g. `hero_videos`","required":true,"schema":{"type":"string"}},{"name":"document_id","in":"path","description":"Document id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsDocument"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection or document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Content"],"summary":"Update a document","description":"Fields left out stay as they are; `data` is replaced whole.","operationId":"updateCmsDocument","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_slug","in":"path","description":"Collection slug, e.g. `hero_videos`","required":true,"schema":{"type":"string"}},{"name":"document_id","in":"path","description":"Document id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDocumentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsDocument"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection or document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Content"],"summary":"Delete a document","operationId":"deleteCmsDocument","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_slug","in":"path","description":"Collection slug, e.g. `hero_videos`","required":true,"schema":{"type":"string"}},{"name":"document_id","in":"path","description":"Document id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Document deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection or document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/collection-products":{"post":{"tags":["Collections"],"summary":"Add a product to a collection","description":"Idempotent.","operationId":"addProductToCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionProductRequest"}}},"required":true},"responses":{"204":{"description":"Added"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `collection_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Collections"],"summary":"Remove a product from a collection","operationId":"removeProductFromCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionProductRequest"}}},"required":true},"responses":{"204":{"description":"Removed"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `collection_not_found`, or `not_found` when the product is not in the collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/collections":{"get":{"tags":["Collections"],"summary":"List collections","description":"By name.","operationId":"listCollections","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches part of the name, case-insensitively.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Collection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Collections"],"summary":"Create a collection","description":"Emits the `collections.created` webhook.","operationId":"createCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/collections/{collection_id}":{"get":{"tags":["Collections"],"summary":"Get a collection","operationId":"getCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`collection_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Collections"],"summary":"Update a collection","description":"Renaming also changes the slug. Emits the `collections.updated` webhook\nand purges the collection's storefront cache.","operationId":"updateCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`collection_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Collections"],"summary":"Delete a collection","description":"The products are kept. Emits the `collections.deleted` webhook.","operationId":"deleteCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`collection_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/collections/{collection_id}/products":{"get":{"tags":["Collections"],"summary":"List a collection's products","description":"Ids and titles in collection order. For full rows use\n`GET /products?collection_id=`.","operationId":"listCollectionProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_CollectionProductEntry"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`collection_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/collections/{collection_id}/sales-channels":{"get":{"tags":["Collections"],"summary":"Get a collection's sales channels","operationId":"getCollectionSalesChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelAssignment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`collection_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Collections"],"summary":"Set a collection's sales channels","operationId":"setCollectionSalesChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelAssignment"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelAssignment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`collection_not_found`, `sales_channel_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/component-candidates":{"get":{"tags":["Manufacturing"],"summary":"List component candidates","description":"Every variant of the store, not only the ones already used as parts, so\na new part can be picked into a bill of materials. Existing parts first.","operationId":"listComponentCandidates","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches SKU, name or product title.","required":false,"schema":{"type":"string"}},{"name":"exclude_variant_id","in":"query","description":"The kit being edited, left out so a variant cannot become a part of\nitself.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ComponentCandidate"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/components":{"get":{"tags":["Manufacturing"],"summary":"List components","description":"Every part of the store (variants created as parts or used in a bill of\nmaterials) with stock, how many kits use it, and what open build jobs\nstill need. Biggest shortfall first.","operationId":"listComponents","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches SKU, name or product title.","required":false,"schema":{"type":"string"}},{"name":"short_only","in":"query","description":"Only components whose open build demand exceeds what is available:\nwhat is blocking production.","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Component"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Manufacturing"],"summary":"Create a component","description":"Creates a part as a `draft` product with a single variant (draft keeps it\noff the storefront and the marketplace feeds; publish it like any product\nif it is also sold on its own). Opening stock is written to the ledger as\na `count` with reason `opening_balance`.","operationId":"createComponent","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Component"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`sku_taken`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`, `location_not_in_store`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/components/{variant_id}":{"delete":{"tags":["Manufacturing"],"summary":"Delete a component","description":"Refused while any kit lists the part (409 `component_in_use`, with\n`details.kits`): deleting it would silently drop a line from every such\nbill of materials. Also refused (409 `component_not_removable`) when the\npart is itself a kit, was sold, or holds reserved stock. Deletes its\nstock rows and history, and the wrapper product when it is an empty,\nunsold draft.","operationId":"deleteComponent","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"The component's variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`component_in_use` (`details.kits`), `component_not_removable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Manufacturing"],"summary":"Update a component","description":"A rename also renames the wrapper product when it exists only to carry\nthis part (a single-variant draft).","operationId":"updateComponent","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"The component's variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Component"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`sku_taken`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/components/{variant_id}/usage":{"get":{"tags":["Manufacturing"],"summary":"List where a component is used","description":"The kits whose bill of materials lists this part, with the quantity per\nkit and what their open build jobs still need.","operationId":"listComponentUsage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"The component's variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ComponentUsage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversation-channels":{"get":{"tags":["Conversation Settings"],"summary":"List inbox channels","operationId":"listConversationChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ConversationChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Conversation Settings"],"summary":"Create an inbox channel","description":"For WhatsApp prefer `POST .../conversation-channels/whatsapp/connect`\n(Meta Embedded Signup), which fills the credentials for you.","operationId":"createConversationChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationChannelCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `config` is not an object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversation-channels/meta-config":{"get":{"tags":["Conversation Settings"],"summary":"Get the WhatsApp signup configuration","description":"The Meta app id and Embedded Signup configuration to open the\n\"Connect with Facebook\" dialog.","operationId":"getWhatsappSignupConfig","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsappSignupConfig"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversation-channels/whatsapp/connect":{"post":{"tags":["Conversation Settings"],"summary":"Connect a WhatsApp number","description":"Finishes Meta's Embedded Signup: exchanges the dialog's code for a\nbusiness token, registers the number, subscribes the WhatsApp Business\naccount to this channel's webhook and stores the credentials encrypted.\nCreates the channel, or updates `channel_id`.","operationId":"connectWhatsappChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsappConnectRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsappConnectResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`meta_not_configured`, `no_whatsapp_account` or `no_phone_number`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`meta_error`: Meta refused the code or did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversation-channels/{channel_id}":{"delete":{"tags":["Conversation Settings"],"summary":"Delete an inbox channel","description":"Its conversations stay, detached from the channel.","operationId":"deleteConversationChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Channel id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Conversation Settings"],"summary":"Update an inbox channel","operationId":"updateConversationChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Channel id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationChannelUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `config` is not an object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversation-channels/{channel_id}/rotate-key":{"post":{"tags":["Conversation Settings"],"summary":"Rotate a channel's public key","description":"Issues a new widget key; the old one stops working at once, so update\nthe embed snippet on the site.","operationId":"rotateConversationChannelKey","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Channel id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversation-channels/{channel_id}/whatsapp-status":{"get":{"tags":["Conversation Settings"],"summary":"Check a WhatsApp channel","description":"Asks Meta whether the stored token still works and how the number\nstands (quality rating, status). A broken channel answers 200 with\n`ok: false`.","operationId":"getWhatsappChannelStatus","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Channel id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsappChannelStatus"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such WhatsApp channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","description":"The inbox, one page at a time. With the default `activity` sort the\nnewest activity comes first and pages are cursor-based, so a\nconversation that gets a new message while you page moves to the head\ninstead of shifting the pages; keep the list fresh with the\n`conversation:new` and `conversation:updated` events of the agent\nWebSocket (`/ws/conversations`). For badge counts use\n`GET /stores/{store_id}/conversations/counts`.","operationId":"listConversations","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only conversations in this status. Omit for every status.","required":false,"schema":{"$ref":"#/components/schemas/ConversationStatus"}},{"name":"assignee","in":"query","description":"`me` (the caller), `unassigned`, or a user id.","required":false,"schema":{"type":"string"}},{"name":"channel_kind","in":"query","description":"Only conversations on this kind of channel.","required":false,"schema":{"$ref":"#/components/schemas/ConversationChannelKind"}},{"name":"channel_id","in":"query","description":"Only conversations on this channel.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"tag","in":"query","description":"Only conversations with this label.","required":false,"schema":{"type":"string"}},{"name":"priority","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ConversationPriority"}},{"name":"customer_id","in":"query","description":"Only conversations with this customer.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"unread","in":"query","description":"Only conversations with contact messages the team has not read.","required":false,"schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Free text over the contact's name, e-mail, phone, WhatsApp number\nand the messages.","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Defaults to `activity`. `activity` and `newest` page by cursor;\n`waiting` and `priority` by offset.","required":false,"schema":{"type":"string","description":"Order of the conversation list.","enum":["activity","waiting","priority","newest"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ConversationListItem"}}}},"400":{"description":"`invalid_assignee`: `assignee` is not `me`, `unassigned` or a user id; `invalid_cursor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations-ai":{"get":{"tags":["Conversation Settings"],"summary":"Get the chat bot settings","operationId":"getConversationBotSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBotSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Conversation Settings"],"summary":"Update the chat bot settings","description":"Fields left out keep their value.","operationId":"updateConversationBotSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBotSettingsUpdate"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBotSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/bulk":{"post":{"tags":["Conversations"],"summary":"Act on many conversations","description":"Assign, resolve, reopen, snooze, reprioritize, label or mark read up to\n200 conversations at once. Each one publishes `conversation:updated`;\nthe whole action is recorded in the audit log.","operationId":"bulkUpdateConversations","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBulkRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBulkResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: no ids or more than 200, a bad `value` for the action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/counts":{"get":{"tags":["Conversations"],"summary":"Count conversations","description":"Per-status totals and unread counts for the whole store, in one cheap\nquery. Poll it for a badge or refresh it on `conversation:updated`.","operationId":"getConversationCounts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCounts"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/reports":{"get":{"tags":["Conversations"],"summary":"Get the attendance report","description":"Volume, response and resolution times, satisfaction, per-agent numbers,\nattributed revenue and labels over the last `days`.","operationId":"getConversationReport","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","description":"Window in days, 1 to 365. Defaults to 30.","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationReport"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/stats":{"get":{"tags":["Conversations"],"summary":"Get inbox stats","operationId":"getConversationStats","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationStats"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/ws-ticket":{"post":{"tags":["Conversations"],"summary":"Get a WebSocket ticket","description":"Browsers cannot set an `Authorization` header on a WebSocket, so they\ntrade their token for a single-use, one-minute ticket and connect to\n`wss://api.mobiari.com/ws/conversations?ticket=...`. Native clients can\nskip this and connect with `Authorization: Bearer` and `?store_id=`.\nSee the realtime guide for the events.","operationId":"createConversationSocketTicket","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationSocketTicket"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}":{"get":{"tags":["Conversations"],"summary":"Get a conversation","description":"The conversation with its internal notes, the matched customer and\ntheir latest orders. Messages are paged separately.","operationId":"getConversation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Conversations"],"summary":"Update a conversation","description":"Change status (resolve, reopen, snooze), assignee, priority, labels,\nbot, contact details or the linked customer. Publishes\n`conversation:updated`; resolving also emits the\n`conversations.resolved` event, and turning the bot off hands over.","operationId":"updateConversation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConversationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `snoozed_until` in the past, an assignee who is not on the store's team, `unassign` together with an assignee, or a customer of another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart":{"get":{"tags":["Conversations"],"summary":"Get the conversation's cart","description":"The assisted-sale cart: one per conversation, shared live with the bot\nand the contact (`cart:updated` events). 404 `no_cart` until the first\nitem is added.","operationId":"getConversationCart","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCart"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation, or `no_cart`: it has no usable cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/customer":{"get":{"tags":["Conversations"],"summary":"Get the cart's contact details","description":"What the order will be placed with, and what is still missing before a\nPIX can be generated.","operationId":"getConversationCartCustomer","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCartCustomer"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Conversations"],"summary":"Set the cart's contact details","description":"Merges the details into the cart (fields left out are kept), fills the\nconversation's blank contact fields and links a matching customer.\nOpens a cart when there is none.","operationId":"updateConversationCartCustomer","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCartCustomerInput"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCartCustomer"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_document`: not a valid CPF","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/freight":{"post":{"tags":["Conversations"],"summary":"Quote or select freight","description":"With `cep`: quotes the cart's shipping options (and remembers the CEP\non the cart). With `option_id`: selects that option and returns the\ncart with the new total.","operationId":"conversationCartFreight","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationFreightRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationFreightResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_cart`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed` (neither `cep` nor `option_id`), `freight_quote_failed` or `freight_option_invalid`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/items":{"post":{"tags":["Conversations"],"summary":"Add an item to the conversation's cart","description":"Opens the cart (a quote cart valid for 14 days) on first use. Adding a\nvariant already in the cart raises its quantity.","operationId":"addConversationCartItem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCartItemRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCart"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`insufficient_stock`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`variant_unavailable`: not a sellable variant of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/items/{variant_id}":{"delete":{"tags":["Conversations"],"summary":"Remove an item from the cart","operationId":"removeConversationCartItem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The cart without the item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCart"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_cart`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Conversations"],"summary":"Change an item's quantity","operationId":"setConversationCartItem","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCartQuantityRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCart"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_cart` or `insufficient_stock`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/pix":{"post":{"tags":["Conversations"],"summary":"Charge the cart by PIX","description":"Turns the cart into an order, creates the PIX charge (or reuses a live\none for the same order) and posts it into the conversation as the\ncaller: a message with the QR code card, then one with just the\ncopy-and-paste code. Needs the contact details and freight\n(`GET .../cart/customer` says what is missing).","operationId":"createConversationCartPix","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationPixSent"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_cart` or `insufficient_stock`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`missing_info` (details: `missing`), `checkout_failed`, `pix_failed` or `whatsapp_window_closed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/reset":{"post":{"tags":["Conversations"],"summary":"Detach the cart","description":"The next item added opens a fresh cart. The old cart is left as it is:\nits link keeps working until it expires.","operationId":"resetConversationCart","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Detached"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/search":{"get":{"tags":["Conversations"],"summary":"Search variants to sell","description":"Active, sellable variants of the store's products (components never),\nbest title match first. `limit` defaults to 12 here.","operationId":"searchConversationCartVariants","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Product title, variant title, SKU or slug. Empty lists everything.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ConversationVariantHit"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/cart/send":{"post":{"tags":["Conversations"],"summary":"Send the payment link","description":"Posts the cart's payment link into the conversation as the caller (and\ndelivers it on WhatsApp or e-mail). The message carries the cart\nsnapshot in `payload.cart`, so clients render a cart card. Takes the\nconversation over like a reply, and follows the same WhatsApp 24-hour\nrule.","operationId":"sendConversationCartLink","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"description":"Optional","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCartLinkRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessageSent"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_cart` or `empty_cart`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`whatsapp_window_closed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/messages":{"get":{"tags":["Conversations"],"summary":"List a conversation's messages","description":"Newest first, paged by cursor: the first page is the latest `limit`\nmessages, `next_cursor` (or `before`) goes further back. Reverse a page\nto render it top to bottom.\n\nWith `after` (a message id) or `created_after` (a time) the order flips\nto oldest first and the page holds what came after it: use it to fetch\nwhat you missed while the WebSocket was down, following `next_cursor`\n(together with the same `after`) until `has_more` is false.\n\nInternal notes are not messages; they come with the conversation.","operationId":"listConversationMessages","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"before","in":"query","description":"Only messages older than this message: scroll back from it. Same as\nfollowing `next_cursor`.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"after","in":"query","description":"Only messages newer than this message, **oldest first**: catch up\nafter a reconnect. Keep passing it with `cursor` to continue.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"created_after","in":"query","description":"Only messages created after this instant, oldest first (like\n`after`, when you have a time rather than a message).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ConversationMessage"}}}},"400":{"description":"`invalid_cursor`, or `before` combined with `after`/`created_after` (`conflicting_parameters`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation, or the `before`/`after` message is not in it (`message_not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Conversations"],"summary":"Send a reply","description":"Posts a team message and delivers it on the conversation's channel\n(WhatsApp, e-mail, or the widget live). Answering takes the conversation\nover: the bot stops, the sender becomes the assignee if there is none,\nand a pending or snoozed conversation reopens.\n\nDelivery is asynchronous: the message comes back with\n`delivery_status` `sent`, and `message:updated` events on the WebSocket\nreport `delivered`, `read` or `failed` (with `delivery_error`).\n\n**WhatsApp 24-hour rule.** Meta accepts free-form messages only within\n24 hours of the contact's last message. Outside that window this call\nanswers 422 `whatsapp_window_closed` and nothing is stored; the\nconversation's `reply_window_expires_at` says when the window closes.\n\nSend an `Idempotency-Key` header: a retry after a lost response then\nreturns the first message instead of sending it twice.","operationId":"sendConversationMessage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationReplyRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessageSent"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`empty_message`, `message_too_long` (over 4096 characters), or `whatsapp_window_closed` (details: `window_expired_at`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{index}":{"get":{"tags":["Conversations"],"summary":"Download an attachment","description":"The file of a message attachment, streamed from where it lives\n(WhatsApp media or the e-mail mailbox). This is the `url` of the\nmessage's `attachments` entries; call it with the usual\n`Authorization` header.","operationId":"downloadConversationAttachment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"message_id","in":"path","description":"Message id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"index","in":"path","description":"The attachment's `index`","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"The file, with the content type it was sent with (`image/*`, `audio/*`, `video/*`, `application/pdf`, ...; `application/octet-stream` when unknown) and a `Content-Disposition` carrying its name","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/ConversationAttachmentFile"}},"application/pdf":{"schema":{"$ref":"#/components/schemas/ConversationAttachmentFile"}},"audio/*":{"schema":{"$ref":"#/components/schemas/ConversationAttachmentFile"}},"image/*":{"schema":{"$ref":"#/components/schemas/ConversationAttachmentFile"}},"video/*":{"schema":{"$ref":"#/components/schemas/ConversationAttachmentFile"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such message or attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`attachment_unavailable`: the provider did not return the file (WhatsApp media expires after 30 days)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/notes":{"post":{"tags":["Conversations"],"summary":"Add an internal note","description":"A note only the team sees; it is never delivered to the contact.\nPublishes `note:new` to the agent WebSocket.","operationId":"createConversationNote","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationNoteRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationNote"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/notes/{note_id}":{"delete":{"tags":["Conversations"],"summary":"Delete an internal note","operationId":"deleteConversationNote","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"note_id","in":"path","description":"Note id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such note on this conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/read":{"post":{"tags":["Conversations"],"summary":"Mark a conversation as read","description":"Clears `unread_for_agents` for the whole team and marks the contact's\nmessages read. Publishes `conversation:updated` when something changed.","operationId":"markConversationRead","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Marked read"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/suggest":{"post":{"tags":["Conversations"],"summary":"Suggest a reply","description":"A draft from the knowledge base, the customer's orders and the thread,\nin the brand's voice. Never sent by itself.","operationId":"suggestConversationReply","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"description":"Optional","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationSuggestRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationSuggestion"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`assistant_failed`: the model call failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/summary":{"post":{"tags":["Conversations"],"summary":"Summarize a conversation","description":"What the contact wants, what was done and what is pending, from the AI\nmodel. Stored on the conversation (`attributes.summary`) and reused\nuntil a new message arrives.","operationId":"summarizeConversation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationSummaryResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`assistant_failed`: the model call failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/conversations/{conversation_id}/typing":{"post":{"tags":["Conversations"],"summary":"Signal typing","description":"Shows the contact (web widget) and the other agents that you are\ntyping. The agent WebSocket's `typing` message does the same without an\nHTTP round trip. Repeat it every few seconds while typing; indicators\nexpire on their own.","operationId":"setConversationTyping","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationTypingRequest"}}},"required":true},"responses":{"204":{"description":"Published"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such conversation in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers":{"get":{"tags":["Customers"],"summary":"List customers","description":"Newest first (`created_at`, then `id`). Paged by keyset: follow\n`next_cursor`, or pass `offset` (with `include_total=true`) for a\npage-number table. Each row carries its `lifecycle` stage; `acquisition`\nis only on the customer record.","operationId":"listCustomers","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches name (first, last or full), e-mail, phone, company or\ndocument. Digits in the query also match phone and document\nignoring punctuation, so `11 98765-4321` finds `+5511987654321`.","required":false,"schema":{"type":"string"}},{"name":"tag","in":"query","description":"Only customers with this tag.","required":false,"schema":{"type":"string"}},{"name":"lifecycle","in":"query","required":false,"schema":{"type":"string","description":"Where a customer is in their relationship with the store, derived from\ntheir paid orders:\n\n| Stage | Meaning |\n| --- | --- |\n| `vip` | Spent at least the store's 90th percentile. |\n| `new` | No paid order yet. |\n| `active` | Last order within 60 days. |\n| `at_risk` | Last order 60 to 180 days ago. |\n| `dormant` | Last order more than 180 days ago. |","enum":["new","active","at_risk","dormant","vip"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Customer"}}}},"400":{"description":"`invalid_cursor`, `invalid_limit` or `invalid_offset`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Customers"],"summary":"Create a customer","description":"Emits the `customers.created` webhook.","operationId":"createCustomer","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`customer_email_exists`: the e-mail belongs to another customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/duplicates":{"get":{"tags":["Customers"],"summary":"List duplicate customers","description":"Groups of customers in the store sharing an e-mail address or phone\nnumber, candidates for a merge. At most 200 groups are considered.","operationId":"listCustomerDuplicates","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_DuplicateGroup"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}":{"get":{"tags":["Customers"],"summary":"Get a customer","description":"The customer record: profile, lifecycle stage, first-touch acquisition,\nsaved addresses, the 50 most recent timeline entries and the 50 most\nrecent orders with their payment method and shipments. To find the\ncustomer of an order, read the order's `customer_id`.","operationId":"getCustomer","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`customer_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Customers"],"summary":"Delete a customer","description":"Removes the customer with their addresses, identities and timeline;\ntheir orders stay, without a customer. For an LGPD erasure that keeps\nthe order history anonymized, use `POST .../erase`. Emits the\n`customers.deleted` webhook.","operationId":"deleteCustomer","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`customer_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`customer_in_use`: records that cannot lose their customer still point at it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Customers"],"summary":"Update a customer","description":"Partial: omitted fields keep their value. Emits the `customers.updated`\nwebhook.","operationId":"updateCustomer","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`customer_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`customer_email_exists`: the e-mail belongs to another customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/addresses":{"get":{"tags":["Customers"],"summary":"List a customer's addresses","description":"Default addresses first, then newest.","operationId":"listCustomerAddresses","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_CustomerAddress"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`customer_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Customers"],"summary":"Add an address to a customer","description":"With `is_default: true`, the customer's previous default address of the\nsame type stops being the default.","operationId":"createCustomerAddress","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddressCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddress"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`customer_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/addresses/{address_id}":{"delete":{"tags":["Customers"],"summary":"Delete a customer address","operationId":"deleteCustomerAddress","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"address_id","in":"path","description":"Address id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such address for this customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Customers"],"summary":"Update a customer address","description":"Partial: omitted fields keep their value. `is_default: true` clears the\nprevious default of the (resulting) address type.","operationId":"updateCustomerAddress","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"address_id","in":"path","description":"Address id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddressUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerAddress"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such address for this customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/consent":{"post":{"tags":["Customers"],"summary":"Record a customer's consent","description":"Staff records consent obtained outside the storefront (verbally at the\ncounter, a WhatsApp opt-in) with where it came from. Granting e-mail\nconsent also lifts an earlier unsubscribe suppression.","operationId":"setCustomerConsent","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentReq"}}},"required":true},"responses":{"204":{"description":"Consent recorded"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/email-activity":{"get":{"tags":["Customers"],"summary":"Get a customer's e-mail activity","description":"Consent (with its source), deliverability status, lead score and topics,\nand the 200 most recent sends, opens, clicks and provider events.","operationId":"getCustomerEmailActivity","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerEmailActivity"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such customer in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/erase":{"post":{"tags":["Customers"],"summary":"Erase a customer's personal data (LGPD)","description":"Scrubs personal fields from the customer and every record that holds\nthem, deletes addresses, identities, notes and subscriptions, and adds\nthe address to the suppression list so the person is never e-mailed\nagain. Orders and fiscal documents stay, as the law requires, pointing\nat the anonymized record. Cannot be undone.","operationId":"eraseCustomerData","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"description":"Optional reason, kept in the audit log","content":{"application/json":{"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EraseReq"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EraseResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such customer in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/export":{"get":{"tags":["Customers"],"summary":"Export a customer's data (LGPD)","description":"Everything held about one customer, as a downloadable JSON document:\nprofile, addresses, identities, consent, orders, conversations with\nmessages, e-mail activity, subscriptions, visits and journey runs. The\nexport is recorded in the audit log.","operationId":"exportCustomerData","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The data bundle, sent as an attachment (`cliente-<id>.json`)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such customer in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/graph":{"get":{"tags":["Customers"],"summary":"Get a customer's identity graph","description":"Identities, per-channel reachability and consent, the recent consent\nledger and likely duplicates, in one response.","operationId":"getCustomerGraph","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGraph"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such customer in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/interactions":{"get":{"tags":["Customers"],"summary":"List a customer's timeline entries","description":"Newest first, keyset-paged: follow `next_cursor` (or pass `offset`).\nTeam notes and system events alike; the CRM timeline\n(`GET .../timeline`) merges these with orders, messages and consent.","operationId":"listCustomerInteractions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_CustomerInteraction"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`customer_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Customers"],"summary":"Log a timeline entry","description":"A note, call, e-mail or meeting logged by the signed-in user, who is\nrecorded as its author.","operationId":"createCustomerInteraction","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerInteractionCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerInteraction"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`customer_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty interaction_type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/merge":{"post":{"tags":["Customers"],"summary":"Merge a duplicate into a customer","description":"Every record pointing at `from_customer_id` (orders, conversations,\ne-mail activity, identities, consent) is repointed to the customer in\nthe path, profile gaps are filled from the duplicate, tags and consent\nare unioned, and the duplicate is deleted. The merge is recorded in the\naudit log with a snapshot of the deleted record.","operationId":"mergeCustomers","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"The customer to keep","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeReq"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Either customer is not in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`same_customer`: both ids are the same","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/customers/{customer_id}/timeline":{"get":{"tags":["Customers"],"summary":"Get a customer's timeline","description":"Orders, conversations, e-mail activity, storefront visits, consent\nchanges and journey runs for one customer, newest first. Covers the 300\nmost recent events.","operationId":"getCustomerTimeline","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customer_id","in":"path","description":"Customer id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_TimelineEvent"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/dashboard/attention":{"get":{"tags":["Analytics"],"summary":"Get what needs attention","description":"Orders to fulfil or awaiting payment, low and out-of-stock variants,\nfailed or waiting automations, pending assistant proposals, overdue\npurchase orders, recently abandoned carts and reviews to moderate.","operationId":"getDashboardAttention","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardAttention"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/dashboard/stats":{"get":{"tags":["Analytics"],"summary":"Get dashboard numbers","description":"Products, customers, pending orders and paid revenue for the period,\neach with its change against the previous period, plus today's paid\nrevenue and orders, recent activity, daily storefront traffic and\ndaily revenue and order series.\n\nDays are computed in the store's time zone (returned as `timezone`);\nsee `DashboardStats` for the exact boundaries and what each series\ncounts.","operationId":"getDashboardStats","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"range","in":"query","description":"KPIs, deltas and the charts all follow this window, in the store's\ntime zone. Defaults to `month`.","required":false,"schema":{"type":"string","description":"The period the dashboard covers.","enum":["7d","30d","90d","month"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardStats"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/delivery-zones":{"get":{"tags":["Freight"],"summary":"List delivery zones","description":"By `sort_order`, then the start of the range.","operationId":"listDeliveryZones","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_DeliveryZone"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Freight"],"summary":"Create a delivery zone","operationId":"createDeliveryZone","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryZoneRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryZone"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty label, invalid CEP range or negative price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/delivery-zones/{zone_id}":{"put":{"tags":["Freight"],"summary":"Update a delivery zone","description":"`label`, the CEP range and the price are replaced; omitted optional\nfields keep their value, and `null` clears `description` or\n`delivery_days`.","operationId":"updateDeliveryZone","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"zone_id","in":"path","description":"Delivery zone id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryZoneUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryZone"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such zone in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty label, invalid CEP range or negative price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Freight"],"summary":"Delete a delivery zone","operationId":"deleteDeliveryZone","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"zone_id","in":"path","description":"Delivery zone id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such zone in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/discount-codes":{"get":{"tags":["Discounts"],"summary":"List discount codes","description":"Newest first.","operationId":"listDiscountCodes","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches part of the code, case-insensitively.","required":false,"schema":{"type":"string"}},{"name":"is_active","in":"query","description":"Only active (`true`) or inactive (`false`) codes.","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_DiscountCode"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Discounts"],"summary":"Create a discount code","description":"Emits the `discount.created` webhook.","operationId":"createDiscountCode","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountCodeCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountCode"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`discount_code_exists`: the store already has this code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/discount-codes/validate":{"post":{"tags":["Discounts"],"summary":"Validate a discount code","description":"Answers 200 whether or not the code applies; read `valid` and `reason`.\nDoes not reserve a use.","operationId":"validateDiscountCode","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountCodeValidateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountCodeValidation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/discount-codes/{code_id}":{"put":{"tags":["Discounts"],"summary":"Update a discount code","description":"Partial: omitted fields keep their value, an explicit `null` clears a\nnullable one. Emits the `discount.updated` webhook.","operationId":"updateDiscountCode","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"code_id","in":"path","description":"Discount code id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountCodeUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountCode"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such code in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`discount_code_exists`: the store already has this code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Discounts"],"summary":"Delete a discount code","description":"A code that orders already used cannot be deleted (their records point\nat it): deactivate it instead. Emits the `discount.deleted` webhook.","operationId":"deleteDiscountCode","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"code_id","in":"path","description":"Discount code id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such code in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`discount_code_in_use`: orders used this code; deactivate it instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/discounts":{"get":{"tags":["Discounts"],"summary":"List automatic discounts","description":"Highest `priority` first, then newest.","operationId":"listAutomaticDiscounts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include_inactive","in":"query","description":"Include inactive rules. Defaults to true.","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AutomaticDiscount"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Discounts"],"summary":"Create an automatic discount","description":"Takes effect on the storefront right away: every cached storefront page\nis purged, since the discount preview appears on all of them.","operationId":"createAutomaticDiscount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticDiscountCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticDiscount"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: value out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/discounts/{discount_id}":{"put":{"tags":["Discounts"],"summary":"Update an automatic discount","description":"Partial: omitted fields keep their value, an explicit `null` clears a\nnullable one. Purges the cached storefront pages.","operationId":"updateAutomaticDiscount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"discount_id","in":"path","description":"Automatic discount id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticDiscountUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomaticDiscount"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such discount in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: value out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Discounts"],"summary":"Delete an automatic discount","description":"Orders that already applied it keep their discount. Purges the cached\nstorefront pages.","operationId":"deleteAutomaticDiscount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"discount_id","in":"path","description":"Automatic discount id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such discount in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/domains":{"get":{"tags":["Storefront"],"summary":"List storefront domains","description":"The store's platform domain and custom domains.","operationId":"listDomains","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_DomainOut"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Storefront"],"summary":"Add a custom domain","description":"Registers the hostname unverified and returns the TXT record to\npublish (`txt_record_name` = `dns_challenge`). Then call\n`POST .../domains/{domain_id}/verify`.","operationId":"addDomain","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDomainRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainOut"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`hostname_already_exists`: registered by a store already","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_hostname`; `reserved_platform_domain`: a domain the platform owns (or a subdomain of it); `reserved_suffix`: a platform hostname","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/domains/{domain_id}":{"delete":{"tags":["Storefront"],"summary":"Remove a custom domain","description":"The storefront stops answering on it. The platform domain cannot be\nremoved.","operationId":"deleteDomain","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain_id","in":"path","description":"Domain id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Domain removed"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such custom domain in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/domains/{domain_id}/primary":{"post":{"tags":["Storefront"],"summary":"Make a domain primary","description":"The domain becomes the store's canonical URL in product feeds,\nsitemaps and other absolute links. Must be verified; platform and\ncustom domains both qualify.","operationId":"setPrimaryDomain","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain_id","in":"path","description":"Domain id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Primary domain set"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such domain in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`domain_not_verified`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/domains/{domain_id}/verify":{"post":{"tags":["Storefront"],"summary":"Verify a custom domain","description":"Looks up the TXT record now. 200 when it matches: the domain is\nverified and published to the edge, which then issues its certificate.\n202 when it does not match yet (DNS can take a while); the failure is\ncounted and the call can be repeated.","operationId":"verifyDomain","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain_id","in":"path","description":"Domain id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainOut"}}}},"202":{"description":"Not verified yet: the TXT record was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainOut"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such custom domain in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_challenge`: the domain has no verification challenge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email-templates":{"get":{"tags":["Transactional Email"],"summary":"List transactional e-mails","description":"Every e-mail the store sends on its own (order confirmation, shipping,\npassword reset...), with the subject it uses today and whether the store\nchanged it.","operationId":"listTransactionalEmails","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_TransactionalEmailSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email-templates/{event}":{"get":{"tags":["Transactional Email"],"summary":"Get a transactional e-mail","description":"The effective template with its defaults, the block catalog and the\nmerge variables of the event.","operationId":"getTransactionalEmail","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","description":"Transactional e-mail event, e.g. `order.paid`","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionalEmailDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Transactional Email"],"summary":"Save a transactional e-mail","description":"Stores the store's version of the e-mail, replacing any earlier one. The\nnext send of the event uses it.","operationId":"saveTransactionalEmail","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","description":"Transactional e-mail event, e.g. `order.paid`","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveTransactionalEmailRequest"}}},"required":true},"responses":{"204":{"description":"Saved"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty subject, or empty body in `html` mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Transactional Email"],"summary":"Reset a transactional e-mail","description":"Drops the store's version; the shipped default takes over again. Resetting\nan e-mail the store never changed does nothing.","operationId":"resetTransactionalEmail","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","description":"Transactional e-mail event, e.g. `order.paid`","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Reset"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email-templates/{event}/preview":{"post":{"tags":["Transactional Email"],"summary":"Preview a transactional e-mail","description":"Renders the template in the request body (not the saved one) with sample\ndata and the store's brand kit, so an editor can preview unsaved edits.","operationId":"previewTransactionalEmail","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","description":"Transactional e-mail event, e.g. `order.paid`","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewTransactionalEmailRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderedEmailPreview"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email-templates/{event}/test":{"post":{"tags":["Transactional Email"],"summary":"Send a transactional e-mail test","description":"Sends the template in the request body, rendered with sample data, to one\ninbox with `[teste]` before the subject. Nothing is saved.","operationId":"testTransactionalEmail","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","description":"Transactional e-mail event, e.g. `order.paid`","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestTransactionalEmailRequest"}}},"required":true},"responses":{"204":{"description":"Sent"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `to` is not an e-mail address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`email_send_failed`: the provider refused it; `error` says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/audience-preview":{"post":{"tags":["Email"],"summary":"Preview a campaign audience","description":"Resolves the filter the way a send would and counts who it reaches.","operationId":"previewEmailAudience","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAudienceFilter"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAudiencePreview"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts":{"get":{"tags":["Email"],"summary":"List campaigns","description":"The store's e-mail campaigns, newest first.","operationId":"listEmailBroadcasts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailBroadcast"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Email"],"summary":"Create a campaign","description":"Copies subject and body from `template_id` unless overridden. Without\n`scheduled_at` the campaign is a `draft` until sent; with it, it is\n`scheduled` and goes out on its own at that time.","operationId":"createEmailBroadcast","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmailBroadcastRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBroadcast"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: no subject or body (neither the template nor the overrides give one), or `template_id` is not a template of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts/{broadcast_id}":{"get":{"tags":["Email"],"summary":"Get a campaign","operationId":"getEmailBroadcast","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBroadcast"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such campaign in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Email"],"summary":"Delete a campaign","description":"Any campaign that is not sending right now; its recipients and events go\nwith it.","operationId":"deleteEmailBroadcast","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such campaign in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`broadcast_sending`: it is being sent; cancel it first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Email"],"summary":"Update a campaign","description":"Changes the fields sent while the campaign is a draft or scheduled.\nSetting `scheduled_at` schedules it. The body is frozen once sending\nstarts.","operationId":"updateEmailBroadcast","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailBroadcastRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBroadcast"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such campaign in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`broadcast_in_flight`: already sending or sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `template_id` is not a template of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts/{broadcast_id}/ab":{"get":{"tags":["Email"],"summary":"Get a campaign's A/B results","description":"Sends, opens and clicks per subject variant.","operationId":"getEmailBroadcastAbResults","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAbResults"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts/{broadcast_id}/cancel":{"post":{"tags":["Email"],"summary":"Cancel a campaign","description":"Stops a draft, scheduled or sending campaign. Recipients already sent to\nstay sent.","operationId":"cancelEmailBroadcast","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBroadcast"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such campaign in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`broadcast_not_cancellable`: already sent, failed or cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts/{broadcast_id}/recipients":{"get":{"tags":["Email"],"summary":"List a campaign's recipients","description":"Newest first, optionally one delivery state only.","operationId":"listEmailBroadcastRecipients","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only recipients in this state (`pending`, `sent`, `delivered`,\n`failed`, `bounced`...).","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailRecipient"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts/{broadcast_id}/report":{"get":{"tags":["Email"],"summary":"Get a campaign report","description":"Delivery funnel and rates, opens and clicks over time, top links, bounces,\ntime to first open, and revenue from recipients who engaged (orders within\n7 days of their send).","operationId":"getEmailBroadcastReport","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailCampaignReport"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such campaign in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts/{broadcast_id}/resend-unopened":{"post":{"tags":["Email"],"summary":"Resend to non-openers","description":"Creates a follow-up campaign, with a new subject and the same body, for\neveryone who received the original and did not open it. With `send_now`\n(the default) it is scheduled for now and goes out within a minute.","operationId":"resendEmailBroadcastToUnopened","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendUnopenedRequest"}}},"required":true},"responses":{"201":{"description":"The follow-up campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBroadcast"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such campaign in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`no_unopened_recipients`: everyone opened it, or nothing was delivered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/broadcasts/{broadcast_id}/send":{"post":{"tags":["Email"],"summary":"Send a campaign now","description":"Moves a draft or scheduled campaign to `sending` and starts the send in\nthe background; answers 202 with the campaign. Recipients are written as\nthe audience resolves and go out over the next minutes (A/B tests and\nsend-time optimization spread them further).","operationId":"sendEmailBroadcast","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"broadcast_id","in":"path","description":"Campaign (broadcast) id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"Sending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBroadcast"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such campaign in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`broadcast_not_sendable`: not a draft or scheduled campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/config":{"get":{"tags":["Transactional Email"],"summary":"Get the e-mail settings","description":"Sender identity, provider, reply routing and preference-center topics.","operationId":"getEmailSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Transactional Email"],"summary":"Update the e-mail settings","description":"Changes the fields sent and records an audit entry.","operationId":"updateEmailSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailSettingsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: unknown `provider` or `inbox_mode`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/contacts/import":{"post":{"tags":["Email"],"summary":"Import contacts from a CSV","description":"Creates or updates customers by e-mail: fills missing names and phone,\nadds tags, and opts in (recording `source`) contacts not opted in yet\nwhen the row or the form says so. Existing consent is never withdrawn.\nBodies up to 30 MB.","operationId":"importEmailContacts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/EmailContactImportForm"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailContactImportResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`csv_missing_file`, `csv_empty` or `csv_missing_email_column`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/design-catalog":{"get":{"tags":["Email"],"summary":"Get the e-mail design catalog","description":"Block types, starter designs and merge variables for the e-mail editor.","operationId":"getEmailDesignCatalog","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDesignCatalog"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/domains":{"get":{"tags":["Email Deliverability"],"summary":"List sending domains","description":"The store's SES sending domains with the DNS records to publish. Pending\ndomains not checked in the last 30 seconds are re-checked with SES first.","operationId":"listEmailDomains","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailDomain"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Email Deliverability"],"summary":"Add a sending domain","description":"Creates the SES identity (Easy DKIM and a custom MAIL FROM) and returns\nthe DNS records to publish. Adding a domain the store already has returns\nit refreshed.","operationId":"addEmailDomain","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddEmailDomainRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDomain"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`email_domain_taken`: another store sends from it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: not a domain; `platform_domain_reserved`: one of the platform's own domains","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`ses_error`: SES refused it; `error` says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/domains/{domain_id}":{"delete":{"tags":["Email Deliverability"],"summary":"Remove a sending domain","description":"Deletes the SES identity too (except the platform's own domains). Mail\nfrom this domain falls back to the platform identity.","operationId":"deleteEmailDomain","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain_id","in":"path","description":"Sending domain id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such domain in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/domains/{domain_id}/check":{"post":{"tags":["Email Deliverability"],"summary":"Check a sending domain","description":"Asks SES for the domain's verification state now.","operationId":"checkEmailDomain","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain_id","in":"path","description":"Sending domain id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDomain"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such domain in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`ses_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/forms":{"get":{"tags":["Email"],"summary":"List subscription forms","description":"The store's embeddable sign-up forms with their embed code, newest first.","operationId":"listEmailForms","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailForm"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Email"],"summary":"Create a subscription form","operationId":"createEmailForm","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailFormRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailForm"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`email_form_slug_taken`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty name, or `welcome_template_id` is not a template of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/forms/{form_id}":{"put":{"tags":["Email"],"summary":"Replace a subscription form","description":"Every setting is replaced by the request's (absent `fields` keep theirs).","operationId":"updateEmailForm","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"form_id","in":"path","description":"Form id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailFormRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailForm"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such form in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`email_form_slug_taken`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Email"],"summary":"Delete a subscription form","description":"Embedded copies stop accepting submissions. Contacts it collected stay.","operationId":"deleteEmailForm","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"form_id","in":"path","description":"Form id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such form in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/health":{"get":{"tags":["Email Deliverability"],"summary":"Get e-mail deliverability health","description":"Campaign delivery, bounce, complaint and open rates over 30 days, the\nsuppression count, verified domains and the platform's SES quota.","operationId":"getEmailHealth","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailHealth"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/overview":{"get":{"tags":["Email"],"summary":"Get the e-mail overview","description":"List health and growth, the last campaigns, when subscribers open, and\nrevenue attributed to e-mail over 90 days.","operationId":"getEmailOverview","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailOverview"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/product-subscriptions":{"get":{"tags":["Email"],"summary":"List product subscriptions","description":"Back-in-stock and price-drop sign-ups from the storefront, newest first.","operationId":"listProductSubscriptions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ProductSubscription"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/product-subscriptions/summary":{"get":{"tags":["Email"],"summary":"Summarize product subscriptions","operationId":"getProductSubscriptionSummary","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSubscriptionSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/products":{"get":{"tags":["Email"],"summary":"List products for e-mails","description":"Product cards for the e-mail editor's picker: active products matching\n`q`, most recently updated first, or exactly the products in `ids`.\nAt most 64 per page; `total` is not available.","operationId":"listEmailProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Search active products by title.","required":false,"schema":{"type":"string"}},{"name":"ids","in":"query","description":"Comma-separated product ids to resolve, in that order (any status).","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailProductCard"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/segments":{"get":{"tags":["Email"],"summary":"List segments","description":"The store's saved segments by name, each with its current member count.","operationId":"listEmailSegments","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailSegment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Email"],"summary":"Create a segment","operationId":"createEmailSegment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSegmentRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSegment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/segments/fields":{"get":{"tags":["Email"],"summary":"List segment fields","description":"The fields and operators segment rules can use.","operationId":"listEmailSegmentFields","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmailSegmentField"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/segments/preview":{"post":{"tags":["Email"],"summary":"Preview segment rules","description":"Counts and samples the customers the rules match, while they are edited.","operationId":"previewEmailSegment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewEmailSegmentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSegmentPreview"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/segments/{segment_id}":{"put":{"tags":["Email"],"summary":"Replace a segment","operationId":"updateEmailSegment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"segment_id","in":"path","description":"Segment id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSegmentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSegment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such segment in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Email"],"summary":"Delete a segment","description":"Meta audiences built from it are removed from the store with it (the\ncopies on Meta stay). Campaigns already sent keep their recipients.","operationId":"deleteEmailSegment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"segment_id","in":"path","description":"Segment id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such segment in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/segments/{segment_id}/export.csv":{"get":{"tags":["Email"],"summary":"Export a segment as CSV","description":"Every member with e-mail, name, orders, spend (reais), last order, tags,\nconsent and e-mail status. Comma-separated, UTF-8.","operationId":"exportEmailSegment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"segment_id","in":"path","description":"Segment id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The CSV file","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such segment in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/segments/{segment_id}/members":{"get":{"tags":["Email"],"summary":"List a segment's members","description":"Every customer the segment matches now (with or without an e-mail), newest\ncustomers first.","operationId":"listEmailSegmentMembers","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"segment_id","in":"path","description":"Segment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailSegmentMember"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such segment in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/suppressions":{"get":{"tags":["Email Deliverability"],"summary":"List suppressed addresses","description":"Newest first.","operationId":"listEmailSuppressions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailSuppression"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Email Deliverability"],"summary":"Suppress an address","description":"The store stops e-mailing it (marketing and transactional sends through\nthe platform), and the matching customer's e-mail status becomes\n`suppressed`. Suppressing an address again updates its reason to `manual`.","operationId":"addEmailSuppression","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddEmailSuppressionRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSuppression"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: not an e-mail address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/suppressions/{suppression_id}":{"delete":{"tags":["Email Deliverability"],"summary":"Remove a suppression","description":"The address can be e-mailed again and the customer's e-mail status goes\nback to `ok`.","operationId":"deleteEmailSuppression","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"suppression_id","in":"path","description":"Suppression id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such suppression in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/templates":{"get":{"tags":["Email"],"summary":"List e-mail templates","description":"The store's marketing templates, most recently edited first.","operationId":"listEmailTemplates","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EmailTemplate"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Email"],"summary":"Create an e-mail template","description":"A `design` is compiled to `html` with the store's brand kit; without one,\n`html` is stored as sent.","operationId":"createEmailTemplate","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmailTemplateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/templates/ai":{"post":{"tags":["Email"],"summary":"Draft an e-mail with the assistant","description":"Writes (or revises) a block design from a prompt, using the store's brand\nguide and real products. Nothing is saved.","operationId":"draftEmailWithAssistant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftEmailRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraft"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`assistant_error`: the model failed or answered something unusable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`assistant_unavailable`: no model configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/templates/render":{"post":{"tags":["Email"],"summary":"Render an e-mail design","description":"Compiles a block design with the store's brand kit (or the one sent) and\nfills merge variables with sample values, for a live preview. Product\nblocks show current catalog data.","operationId":"renderEmailDesign","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderEmailDesignRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderedEmailPreview"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/templates/{template_id}":{"get":{"tags":["Email"],"summary":"Get an e-mail template","operationId":"getEmailTemplate","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"template_id","in":"path","description":"E-mail template id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such template in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Email"],"summary":"Delete an e-mail template","description":"Campaigns already created from it keep their copy of the content.","operationId":"deleteEmailTemplate","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"template_id","in":"path","description":"E-mail template id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such template in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Email"],"summary":"Update an e-mail template","description":"Changes the fields sent. A `design` recompiles `html` (with\n`preview_text`); an `html` without a `design` switches the template to raw\nHTML and drops its design.","operationId":"updateEmailTemplate","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"template_id","in":"path","description":"E-mail template id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailTemplateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such template in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/templates/{template_id}/test":{"post":{"tags":["Email"],"summary":"Send an e-mail template test","description":"Renders the saved template with stub merge values (customer \"Teste\nMarketing\") and sends it to one address. No recipient row is written.","operationId":"testEmailTemplate","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"template_id","in":"path","description":"E-mail template id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestEmailTemplateRequest"}}},"required":true},"responses":{"204":{"description":"Sent"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such template in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `to` is not an e-mail address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`email_send_failed`: the provider refused it; `error` says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/email/test":{"post":{"tags":["Transactional Email"],"summary":"Send a test e-mail","description":"Sends a short branded message through the store's configured identity (or\nthe platform fallback). A provider refusal (unverified domain, bad key)\ncomes back as `email_send_failed` with the provider's reason.","operationId":"sendTestEmail","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTestEmailRequest"}}},"required":true},"responses":{"204":{"description":"Sent"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `to` is not an e-mail address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`email_send_failed`: the provider refused it; `error` says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers":{"get":{"tags":["Integrations"],"summary":"List ERP providers","description":"The store's ERP connections, the default first. Secrets are masked.","operationId":"listErpProviders","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ErpProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Integrations"],"summary":"Connect an ERP","description":"Creates the store's connection to an ERP (for Tiny, `code` is\n`tiny_erp`; then authorize it with the OAuth calls). The answer masks\nthe secrets.","operationId":"createErpProvider","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpProviderCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`erp_provider_exists`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}":{"put":{"tags":["Integrations"],"summary":"Update an ERP provider","description":"Changes the fields sent. `config_json` is merged into the stored\nsettings; masked secrets sent back unchanged keep the stored values.","operationId":"updateErpProvider","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpProviderUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/health":{"get":{"tags":["Integrations"],"summary":"Check an ERP provider","description":"The stored connection and sync state (always available, even when Tiny is\ndown), plus a live call to Tiny's `/info` when a token is present. Also\ncreates the stock webhook secret on first read, so `status.webhook_url`\nis always ready to paste into Tiny.","operationId":"getErpProviderHealth","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpProviderHealth"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/sync-logs":{"get":{"tags":["Integrations"],"summary":"List ERP sync runs","description":"The provider's sync and import runs, newest first. Keyset-paged.","operationId":"listErpSyncLogs","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ErpSyncLog"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/sync-logs/{log_id}":{"get":{"tags":["Integrations"],"summary":"Get an ERP sync run","description":"Poll it to follow an import started with `importTinyProducts` (its\n`job_id`).","operationId":"getErpSyncLog","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"log_id","in":"path","description":"Sync log id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpSyncLog"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`sync_log_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/info":{"get":{"tags":["Integrations"],"summary":"Get the Tiny account","description":"Tiny's `/info` answer (the account behind the token), passed through.","operationId":"getTinyAccountInfo","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tiny's own payload","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `provider_token_missing`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`provider_error` (`details.provider_status`, `details.provider_body`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/link-report":{"get":{"tags":["Integrations"],"summary":"Get the Tiny link report","description":"Every variant of the store with whether a sync matched it to a Tiny\nproduct (by SKU, case-insensitive) and the stock held in Mobiari: which\nSKUs are linked, which are not, and where stock is 0 because a SKU never\nmatched.","operationId":"getTinyLinkReport","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TinyLinkReport"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/oauth/authorize-url":{"get":{"tags":["Integrations"],"summary":"Get Tiny's OAuth authorize URL","description":"Built from the provider's `oauth_client_id` and `oauth_redirect_uri`.","operationId":"getTinyAuthorizeUrl","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"state","in":"query","description":"Echoed back on the redirect, to find the store and provider again.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TinyAuthorizeUrl"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `oauth_not_configured` (client id or redirect URI missing)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/oauth/token":{"post":{"tags":["Integrations"],"summary":"Exchange Tiny's OAuth code","description":"Trades the `code` from Tiny's redirect for tokens, stores them (never\nreturned) and clears any needs-reauth state.","operationId":"exchangeTinyOauthCode","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TinyOauthTokenRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TinyOauthResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `oauth_not_configured`, `validation_failed` (empty code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`oauth_exchange_failed`: Tiny refused the code (`details.provider_response`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/orders":{"get":{"tags":["Integrations"],"summary":"List Tiny orders","description":"Tiny's `/pedidos` answer, passed through as Tiny paginates it.","operationId":"listTinyOrders","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"order_by","in":"query","description":"Tiny's `orderBy`.","required":false,"schema":{"type":"string"}},{"name":"situacao","in":"query","description":"Tiny's `situacao`.","required":false,"schema":{"type":"string"}},{"name":"data_inicial","in":"query","description":"Created on or after (products), or the order period start.","required":false,"schema":{"type":"string"}},{"name":"data_final","in":"query","description":"Order period end.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tiny's own payload","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `provider_token_missing`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/products":{"get":{"tags":["Integrations"],"summary":"List Tiny products","description":"Tiny's `/produtos` answer, passed through as Tiny paginates it (this is\nTiny's list, not a Mobiari `Page`).","operationId":"listTinyProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"order_by","in":"query","description":"Tiny's `orderBy`.","required":false,"schema":{"type":"string"}},{"name":"situacao","in":"query","description":"Tiny's `situacao`.","required":false,"schema":{"type":"string"}},{"name":"data_inicial","in":"query","description":"Created on or after (products), or the order period start.","required":false,"schema":{"type":"string"}},{"name":"data_final","in":"query","description":"Order period end.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tiny's own payload","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `provider_token_missing`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/products/import":{"post":{"tags":["Integrations"],"summary":"Import products from Tiny","description":"Starts a background import of Tiny's catalogue (products, variations,\nkits and their components, prices and stock) and answers at once with\nthe sync log that tracks it. One sync runs per provider at a time.","operationId":"importTinyProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpImportStarted"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`sync_already_running`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `provider_token_missing`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/products/import/stream":{"post":{"tags":["Integrations"],"summary":"Import products from Tiny, streaming progress","description":"The same import as `importTinyProducts`, answering with its progress as\nnewline-delimited JSON (`application/x-ndjson`), one event object per\nline, ending with `{\"type\": \"done\", ...}`. Read it as a stream. Do not\nsend an `Idempotency-Key`: the stream would be buffered to be replayed.","operationId":"streamTinyProductImport","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Progress events, one JSON object per line","content":{"application/x-ndjson":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`sync_already_running`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `provider_token_missing`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/erp-providers/{provider_id}/tiny/sync":{"post":{"tags":["Integrations"],"summary":"Sync stock from Tiny","description":"Pulls Tiny's stock into the store's location (matching variants by SKU)\nin the background and answers 202 at once; follow it with\n`getErpProviderHealth` (`status.last_sync_at`, `status.last_error`).\nWith `dry_run=true` it runs inline, writes nothing and answers 200 with\nwhat would change. The scheduled sync (leader-elected worker) is\nseparate and unaffected.","operationId":"syncTinyStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"ERP provider id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"query","description":"Location the ERP's stock is written to; defaults to the store's\nfirst active location (created when the store has none).","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"dry_run","in":"query","description":"Compute what the sync would change and answer with it, writing\nnothing.","required":false,"schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Dry run: what would change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpSyncPreview"}}}},"202":{"description":"Started in the background","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpSyncStarted"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`erp_provider_not_found` (or the location)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_erp_provider`, `provider_token_missing`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/events":{"get":{"tags":["Events"],"summary":"List store events","description":"The store's domain events (the outbox that feeds webhooks, workflows\nand team alerts), newest first, with their delivery status.","operationId":"listStoreEvents","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"query","description":"Only events with this name, e.g. `orders.paid`.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Where an event is in delivery.","enum":["dispatched","pending","failed"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_EventRow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/freight-providers":{"get":{"tags":["Freight"],"summary":"List freight providers","description":"The default first, then by name. Secrets are masked.","operationId":"listFreightProviders","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_FreightProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Freight"],"summary":"Connect a freight provider","description":"Secrets in the response are masked.","operationId":"createFreightProvider","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightProviderCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`freight_provider_exists`: same code and name already connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/freight-providers/{provider_id}":{"put":{"tags":["Freight"],"summary":"Update a freight provider","description":"Partial: omitted fields keep their value; `config_json` is merged into\nthe stored settings and masked secrets (`__stored__`) are kept.","operationId":"updateFreightProvider","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"Freight provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightProviderUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such provider in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/freight-providers/{provider_id}/cargo-types":{"get":{"tags":["Freight"],"summary":"List a provider's cargo types","description":"Asks Central do Frete for the cargo types it quotes, for the \"default\ncargo types\" setting. A small catalog from the carrier, returned whole\nas an array. Only `central_do_frete` providers have one.","operationId":"listFreightProviderCargoTypes","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"Freight provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FreightCargoType"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such provider in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unsupported_provider`: not Central do Frete; `provider_token_missing`: no API token saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`freight_provider_error`: the carrier did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/freight-providers/{provider_id}/health":{"get":{"tags":["Freight"],"summary":"Check a freight provider","description":"Reports whether the provider's required settings are all present (from\nthe module's registry spec). It does not call the carrier.","operationId":"checkFreightProviderHealth","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"Freight provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightProviderHealth"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such provider in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/freight/cancel-reasons":{"get":{"tags":["Shipments"],"summary":"List freight cancel reasons","description":"The carrier's reasons for cancelling a freight order; send one's `id`\nto `POST .../shipments/{shipment_id}/cancel`.","operationId":"listFreightCancelReasons","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_FreightCancelReason"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`freight_provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`freight_provider_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/freight/settings":{"get":{"tags":["Shipments"],"summary":"Get freight settings","description":"The origin CEP, default cargo types and sender address details of the\nstore's Central do Frete integration.","operationId":"getFreightSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`freight_provider_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/github/connect":{"get":{"tags":["Storefront"],"summary":"Start connecting GitHub","description":"Returns the GitHub App install URL for this store. Bearer auth cannot\nfollow a cross-site redirect, so the client navigates to the URL itself.","operationId":"getGithubInstallUrl","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GithubInstallUrl"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`github_app_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/github/export":{"get":{"tags":["Storefront"],"summary":"Export the active deployment","description":"Every file of the storefront's active deployment, base64-encoded, as\none manifest: the starting point for a new repository. A document, not\na paged list.","operationId":"exportActiveDeployment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExportFile"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`no_active_deployment`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/github/installation":{"get":{"tags":["Storefront"],"summary":"Get the GitHub connection","description":"Which GitHub account and repository the storefront deploys from.","operationId":"getGithubInstallation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallationStatus"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/github/link":{"post":{"tags":["Storefront"],"summary":"Link a repository","description":"Pushes to the repository (and its pull requests) now build and deploy\nthe storefront.","operationId":"linkGithubRepo","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkRepoRequest"}}},"required":true},"responses":{"204":{"description":"Repository linked"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Storefront"],"summary":"Unlink the repository","description":"Deployments stop following the repository; the installation stays.","operationId":"unlinkGithubRepo","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Repository unlinked"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/github/repos":{"get":{"tags":["Storefront"],"summary":"List GitHub repositories","description":"Repositories the store's GitHub App installation can access, to pick\none to deploy from.","operationId":"listGithubRepos","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_RepoSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"428":{"description":"`github_not_installed`: install the GitHub App first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`github_app_not_configured`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/inventory-locations":{"get":{"tags":["Inventory"],"summary":"List inventory locations","description":"By priority, then name. The first active one is the default location.","operationId":"listInventoryLocations","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_InventoryLocation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Inventory"],"summary":"Create an inventory location","description":"Emits the `inventory_location.created` webhook.","operationId":"createInventoryLocation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLocationCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLocation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/inventory-locations/{location_id}":{"put":{"tags":["Inventory"],"summary":"Update an inventory location","description":"Changes the fields sent. Emits the `inventory_location.updated` webhook.","operationId":"updateInventoryLocation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"path","description":"Inventory location id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLocationUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLocation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`location_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Inventory"],"summary":"Delete an inventory location","description":"Refused while the location holds stock rows, transfers or receipts\n(409 `location_in_use`): deactivate it instead. Emits the\n`inventory_location.deleted` webhook.","operationId":"deleteInventoryLocation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"path","description":"Inventory location id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`location_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`location_in_use`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/invites":{"get":{"tags":["Team"],"summary":"List pending invites","description":"Invites not yet accepted or cancelled, newest first.","operationId":"listInvites","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StoreInvite"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Team"],"summary":"Invite someone to the store","description":"Creates a pending invite, valid for a limited time, that grants\n`role_ids` to whoever accepts it with this e-mail. The roles may not\ngrant permissions the inviter does not hold. The acceptance link is\ne-mailed to the invitee; its token is never returned. Someone new to\nthe organization takes a seat of the plan.","operationId":"createInvite","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInviteRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreInvite"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`plan_limit_reached`: every seat of the plan is taken (`details` has `limit`, `max`, `used`, `plan`); `subscription_inactive`: the subscription is suspended or canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`missing_permission`, or `grant_exceeds_actor`: the roles grant permissions the inviter does not hold","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: no roles, an unknown role, or an invalid e-mail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/invites/{invite_id}":{"delete":{"tags":["Team"],"summary":"Cancel an invite","description":"The acceptance link stops working.","operationId":"cancelInvite","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"invite_id","in":"path","description":"Invite id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Invite cancelled"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No pending invite with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kb/articles":{"get":{"tags":["Knowledge Base"],"summary":"List knowledge base articles","description":"Most recently edited first.","operationId":"listKbArticles","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/KbArticleStatus"}},{"name":"search","in":"query","description":"Matches title and text.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_KbArticleSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Knowledge Base"],"summary":"Create a knowledge base article","description":"A published article is indexed in the background (`indexed_at` fills\nin when the bot can read it).","operationId":"createKbArticle","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKbArticleRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbArticle"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: a collection of another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kb/articles/{article_id}":{"get":{"tags":["Knowledge Base"],"summary":"Get a knowledge base article","operationId":"getKbArticle","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"article_id","in":"path","description":"Article id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbArticle"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such article in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Knowledge Base"],"summary":"Delete a knowledge base article","operationId":"deleteKbArticle","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"article_id","in":"path","description":"Article id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such article in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Knowledge Base"],"summary":"Update a knowledge base article","description":"Re-indexes it in the background when published.","operationId":"updateKbArticle","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"article_id","in":"path","description":"Article id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateKbArticleRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbArticle"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such article in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: a collection of another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kb/collections":{"get":{"tags":["Knowledge Base"],"summary":"List knowledge base collections","description":"Ordered by position, then name.","operationId":"listKbCollections","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_KbCollection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Knowledge Base"],"summary":"Create a knowledge base collection","operationId":"createKbCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbCollectionRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbCollection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: missing name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kb/collections/{collection_id}":{"delete":{"tags":["Knowledge Base"],"summary":"Delete a knowledge base collection","description":"Its articles stay, without a collection.","operationId":"deleteKbCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Knowledge Base"],"summary":"Update a knowledge base collection","operationId":"updateKbCollection","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"path","description":"Collection id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbCollectionRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbCollection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such collection in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: missing name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kb/reindex":{"post":{"tags":["Knowledge Base"],"summary":"Re-index the knowledge base","description":"Queues every published article for indexing again (after changing the\nembeddings configuration, for example).","operationId":"reindexKb","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbReindexResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kb/search":{"post":{"tags":["Knowledge Base"],"summary":"Search the knowledge base","description":"What the bot would read for a question: published articles only.","operationId":"searchKb","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbSearchRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbSearchResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kits":{"get":{"tags":["Manufacturing"],"summary":"List kits","description":"Variants with their own bill of materials, with how many can be built\nfrom what is available.","operationId":"listKits","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches SKU, name or product title.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Kit"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kits/{variant_id}/bom":{"get":{"tags":["Manufacturing"],"summary":"Get a kit's bill of materials","description":"The variant's own lines (a product's base lines are under\n`/products/{product_id}/base-bom`), with the stock of each part.","operationId":"listKitBom","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"The kit's variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_BomLine"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Manufacturing"],"summary":"Set a bill-of-materials line","description":"Adds a part to a kit, or changes its quantity. The part must be a variant\nof the same store and cannot be the kit itself or a kit built from this\none (bills of materials are one level deep). Marks the part as a\ncomponent and refreshes the kit's availability.","operationId":"setKitBomLine","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"The kit's variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BomLineRequest"}}},"required":true},"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`, `component_not_in_store`, `bom_cycle`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/kits/{variant_id}/bom/{component_variant_id}":{"delete":{"tags":["Manufacturing"],"summary":"Remove a bill-of-materials line","operationId":"deleteKitBomLine","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"The kit's variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"component_variant_id","in":"path","description":"The part's variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`, `bom_line_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/locations":{"get":{"tags":["Locations"],"summary":"List store locations","description":"By `position`, then name.","operationId":"listStoreLocations","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StoreLocation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Locations"],"summary":"Create a store location","operationId":"createStoreLocation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocationRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`location_slug_taken`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: no name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/locations/{location_id}":{"get":{"tags":["Locations"],"summary":"Get a store location","operationId":"getStoreLocation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"path","description":"Location id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such location in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Locations"],"summary":"Update a store location","description":"A partial update: omitted fields keep their value; send `null` to clear\na nullable one (description, contact, address, coordinates, pickup\ninstructions). `name` is required.","operationId":"updateStoreLocation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"path","description":"Location id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocationUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreLocation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such location in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`location_slug_taken`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: no name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Locations"],"summary":"Delete a store location","operationId":"deleteStoreLocation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"path","description":"Location id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such location in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`location_in_use`: carts or orders still point at it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/catalog/sync":{"post":{"tags":["Analytics"],"summary":"Sync the Meta catalog","description":"Pushes every active variant of the store to its Meta catalog now (price\nand availability edits are also pushed as they happen). Answers Meta's\nresponse so catalog validation errors can be shown as they are.","operationId":"syncMetaCatalog","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaCatalogSyncResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`meta_catalog_not_configured`: set the catalog id and access token first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`meta_catalog_error`: Meta rejected the push or could not be reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/config":{"get":{"tags":["Analytics"],"summary":"Get the tracking configuration","operationId":"getMarketingConfig","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketingConfig"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Analytics"],"summary":"Update the tracking configuration","description":"Partial update: only fields sent are written, `\"\"` clears one. Answers\nthe configuration as `getMarketingConfig` does, secrets masked.","operationId":"updateMarketingConfig","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMarketingConfigRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketingConfig"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/conversions":{"get":{"tags":["Analytics"],"summary":"List conversion deliveries","description":"Every order of the store, newest first, with the delivery state of its\nMeta Conversions API and Google Ads uploads. Errors are trimmed to\nMeta's human message.","operationId":"listConversionDeliveries","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ConversionDelivery"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/conversions/{order_id}/resend":{"post":{"tags":["Analytics"],"summary":"Resend an order's conversions","description":"Queues the Meta Conversions API and Google Ads uploads again for a\ncaptured order. Uploads already `sent` are not repeated, so this is safe\nto call more than once.","operationId":"resendOrderConversions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"Queued"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`order_not_captured`: only orders with a captured payment send conversions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/insights":{"get":{"tags":["Analytics"],"summary":"Get the attribution report","description":"Paid and fulfilled orders created in the window, grouped by the\nsource / medium / campaign of their first or last touch, with the\nstore's totals as the denominator.","operationId":"getMarketingInsights","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the window (inclusive). Defaults to 30 days ago.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the window (inclusive). Defaults to now.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"touch","in":"query","description":"Defaults to `last_touch`.","required":false,"schema":{"type":"string","description":"Which touch of the visitor's journey an order is credited to.","enum":["first_touch","last_touch"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketingInsights"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/recent-events":{"get":{"tags":["Analytics"],"summary":"List recent events","description":"The store's raw tracking events, newest first.","operationId":"listRecentTrackingEvents","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_TrackedEvent"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/stats":{"get":{"tags":["Analytics"],"summary":"Get traffic totals","description":"Visitors, sessions, pageviews, events and attributed conversions in the\nwindow.","operationId":"getMarketingStats","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the window (inclusive). Defaults to 30 days ago.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the window (inclusive). Defaults to now.","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketingStats"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/top-events":{"get":{"tags":["Analytics"],"summary":"List the top events","description":"Tracked events other than pageviews (`identify` included), most\nfrequent first.","operationId":"listTopEvents","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the window (inclusive). Defaults to 30 days ago.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the window (inclusive). Defaults to now.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_TopEvent"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/top-pages":{"get":{"tags":["Analytics"],"summary":"List the most viewed pages","description":"Storefront pages by pageviews in the window, most viewed first.","operationId":"listTopPages","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the window (inclusive). Defaults to 30 days ago.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the window (inclusive). Defaults to now.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_TopPage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/top-referrers":{"get":{"tags":["Analytics"],"summary":"List the top referrers","description":"Referring hosts by pageviews in the window, busiest first.","operationId":"listTopReferrers","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the window (inclusive). Defaults to 30 days ago.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the window (inclusive). Defaults to now.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_TopReferrer"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/visitors":{"get":{"tags":["Analytics"],"summary":"List visitors","description":"Visitors with activity in the window, most recently seen first.","operationId":"listVisitors","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the window (inclusive). Defaults to 30 days ago.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the window (inclusive). Defaults to now.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"search","in":"query","description":"Matches the identified customer's e-mail or name, or the start of\nthe visitor id. `q` is accepted too.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_VisitorSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/marketing/visitors/{visitor_id}":{"get":{"tags":["Analytics"],"summary":"Get a visitor","operationId":"getVisitor","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"visitor_id","in":"path","description":"Visitor id (the tracker's cookie)","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitorDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`visitor_not_found`: no visit, event or attributed order of this visitor in the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/me/platform-notifications":{"get":{"tags":["Notifications"],"summary":"List my alert channels","description":"My WhatsApp and e-mail destinations for this store's admin events, sent\nfrom Mobiari's own accounts. At most one per channel type, so a plain\narray.","operationId":"listMyAlertChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlatformNotificationPreference"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Notifications"],"summary":"Replace my alert channels","description":"Replaces my WhatsApp and e-mail alert channels for this store with the\nones sent. Push preferences are not touched.","operationId":"updateMyAlertChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertPlatformPrefsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlatformNotificationPreference"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty destination or a channel type sent twice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/me/push-preferences":{"get":{"tags":["Push Notifications"],"summary":"Get my push preferences for a store","description":"Which of this store's alerts push to my devices. Until saved, the\ndefaults apply (`is_default`).","operationId":"getPushPreferences","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushPreferences"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`not_store_member`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Push Notifications"],"summary":"Set my push preferences for a store","description":"Replaces the set of alerts that push to my devices for this store.\nApplies to every device I registered.","operationId":"updatePushPreferences","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePushPreferencesRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushPreferences"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`not_store_member`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/members":{"get":{"tags":["Team"],"summary":"List store members","description":"The owner first, then everyone holding a role, by name.","operationId":"listStoreMembers","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StoreMember"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/members/{user_id}":{"delete":{"tags":["Team"],"summary":"Remove a member","description":"Takes away every role the user holds in the store (and any legacy\ndirect grant). The user keeps their account and other stores. The\nstore owner cannot be removed; transfer ownership first.","operationId":"removeStoreMember","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"path","description":"The member's user id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Member removed"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not a member of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`cannot_remove_owner`: the user owns the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-channels":{"get":{"tags":["Notifications"],"summary":"List notification channels","description":"The store's customer-facing channels (abandoned-cart recovery, review\nrequests), oldest first. Secrets in `config_json` read as `__stored__`.","operationId":"listNotificationChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_NotificationChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Notifications"],"summary":"Create a notification channel","description":"Adds a channel the store's automations can message customers through.","operationId":"createNotificationChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNotificationChannelRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty or long name, unknown `channel_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-channels/{channel_id}":{"delete":{"tags":["Notifications"],"summary":"Delete a notification channel","description":"Its past sends stay in the log.","operationId":"deleteNotificationChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Notification channel id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Notifications"],"summary":"Update a notification channel","description":"Changes the fields sent. A `config_json` replaces the stored config;\nsecrets sent back as `__stored__` keep their stored value.","operationId":"updateNotificationChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Notification channel id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNotificationChannelRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-channels/{channel_id}/test":{"post":{"tags":["Notifications"],"summary":"Send a test through a channel","description":"Sends the test message (in the channel's language) to the channel's\n`test_recipient` (e-mail, WhatsApp) or its chat/URL (Telegram, webhook),\nand records it in the log.","operationId":"testNotificationChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Notification channel id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Sent"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`notification_send_failed`: the provider refused it or the channel is missing settings; `error` says why","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-inbox":{"get":{"tags":["Notifications"],"summary":"List my notification inbox","description":"The store's notification log with my read state, newest first.\nKeyset-paged: walk it with `next_cursor`.","operationId":"listNotificationInbox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"unread","in":"query","description":"`true`: only unread; `false`: only read. Omit for both.","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_InboxNotification"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-inbox/mark-all-read":{"post":{"tags":["Notifications"],"summary":"Mark all notifications read","description":"Every inbox entry of this store, for me only.","operationId":"markAllNotificationsRead","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"All marked read"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-inbox/unread-count":{"get":{"tags":["Notifications"],"summary":"Count my unread notifications","description":"For the bell badge. Cheap enough to poll.","operationId":"getNotificationUnreadCount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationUnreadCount"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-inbox/{log_id}/read":{"post":{"tags":["Notifications"],"summary":"Mark a notification read","description":"For me only; other members keep their own read state. Idempotent.","operationId":"markNotificationRead","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"log_id","in":"path","description":"Inbox entry (notification log) id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Marked read"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such entry in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/notification-logs":{"get":{"tags":["Notifications"],"summary":"List notification logs","description":"Everything the store sent or tried to send, newest first. Keyset-paged:\nwalk it with `next_cursor`.","operationId":"listNotificationLogs","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_NotificationLog"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/onboarding":{"get":{"tags":["Stores"],"summary":"Get the setup checklist","description":"What is left to set up in the store, step by step, read from its data:\nproducts, payments, freight, brand, WhatsApp, team, custom domain and\nthe first order.","operationId":"getOnboardingChecklist","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingChecklist"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/option-groups/{option_group_id}":{"put":{"tags":["Products"],"summary":"Update an option group","description":"Emits the `option_group.updated` webhook.","operationId":"updateOptionGroup","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"option_group_id","in":"path","description":"Option group id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionGroupUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionGroup"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`option_group_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Products"],"summary":"Delete an option group","description":"Deletes its values too. Refused while a variant carries one of them.\nEmits the `option_group.deleted` webhook.","operationId":"deleteOptionGroup","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"option_group_id","in":"path","description":"Option group id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`option_group_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`option_group_in_use`: a variant carries one of its values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/option-groups/{option_group_id}/values":{"get":{"tags":["Products"],"summary":"List an option group's values","operationId":"listOptionValues","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"option_group_id","in":"path","description":"Option group id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_OptionValue"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`option_group_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Products"],"summary":"Create an option value","operationId":"createOptionValue","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"option_group_id","in":"path","description":"Option group id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValueCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValue"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`option_group_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`, or `invalid_color` for a custom color without a valid `color_hex`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/option-values/{option_value_id}":{"put":{"tags":["Products"],"summary":"Update an option value","description":"Emits the `option_value.updated` webhook.","operationId":"updateOptionValue","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"option_value_id","in":"path","description":"Option value id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValueUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionValue"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`option_value_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`, or `invalid_color`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Products"],"summary":"Delete an option value","description":"Refused while a variant carries it. Emits the `option_value.deleted`\nwebhook.","operationId":"deleteOptionValue","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"option_value_id","in":"path","description":"Option value id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`option_value_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`option_value_in_use`: a variant carries this value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders":{"get":{"tags":["Orders"],"summary":"List orders","description":"Newest first (`created_at`, then `id`). Paged by keyset: follow\n`next_cursor` for an infinite list; orders placed meanwhile never shift\nor repeat rows, whatever the filters. Page-number tables may pass\n`offset` instead (with `include_total=true` for the page count).\n\nEach row carries what a list or card needs (status, customer, totals,\nfirst item, unit counts, per-line shipped counts); fetch the order for\nthe rest.","operationId":"listOrders","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"An order status, or `processing` / `shipped` (the fulfillment tabs).","required":false,"schema":{"$ref":"#/components/schemas/OrderListStatus"}},{"name":"customer_id","in":"query","description":"Only this customer's orders.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches the order number, the customer's name or e-mail, and the\nname or e-mail typed at checkout.","required":false,"schema":{"type":"string"}},{"name":"include_test","in":"query","description":"Include orders flagged as test data. Defaults to false.","required":false,"schema":{"type":"boolean"}},{"name":"created_after","in":"query","description":"Only orders created at or after this instant.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","description":"Only orders created before this instant.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_OrderSummary"}}}},"400":{"description":"`invalid_cursor`, `invalid_limit` or `invalid_offset`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Orders"],"summary":"Create an order","description":"Prices every line from the catalog, applies an active discount code,\nand reserves stock (or queues production for made-to-order lines) line\nby line. The order starts `pending`. Emits the `orders.created` webhook.\n\nFor a sale taken at the counter, with payment, use\n`POST /stores/{store_id}/orders/manual`.","operationId":"createOrder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`: a variant is not in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`insufficient_stock` or `insufficient_component_stock` (with `details.max_shippable`, `details.limiting_sku`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: no items, a quantity below 1, or an unknown customer / sales channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/manual":{"post":{"tags":["Orders"],"summary":"Record a counter sale","description":"Creates a numbered order with its lines, reserves stock (queuing\nproduction for made-to-order lines) and records the payment, in one\ntransaction.\n\nEvery method but `pix_qr` records an in-person payment: the order is\n`paid` / `captured` at once and `orders.paid` fires. `pix_qr` creates a\nreal PIX charge through the store's gateway and returns its QR code; the\norder stays `pending` until the gateway confirms, and if the charge\ncannot be created the order is cancelled and its stock released.\n\nEmits the `orders.created` webhook.","operationId":"createManualSale","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualSaleRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualSaleResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`: a variant is not in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`insufficient_stock` or `insufficient_component_stock` (with `details.max_shippable`, `details.limiting_sku`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed` (no items, bad quantity, unknown customer), `invalid_manual_discount`, `invalid_shipping`, `invalid_postal_code`, or `pix_intent_failed` (no gateway configured or the gateway refused)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}":{"get":{"tags":["Orders"],"summary":"Get an order","description":"Everything an order screen shows in one call: lines with images and\nproduction state, customer and delivery address, totals in cents,\npayment state, shipments with contents and tracking, refunds, and the\nstatus changes allowed from here (`allowed_status_transitions`).\n\nThe payment attempts themselves (PIX codes, gateway events) are at\n`GET .../orders/{order_id}/payments`.","operationId":"getOrder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/adjustments":{"get":{"tags":["Orders"],"summary":"List an order's item adjustments","description":"Oldest first.","operationId":"listOrderItemAdjustments","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_item_id","in":"query","description":"Only this line's adjustments.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_OrderItemAdjustment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Orders"],"summary":"Add an item adjustment","description":"Records an adjustment against one line of the order. Totals are not\nrecomputed. Emits the `order_item_adjustment.created` webhook.","operationId":"createOrderItemAdjustment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderItemAdjustmentRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItemAdjustment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: the line is not on this order, or a field is out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/nfe":{"post":{"tags":["Shipments"],"summary":"Attach a nota fiscal","description":"One NFe per order, however many boxes it ships in. The XML is parsed\nfor the access key, number and total; a Central do Frete order cannot\nbe generated without it.","operationId":"attachOrderNfe","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachNfeRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderNfe"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed` (neither XML nor DANFE link) or `nfe_key_not_found` (no access key in the XML)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/payments":{"get":{"tags":["Payments"],"summary":"List an order's payments","description":"Every payment attempt on the order (newest first) with its status, the\ngateway events that concern them (at most 100, newest first) and the\nrefunds issued. Provider snapshots are sanitized; card data and secrets\nare never returned.\n\nPoll this while a PIX charge is pending: an intent turning `approved`\nmeans the order is paid.","operationId":"listOrderPayments","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPayments"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/refund":{"post":{"tags":["Payments"],"summary":"Refund an order","description":"Returns money through the gateway that took it (Mercado Pago), from the\norder's latest approved payment. Omit `amount_cents` to refund what is\nleft on it; pass it for a partial refund. Local state changes only after\nthe gateway accepts: the refund is recorded, and once the payment is fully\nrefunded the order becomes `refunded` (stock released, open production\ncancelled, `orders.updated` webhook and `orders.refunded` event);\notherwise its `payment_status` becomes `partially_refunded`.\n\n**Send an `Idempotency-Key` header.** Every call that passes the checks\ncreates a new refund at the gateway, so a blind retry of a partial refund\nreturns money twice. With the header, a retry replays the first response\nfor 24 hours, and the key is also forwarded to the gateway. A retry\nwithout it is still bounded by the refundable amount: once the payment is\nfully refunded, further calls fail with `already_refunded`.\n\nPayments taken outside a gateway (cash, card machine, manual PIX) cannot\nbe refunded here; record them with `PATCH .../status` to `refunded`.","operationId":"refundOrder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Strongly recommended: a unique key per refund the user intends (e.g. a UUID).","required":false,"schema":{"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminRefundRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_refundable_payment` (no approved payment), `already_refunded` (nothing left to refund) or `idempotency_request_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`refund_exceeds_refundable` (`details.refundable_cents` says the most you can refund), `validation_failed` (amount below 1), `refund_not_supported` (the payment was not taken by a gateway that refunds through the API), `payment_provider_not_configured` or `missing_provider_reference`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`provider_error`: the gateway refused or failed; nothing was recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments":{"get":{"tags":["Shipments"],"summary":"List an order's shipments","description":"Oldest first, each with its contents and tracking. The order itself\n(`GET .../orders/{order_id}`) carries the same list.","operationId":"listOrderShipments","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Shipments"],"summary":"Create a shipment","description":"Adds a box to the order. Without `items` it takes every unit not yet\nclaimed by another (non-cancelled) shipment. The order's\n`fulfillment_status` (and `fulfilled` status once everything is\ndelivered) follows its shipments.","operationId":"createShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShipmentRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`item_not_available` (the line is not on this order or nothing of it is left) or `quantity_exceeds_remaining`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}":{"delete":{"tags":["Shipments"],"summary":"Delete a shipment","description":"Removes the box and frees its units to ship again. Nothing is cancelled\nat the carrier; use `POST .../cancel` for that.","operationId":"deleteShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Shipments"],"summary":"Update a shipment","description":"For shipments managed by hand (own delivery, other carriers, pickup):\nstatus, carrier, tracking, cost, notes, and the shipped / delivered\nstamps. Central do Frete shipments move through quote, generate, sync\nand cancel instead. The order's fulfillment follows.","operationId":"updateShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateShipmentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}/cancel":{"post":{"tags":["Shipments"],"summary":"Cancel a shipment","description":"Cancels the carrier order first when there is one, then marks the\nshipment `cancelled`; its units are free to ship again.","operationId":"cancelShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelShipmentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`freight_provider_not_configured` or `freight_invalid_input` (422), `freight_not_found` (404), `freight_provider_error` (502, the carrier refused or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}/confirm-collect":{"post":{"tags":["Shipments"],"summary":"Confirm the carrier collected","description":"Tells the carrier the goods were collected and moves the shipment to\n`collected`.","operationId":"confirmShipmentCollect","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_freight_order`: the shipment has no carrier order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`freight_provider_not_configured` or `freight_invalid_input` (422), `freight_not_found` (404), `freight_provider_error` (502, the carrier refused or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}/generate":{"post":{"tags":["Shipments"],"summary":"Create the carrier order","description":"Creates the freight order at Central do Frete from a quote and moves the\nshipment to `ordered`. The order's NFe XML must be attached first\n(`POST .../orders/{order_id}/nfe`).","operationId":"generateShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateShipmentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`nfe_required`: attach the NFe XML first; or a freight error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`freight_provider_not_configured` or `freight_invalid_input` (422), `freight_not_found` (404), `freight_provider_error` (502, the carrier refused or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}/items":{"put":{"tags":["Shipments"],"summary":"Set a shipment's contents","description":"Replaces what is in the box. Each line can take at most what no other\n(non-cancelled) shipment has claimed; see `GET .../unshipped-items`.","operationId":"setShipmentItems","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetShipmentItemsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`item_not_available` (the line is not on this order or nothing of it is left) or `quantity_exceeds_remaining`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}/quote":{"post":{"tags":["Shipments"],"summary":"Quote a shipment","description":"Asks the store's carrier integration (Central do Frete) for options to\nthe destination. Nothing is saved; pick an option and call `generate`.","operationId":"quoteShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteShipmentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentQuote"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed` (no invoice amount), or a freight error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`freight_provider_not_configured` or `freight_invalid_input` (422), `freight_not_found` (404), `freight_provider_error` (502, the carrier refused or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}/sync":{"post":{"tags":["Shipments"],"summary":"Sync a shipment with the carrier","description":"Pulls the carrier's order detail now (a background job also polls):\nstatus, tracking events, carrier, cost and, when still empty, the\norder's NFe data.","operationId":"syncShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`no_freight_order`: the shipment has no carrier order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"`freight_provider_not_configured` or `freight_invalid_input` (422), `freight_not_found` (404), `freight_provider_error` (502, the carrier refused or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/shipments/{shipment_id}/unlink":{"post":{"tags":["Shipments"],"summary":"Unlink a shipment from its carrier order","description":"Clears the carrier linkage (order code, quotation, price, tracking) and\nresets the shipment to `draft`. Nothing is cancelled at the carrier; it\nis for a code linked by mistake. To cancel the freight order use\n`POST .../cancel`.","operationId":"unlinkShipment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"shipment_id","in":"path","description":"Shipment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order or shipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/status":{"patch":{"tags":["Orders"],"summary":"Change an order's status","description":"Moves the order by hand. Allowed moves (also in the order's\n`allowed_status_transitions`):\n\n| From | To |\n| --- | --- |\n| `draft` | `pending`, `paid`, `cancelled` |\n| `pending` | `paid`, `fulfilled`, `cancelled` |\n| `paid` | `fulfilled`, `cancelled`, `refunded` |\n| `fulfilled` | `cancelled`, `refunded` |\n| `cancelled`, `refunded` | nothing (terminal) |\n\nSetting the current status again is a no-op that returns the order, so\na retried call is safe. Any other move answers 409\n`invalid_status_transition` with `details.from`, `details.to` and\n`details.allowed`.\n\nSide effects: `cancelled` and `refunded` release reserved stock and\ncancel open production; `fulfilled` consumes component reservations and\nschedules the review request. `refunded` here only records that money\nwent back outside the platform; to refund through the gateway use\n`POST .../refund`. `paid` does not change `payment_status`. Shipping is\nnot a status: it follows the shipments. Emits the `orders.updated`\nwebhook and the matching `orders.paid` / `orders.fulfilled` /\n`orders.cancelled` / `orders.refunded` event.\n\nNeeds `orders.cancel` to cancel, `orders.refund` to mark refunded,\n`orders.manage_payments` to mark paid, `orders.fulfill` to fulfil, and\n`orders.edit` otherwise.","operationId":"updateOrderStatus","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrderStatusRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`invalid_status_transition` (see the table), or `inventory_conflict` when reservations could not be released or consumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/test":{"patch":{"tags":["Orders"],"summary":"Flag an order as test data","description":"Test orders are hidden from the order list (unless `include_test=true`)\nand from reports. Payments, refunds and stock are not touched.","operationId":"setOrderTestFlag","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetOrderTestRequest"}}},"required":true},"responses":{"204":{"description":"Flag set"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/orders/{order_id}/unshipped-items":{"get":{"tags":["Shipments"],"summary":"List an order's unshipped items","description":"Every line of the order, in order, with the units no (non-cancelled)\nshipment has claimed yet. Feeds a picker for a shipment's contents.","operationId":"listUnshippedItems","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"path","description":"Order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_UnshippedItem"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such order in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/pages":{"get":{"tags":["Storefront"],"summary":"List pages","description":"The store's content pages, newest first.","operationId":"listStorefrontPages","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"published","in":"query","description":"Only published (`true`) or only draft (`false`) pages.","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StorefrontPage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Storefront"],"summary":"Create a page","operationId":"createStorefrontPage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStorefrontPageRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`page_slug_taken`: another page of the store has this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty or too long title, slug or template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/pages/{page_id}":{"get":{"tags":["Storefront"],"summary":"Get a page","operationId":"getStorefrontPage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","description":"Page id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such page in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Storefront"],"summary":"Update a page","description":"Changes the fields sent; absent or null fields keep their value, so\n`content` and `template` cannot be cleared through this call (send an\nempty string instead).","operationId":"updateStorefrontPage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","description":"Page id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStorefrontPageRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such page in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`page_slug_taken`: another page of the store has this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty or too long title, slug or template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Storefront"],"summary":"Delete a page","operationId":"deleteStorefrontPage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","description":"Page id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such page in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/payment-providers":{"get":{"tags":["Payments"],"summary":"List payment providers","description":"The store's configured gateways, the default first. Secret settings\n(access tokens, webhook secrets) come back as a mask; send the mask back\nunchanged on update to keep the stored value.","operationId":"listPaymentProviders","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_PaymentProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Payments"],"summary":"Connect a payment provider","description":"Stores a gateway's settings for the store. `is_default: true` makes it\nthe default and clears the flag on the others.","operationId":"createPaymentProvider","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentProviderRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`payment_provider_exists`: the store already has this gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/payment-providers/catalog":{"get":{"tags":["Payments"],"summary":"List the payment gateway catalog","description":"Every gateway the platform supports, with the payment methods it offers\nand the fields its connect form needs. A small fixed list, not paged.","operationId":"listPaymentProviderCatalog","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaymentProviderMeta"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/payment-providers/{provider_id}":{"put":{"tags":["Payments"],"summary":"Update a payment provider","description":"Omitted fields are kept. `config_json` is merged into the stored\nsettings; a secret sent back as the mask keeps its stored value.","operationId":"updatePaymentProvider","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"Payment provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentProviderRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProvider"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such provider in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/payment-providers/{provider_id}/health":{"get":{"tags":["Payments"],"summary":"Check a payment provider","description":"Reports whether the provider's required settings are all present (from\nthe gateway's registry spec). It does not call the gateway.","operationId":"checkPaymentProviderHealth","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider_id","in":"path","description":"Payment provider id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProviderHealth"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such provider in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/product-categories":{"post":{"tags":["Categories"],"summary":"Add a product to a category","description":"Idempotent.","operationId":"addProductToCategory","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCategoryRequest"}}},"required":true},"responses":{"204":{"description":"Added"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `category_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Categories"],"summary":"Remove a product from a category","operationId":"removeProductFromCategory","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCategoryRequest"}}},"required":true},"responses":{"204":{"description":"Removed"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `category_not_found`, or `not_found` when the product is not in the category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/product-feeds":{"get":{"tags":["Product Feeds"],"summary":"List product feeds","operationId":"listProductFeeds","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ProductFeed"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Product Feeds"],"summary":"Create a product feed","description":"The feed gets its public URL (`endpoint_url`). A `generated` feed has\nno content until the first `POST .../generate`.","operationId":"createProductFeed","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeed"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/product-feeds/{feed_id}":{"get":{"tags":["Product Feeds"],"summary":"Get a product feed","operationId":"getProductFeed","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeed"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Product Feeds"],"summary":"Update a product feed","operationId":"updateProductFeed","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeed"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Product Feeds"],"summary":"Delete a product feed","description":"Deletes its overrides too; the public URL stops answering. Emits the\n`product_feed.deleted` webhook.","operationId":"deleteProductFeed","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/product-feeds/{feed_id}/generate":{"post":{"tags":["Product Feeds"],"summary":"Generate a product feed","description":"Builds the feed from the store's active products now, stores it as the\nfeed's content (served at `endpoint_url`) and returns it: XML for\nGoogle, CSV for Meta and OMNIFEED, JSON for custom feeds.","operationId":"generateProductFeed","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"The generated content","content":{"application/json":{"schema":{"type":"string"}},"application/xml":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/product-feeds/{feed_id}/overrides":{"get":{"tags":["Product Feeds"],"summary":"List a feed's overrides","operationId":"listProductFeedOverrides","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ProductFeedOverride"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Product Feeds"],"summary":"Create a feed override","operationId":"createProductFeedOverride","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedOverrideCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedOverride"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`, `product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/product-feeds/{feed_id}/overrides/{override_id}":{"put":{"tags":["Product Feeds"],"summary":"Update a feed override","operationId":"updateProductFeedOverride","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"override_id","in":"path","description":"Override id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedOverrideUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductFeedOverride"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`, `override_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Product Feeds"],"summary":"Delete a feed override","operationId":"deleteProductFeedOverride","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feed_id","in":"path","description":"Feed id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"override_id","in":"path","description":"Override id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`feed_not_found`, `override_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products":{"get":{"tags":["Products"],"summary":"List products","description":"Each row carries its primary image, price range, stock totals, variant\ncount and active variants, so a list screen needs no further requests.\nKit components that are not themselves active products are left out.","operationId":"listProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only products in this status. Without it, drafts are hidden unless\n`include_drafts=true`.","required":false,"schema":{"$ref":"#/components/schemas/ProductStatus"}},{"name":"include_drafts","in":"query","description":"Include drafts when no `status` is given.","required":false,"schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Matches part of the title, the SKU prefix, a variant's SKU or\nbarcode, or the product's GTIN/EAN/UPC, case-insensitively.","required":false,"schema":{"type":"string"}},{"name":"category_id","in":"query","description":"Only products in this category.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"query","description":"Only products in this collection.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"How to order the product list.","enum":["priority","updated_at","title"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ProductListItem"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Products"],"summary":"Create a product","description":"The slug is derived from the title and made unique within the store. A\n`single` product with `default_price_cents` also gets its one variant\n(SKU `{sku_prefix or product id}-DEFAULT`). New products are drafts\nunless `status` says otherwise. Emits the `products.created` webhook.","operationId":"createProduct","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`sku_taken`: the default variant's SKU is already used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/dedupe-drafts":{"post":{"tags":["Products"],"summary":"Remove duplicate drafts","description":"For each group of drafts sharing a title (case-insensitive), keeps the\nmost recently updated one and deletes the rest. Drafts that orders\nreference are kept. `dry_run=true` only counts.","operationId":"dedupeDraftProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"dry_run","in":"query","description":"Only count what would happen.","required":false,"schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DedupeDraftsResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/purge-archived":{"post":{"tags":["Products"],"summary":"Delete every archived product","description":"Products that orders reference are kept and listed in\n`skipped_due_to_orders`. `dry_run=true` only counts.","operationId":"purgeArchivedProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"dry_run","in":"query","description":"Only count what would happen.","required":false,"schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/purge-drafts":{"post":{"tags":["Products"],"summary":"Delete every draft product","description":"Products that orders reference are kept and listed in\n`skipped_due_to_orders`. `dry_run=true` only counts.","operationId":"purgeDraftProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"dry_run","in":"query","description":"Only count what would happen.","required":false,"schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}":{"get":{"tags":["Products"],"summary":"Get a product","description":"The product with its variants (options, stock per location), option\ngroups and gallery. `availability` is resolved from the variants' stock.","operationId":"getProduct","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Products"],"summary":"Update a product","description":"Partial: omitted fields keep their value. Send `{\"status\": \"archived\"}`\nto archive. Prices live on the variants (`PUT /variants/{variant_id}`).\nThe slug is not changed here; use `PATCH .../slug`. Emits the\n`products.updated` webhook and purges the product's storefront cache.","operationId":"updateProduct","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Products"],"summary":"Delete a product","description":"Deletes the product with its variants, options, stock rows, gallery and\ncategory/collection memberships. Refused while any order references it;\narchive it instead. Emits the `products.deleted` webhook.","operationId":"deleteProduct","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`product_has_orders`: orders reference this product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/base-bom":{"get":{"tags":["Manufacturing"],"summary":"Get a product's base bill of materials","description":"Lines shared by every variant of the product. A variant's own line for\nthe same part wins over the base line.","operationId":"listProductBaseBom","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_BomLine"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Manufacturing"],"summary":"Set a base bill-of-materials line","description":"Adds a part every variant of the product needs, or changes its quantity.\nThe part cannot be one of the product's own variants.","operationId":"setProductBaseBomLine","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BomLineRequest"}}},"required":true},"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`, `component_not_in_store`, `bom_cycle`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/base-bom/{component_variant_id}":{"delete":{"tags":["Manufacturing"],"summary":"Remove a base bill-of-materials line","operationId":"deleteProductBaseBomLine","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"component_variant_id","in":"path","description":"The part's variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `bom_line_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/categories":{"get":{"tags":["Categories"],"summary":"List a product's categories","operationId":"listProductCategories","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Category"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/collections":{"get":{"tags":["Collections"],"summary":"List a product's collections","operationId":"listProductCollections","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Collection"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/images":{"get":{"tags":["Products"],"summary":"List a product's media","description":"The active gallery: images (with their resized renditions in `variants`)\nand videos (`media_type = video`, `cdn_url` is the playable URL).\nProduct-wide entries first, then variant-specific ones, each by position.","operationId":"listProductImages","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ProductImageWithVariants"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Products"],"summary":"Upload a product image","description":"`multipart/form-data` with the file in `image` (JPEG, PNG or WebP, up\nto 10 MB). The image is stored with resized JPEG and WebP renditions.\nEmits the `product.image.created` webhook.","operationId":"uploadProductImage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ProductImageUploadForm"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageUploadResponse"}}}},"400":{"description":"`bad_request`: malformed multipart body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_image`: not a supported image or too large; `validation_failed`: bad `image_kind` or no `image` part","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/images/associate":{"post":{"tags":["Products"],"summary":"Add a library file to a product's gallery","description":"Copies an image from the tenant's file library into the product's\ngallery, with resized renditions.","operationId":"associateFileWithProduct","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssociateFileRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageUploadResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `variant_not_found`, or `file_not_found` (not in the store's tenant)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`file_not_image`: the file is not an image; `validation_failed`: bad `image_kind`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/images/{image_id}":{"delete":{"tags":["Products"],"summary":"Delete a product image","description":"Removes the gallery entry and its stored files. Emits the\n`product.image.deleted` webhook.","operationId":"deleteProductImage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"image_id","in":"path","description":"Image id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `image_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Products"],"summary":"Update a product image","description":"Alt text, position, primary flag, visibility, the owning variant, the\nimage kind, a video's poster, and (with `extra_variant_ids`) the other\nvariants the image is shared with. Emits the `product.image.updated`\nwebhook.","operationId":"updateProductImage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"image_id","in":"path","description":"Image id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductImageRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductImage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `image_not_found`, or `variant_not_found` (a variant id not on this product)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: bad `image_kind`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/option-groups":{"get":{"tags":["Products"],"summary":"List a product's option groups","description":"In display order, each with its values.","operationId":"listOptionGroups","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_OptionGroupWithValues"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Products"],"summary":"Create an option group","operationId":"createOptionGroup","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionGroupCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionGroup"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/sales-channels":{"get":{"tags":["Products"],"summary":"Get a product's sales channels","operationId":"getProductSalesChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelAssignment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Products"],"summary":"Set a product's sales channels","description":"`all: true` shows it on every channel; otherwise only on\n`sales_channel_ids`.","operationId":"setProductSalesChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelAssignment"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelAssignment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `sales_channel_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/slug":{"patch":{"tags":["Products"],"summary":"Change a product's slug","description":"The previous slug becomes a 301 redirect to the product, so old links\nkeep working.","operationId":"updateProductSlug","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSlugUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSlugUpdate"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`slug_taken`: another product uses the slug or holds it as a redirect","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: nothing usable in the slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/slug-redirects":{"get":{"tags":["Products"],"summary":"List a product's slug redirects","description":"Newest first.","operationId":"listProductSlugRedirects","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ProductSlugRedirect"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/slug-redirects/{redirect_id}":{"delete":{"tags":["Products"],"summary":"Delete a slug redirect","description":"The old URL stops redirecting and the slug becomes free.","operationId":"deleteProductSlugRedirect","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"redirect_id","in":"path","description":"Redirect id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such redirect for this product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/specs":{"get":{"tags":["Products"],"summary":"Get a product's specifications","description":"The whole spec sheet in one call: the global groups and fields, the\ntaxonomies with their terms, the values set on this product, and the\nstore's collections for `collection_ref` fields. Taxonomy values are in\n`term_ids` (plus `value_texts` for free-form entries); other kinds use\n`value_text`.","operationId":"getProductSpecs","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSpecsResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such product in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/specs/{field_id}":{"put":{"tags":["Products"],"summary":"Set a product's specification value","description":"Sets, replaces or clears one field. An empty payload (no terms, no\ncollections, blank text) clears it and answers 204. The field's kind\ndecides what is accepted:\n\n- `taxonomy`: `term_ids` (at most one unless the field is `multiple`),\n  an optional `value_text` override, and `value_texts` when the field\n  has `allow_freeform`.\n- `collection_ref`: `collection_ids` of the store's collections; this\n  writes the product's collection membership.\n- anything else: `value_text`.","operationId":"setProductSpec","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"field_id","in":"path","description":"Spec field id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertSpecValueRequest"}}},"required":true},"responses":{"200":{"description":"The stored value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSpecValue"}}}},"204":{"description":"The value was cleared"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such product in this store, or no such field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_spec_value`: the payload does not fit the field's kind","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/stock":{"get":{"tags":["Products"],"summary":"Get a kit's component stock","description":"For kit products: how many kits the components on hand allow, and each\ncomponent's stock. Empty for products without components. For a\nproduct's own stock per location see `GET .../products/{product_id}`.","operationId":"getProductComponentStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductStockResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/suggested":{"get":{"tags":["Products"],"summary":"List a product's suggested products","operationId":"listSuggestedProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_SuggestedProduct"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Products"],"summary":"Set a product's suggested products","description":"Replaces the list.","operationId":"setSuggestedProducts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestedProductsSetRequest"}}},"required":true},"responses":{"204":{"description":"Replaced"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/variants":{"get":{"tags":["Products"],"summary":"List a product's variants","description":"Every variant, active or not, in display order, with stock summed over\nthe store's locations.","operationId":"listProductVariants","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ProductVariant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Products"],"summary":"Create a variant","description":"Adds a variant to the product. The SKU must be unique across the\nplatform.","operationId":"createProductVariant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVariant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`sku_taken`: another variant already uses this SKU","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/variants/reorder":{"put":{"tags":["Products"],"summary":"Reorder a product's variants","operationId":"reorderProductVariants","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantReorderRequest"}}},"required":true},"responses":{"204":{"description":"Reordered"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/products/{product_id}/videos":{"post":{"tags":["Products"],"summary":"Add a video to a product's gallery","description":"By URL (YouTube, Vimeo or a video file). `provider` is detected from the\nURL when omitted. Emits the `product.image.created` webhook.","operationId":"attachProductVideo","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","description":"Product id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachVideoRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductImage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`product_not_found`, `variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: the URL is not http(s)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/purchase-orders":{"get":{"tags":["Purchasing"],"summary":"List purchase orders","description":"Newest first, with supplier and totals. Keyset-paged; `offset` also\nworks for page-number tables.","operationId":"listPurchaseOrders","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Where a purchase order stands (see the tag description).","enum":["draft","ordered","partial","received","cancelled"]}},{"name":"supplier_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_PurchaseOrder"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Purchasing"],"summary":"Create a purchase order","description":"A `draft` order, numbered `PO-NNNN` per store. Each line snapshots the\nvariant's SKU and name as they read today.","operationId":"createPurchaseOrder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`supplier_not_found`, `location_not_in_store`, `item_not_found_in_store`, `quantity_must_be_positive`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/purchase-orders/{po_id}":{"get":{"tags":["Purchasing"],"summary":"Get a purchase order","operationId":"getPurchaseOrder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"po_id","in":"path","description":"Purchase order id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`purchase_order_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Purchasing"],"summary":"Update a purchase order","description":"Changes the fields sent (omitted ones stay). `lines` replaces every line\nand is only allowed on a draft. `status` moves a draft to `ordered`, or\ncancels an order that is not received.","operationId":"updatePurchaseOrder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"po_id","in":"path","description":"Purchase order id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`purchase_order_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`order_not_editable` (lines on a non-draft), `invalid_status_transition`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`supplier_not_found`, `location_not_in_store`, `item_not_found_in_store`, `quantity_must_be_positive`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/purchase-orders/{po_id}/receive":{"post":{"tags":["Purchasing"],"summary":"Receive a purchase order","description":"Books one delivery: a receipt with its lines, a `stock_in` movement per\nline carrying the landed unit cost (shipping and other costs spread over\nevery unit ordered), the variant's moving average cost, and the order's\nnew status (`partial` or `received`), all in one transaction.\n\nEvery call books a new delivery, so send an `Idempotency-Key`: a retry\nwith the same key replays the first answer instead of receiving the\ngoods twice.","operationId":"receivePurchaseOrder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"po_id","in":"path","description":"Purchase order id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseReceiveRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseReceiptResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`purchase_order_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`order_cancelled`, `inventory_managed_externally`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`line_not_on_order`, `location_not_in_store`, `no_inventory_location`, `nothing_to_receive` (no line with a positive quantity)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/quotes":{"get":{"tags":["Quotes"],"summary":"List quotes","description":"Newest first.","operationId":"listQuotes","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_QuoteSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Quotes"],"summary":"Create a quote","description":"Builds a cart at storefront prices (stock is checked and reserved like a\nshopper's add to cart), applies the negotiated discount and, when the\nseller picked one, re-quotes and applies the freight. Answers with the\nlink to send the customer, who pays it through the normal checkout.\n\n`freight_applied` is false when the seller's carrier was not offered on\nthe re-quote (the customer then picks one on the link);\n`freight_price_changed` when it was, at a different price.","operationId":"createQuote","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteCreated"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`, `customer_not_found` or `sales_channel_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`insufficient_stock`: not enough stock for a line","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`empty_quote`, `invalid_max_installments` (1 to 12) or `invalid_discount` (percent under 100%)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/quotes/{cart_id}/expire":{"post":{"tags":["Quotes"],"summary":"Expire a quote","description":"The link stops working right away. A quote the customer already paid is\nunaffected.","operationId":"expireQuote","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cart_id","in":"path","description":"The quote's cart id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Expired"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such quote in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/refunds":{"get":{"tags":["Payments"],"summary":"List refunds","description":"Refunds issued through the payment provider, newest first, keyset-paged\n(follow `next_cursor`). Refunds made before the refund ledger existed\nare not listed.","operationId":"listRefunds","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"order_id","in":"query","description":"Only this order's refunds.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"created_after","in":"query","description":"Only refunds issued at or after this instant.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","description":"Only refunds issued before this instant.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Refund"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/reservations":{"get":{"tags":["Inventory"],"summary":"List reservations","description":"Every held unit with its order attached, newest first. Keyset-paged;\n`offset` also works for page-number tables.","operationId":"listReservations","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Defaults to `active`.","required":false,"schema":{"type":"string","description":"Which reservations to list: one status, or `all`.","enum":["active","released","consumed","expired","cancelled","all"]}},{"name":"search","in":"query","description":"Matches SKU, variant name or order number.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Reservation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/reservations/{reservation_id}/consume":{"post":{"tags":["Inventory"],"summary":"Consume a reservation","description":"The held units left the shelf: on-hand and reserved both drop. Writes a\n`consume` movement. Closing twice answers 409 `reservation_not_active`.","operationId":"consumeReservation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"reservation_id","in":"path","description":"Reservation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationCloseResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`reservation_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`reservation_not_active`: already closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/reservations/{reservation_id}/release":{"post":{"tags":["Inventory"],"summary":"Release a reservation","description":"Gives the held units back to available stock; the physical units never\nmoved. Writes a `release` movement. Closing twice answers 409\n`reservation_not_active`, so a retry is harmless.","operationId":"releaseReservation","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"reservation_id","in":"path","description":"Reservation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationCloseResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`reservation_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`reservation_not_active`: already closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/reviews":{"get":{"tags":["Reviews"],"summary":"List reviews","description":"Newest first, keyset-paged (`offset` also works). For the moderation\nqueue's badge, count pending reviews with\n`status=pending&limit=1&include_total=true`.","operationId":"listReviews","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"`pending` (waiting for moderation), `approved` (shown on the storefront)\nor `rejected`.","enum":["pending","approved","rejected"]}},{"name":"product_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ReviewWithProduct"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/reviews/settings":{"get":{"tags":["Reviews"],"summary":"Get review settings","operationId":"getReviewSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Reviews"],"summary":"Update review settings","description":"Partial: omitted fields keep their value. Answers with the settings.","operationId":"updateReviewSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSettingsUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/reviews/{review_id}":{"delete":{"tags":["Reviews"],"summary":"Delete a review","operationId":"deleteReview","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"review_id","in":"path","description":"Review id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such review in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Reviews"],"summary":"Moderate a review","description":"Approve, reject or send a review back to pending. Records who decided\nand when. Only `approved` reviews show on the storefront.","operationId":"updateReview","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"review_id","in":"path","description":"Review id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Review"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such review in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/roles":{"get":{"tags":["Team"],"summary":"List roles","description":"The store's roles by position, built-in presets included (they are\ncreated on first use).","operationId":"listRoles","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StoreRole"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Team"],"summary":"Create a role","description":"The codes must be in the catalog and within the caller's own\npermissions.","operationId":"createRole","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStoreRoleRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreRole"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`missing_permission` or `grant_exceeds_actor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: bad name or unknown codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/roles/audit":{"get":{"tags":["Team"],"summary":"List role and membership changes","description":"Who changed which role or membership, newest first.","operationId":"listRoleAudit","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_RoleAuditEntry"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/roles/{role_id}":{"delete":{"tags":["Team"],"summary":"Delete a role","description":"Holders lose the role's permissions. Built-in roles cannot be deleted.","operationId":"deleteRole","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"role_id","in":"path","description":"Role id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Role deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such role in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`system_role`: built-in roles cannot be deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Team"],"summary":"Update a role","description":"Fields left out stay as they are. New codes must be within the\ncaller's own permissions. Takes effect for every holder at once.","operationId":"updateRole","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"role_id","in":"path","description":"Role id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStoreRoleRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreRole"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`missing_permission` or `grant_exceeds_actor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such role in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: unknown codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/sales-channels":{"get":{"tags":["Sales Channels"],"summary":"List sales channels","description":"By name.","operationId":"listSalesChannels","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_SalesChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Sales Channels"],"summary":"Create a sales channel","description":"Emits the `sales_channel.created` webhook.","operationId":"createSalesChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`web_channel_exists`: a store has one web channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/sales-channels/{channel_id}":{"put":{"tags":["Sales Channels"],"summary":"Update a sales channel","description":"Partial: omitted fields keep their value. Emits the\n`sales_channel.updated` webhook.","operationId":"updateSalesChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Sales channel id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannel"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`web_channel_exists`: a store has one web channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Sales Channels"],"summary":"Delete a sales channel","description":"The `web` channel is the storefront and cannot be deleted. Orders and\ncarts from the channel keep their records only if the database allows\nit; a channel that orders reference answers 409. Emits the\n`sales_channel.deleted` webhook.","operationId":"deleteSalesChannel","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Sales channel id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`web_channel_protected`: the storefront channel; `sales_channel_in_use`: orders or carts reference it (deactivate it instead)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/sales-channels/{channel_id}/generate-api-key":{"post":{"tags":["Sales Channels"],"summary":"Generate a sales channel API key","description":"Mints a new `msc_live_…` key for the channel and replaces the previous\none, which stops working. The key is only returned here; the channel\nkeeps a hash and `api_key_prefix`.","operationId":"generateSalesChannelApiKey","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"channel_id","in":"path","description":"Sales channel id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesChannelApiKey"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such channel in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/search":{"get":{"tags":["Search"],"summary":"Search the store","description":"Matches orders (number, customer name or e-mail), customers (name,\ne-mail, phone digits), products (title, slug, SKU), e-mail campaigns and\nconversations, returning up to `limit` of each. Groups the caller has\nno read permission for come back empty.","operationId":"searchStore","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Search text; at least 2 characters or every group comes back empty.","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Hits per group, 1 to 20. Defaults to 5.","required":false,"schema":{"type":"integer","format":"int64","maximum":20,"minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`missing_permission`: the caller may read none of the groups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/settings":{"get":{"tags":["Stores"],"summary":"Get store settings","description":"Stock reservation, dispatch time, abandoned-cart recovery and review\nrequests.","operationId":"getStoreSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreFulfillmentSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Stores"],"summary":"Update store settings","description":"Fields left out stay as they are.","operationId":"updateStoreSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStoreFulfillmentSettingsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreFulfillmentSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: a value is out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/shipping-boxes":{"get":{"tags":["Shipping Boxes"],"summary":"List shipping boxes","description":"The store's boxes, by name.","operationId":"listShippingBoxes","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ShippingBox"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Shipping Boxes"],"summary":"Create a shipping box","description":"Emits the `shipping_box.created` webhook.","operationId":"createShippingBox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingBoxCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingBox"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/shipping-boxes/{box_id}":{"get":{"tags":["Shipping Boxes"],"summary":"Get a shipping box","operationId":"getShippingBox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"box_id","in":"path","description":"Shipping box id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingBox"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`shipping_box_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Shipping Boxes"],"summary":"Update a shipping box","description":"Changes the fields sent. Emits the `shipping_box.updated` webhook.","operationId":"updateShippingBox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"box_id","in":"path","description":"Shipping box id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingBoxUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingBox"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`shipping_box_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Shipping Boxes"],"summary":"Delete a shipping box","description":"Also removes it from every variant. Emits the `shipping_box.deleted`\nwebhook.","operationId":"deleteShippingBox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"box_id","in":"path","description":"Shipping box id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`shipping_box_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/spec-fields/{field_id}/suggestions":{"get":{"tags":["Products"],"summary":"List values used for a spec field","description":"Distinct free-form values this store has entered for the field, most\nrecently used first (the 100 most recent). Feeds autocomplete on text,\ndimension and weight inputs and the \"recently used\" section of\nfree-form taxonomy pickers.","operationId":"listSpecFieldSuggestions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"field_id","in":"path","description":"Spec field id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_String"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock":{"get":{"tags":["Inventory"],"summary":"List stock","description":"One row per stocked variant, variants and components together (`role`\nnarrows). Quantities sum across locations unless `location_id` names\none. Items at or below their reorder point come first, then by name.","operationId":"listStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"query","description":"Quantities at this location only; omitted sums every location.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches SKU or name.","required":false,"schema":{"type":"string"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","description":"Which role of stocked item to list. Being a component is a role, not a\ncategory: a component can also be sold on its own.","enum":["all","product","component"]}},{"name":"low_stock","in":"query","description":"Only items at or below their reorder point.","required":false,"schema":{"type":"boolean"}},{"name":"out_of_stock","in":"query","description":"Only items with nothing to sell: buildable 0 for kits, available 0\notherwise.","required":false,"schema":{"type":"boolean"}},{"name":"in_stock_only","in":"query","description":"Only items with something to sell.","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StockListItem"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock-counts":{"get":{"tags":["Inventory"],"summary":"List stock counts","description":"Count sheets, newest first, with how far along each is.","operationId":"listStockCounts","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Where a count stands. `draft` and `counting` accept entries; `posted`\nand `cancelled` are closed.","enum":["draft","counting","posted","cancelled"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StockCount"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Inventory"],"summary":"Start a stock count","description":"Draws a count sheet for one location, snapshotting what the book says\neach active variant has there. Nothing moves until the count is posted.","operationId":"createStockCount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCount"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`location_not_in_store`, `no_inventory_location`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock-counts/{count_id}":{"get":{"tags":["Inventory"],"summary":"Get a stock count","description":"The sheet and its lines (up to 2000, by name), optionally only the\nvariances, only the uncounted lines, or those matching a search. To find\nthe line for a scanned barcode, pass it as `search`.","operationId":"getStockCount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"count_id","in":"path","description":"Stock count id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","description":"Which lines of a count sheet to return.","enum":["all","variance","uncounted"]}},{"name":"search","in":"query","description":"Matches SKU, barcode or name.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`stock_count_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock-counts/{count_id}/cancel":{"post":{"tags":["Inventory"],"summary":"Cancel a stock count","description":"Abandons the sheet without moving stock. A posted count cannot be\ncancelled; cancelling a cancelled one is a no-op.","operationId":"cancelStockCount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"count_id","in":"path","description":"Stock count id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCount"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`stock_count_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`count_closed`: already posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock-counts/{count_id}/import":{"put":{"tags":["Inventory"],"summary":"Import counted quantities from CSV","description":"Fills a count sheet from a spreadsheet: a column of SKUs (`sku`,\n`codigo`, `code`, `referencia`) and one of quantities (`quantidade`,\n`qtd`, `contagem`, `contado`, `quantity`, `counted`, `qty`, `em_maos`);\nwithout a recognisable header, the first two columns. Blank quantities\nstay uncounted; `3`, `3,0` and `3.0` all read as 3. Writes counted\nquantities only: the sheet still has to be posted. SKUs not on the\nsheet are reported, not added.","operationId":"importStockCount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"count_id","in":"path","description":"Stock count id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"The spreadsheet as CSV","content":{"text/csv":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountImportResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`stock_count_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`count_closed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`empty_file`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock-counts/{count_id}/items/{line_id}":{"patch":{"tags":["Inventory"],"summary":"Enter a counted quantity","description":"Sets (or clears) what was counted on one line. Absolute, so retrying is\nharmless. Moves no stock until the count is posted.","operationId":"setStockCountLine","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"count_id","in":"path","description":"Stock count id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"line_id","in":"path","description":"Line id (`StockCountItem.id`)","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountLineUpdate"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountItem"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`stock_count_not_found`, `stock_count_line_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`count_closed`: posted or cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock-counts/{count_id}/post":{"post":{"tags":["Inventory"],"summary":"Post a stock count","description":"Applies the sheet: every counted line that disagrees with the book\nbecomes a `count` movement setting on-hand at the location to the\ncounted figure, all in one transaction, and the count becomes `posted`.\nA count can be posted once: a retry answers 409 `count_closed` (with an\n`Idempotency-Key` it replays the first answer instead).","operationId":"postStockCount","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"count_id","in":"path","description":"Stock count id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"description":"Optional","content":{"application/json":{"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/StockCountPostRequest"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockCountPostResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`stock_count_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`count_closed`, `inventory_managed_externally`, `logical_stock_readonly` (a kit on the sheet; `details.variant_id`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock/bulk-adjust":{"post":{"tags":["Inventory"],"summary":"Adjust stock in bulk","description":"Up to 500 adjustments at one location in one transaction: all apply or\nnone do. Each line is a `delta` or a `set_to`, like `adjustVariantStock`.\nSend an `Idempotency-Key`.","operationId":"bulkAdjustStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStockAdjustRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStockAdjustResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`insufficient_stock`, `inventory_managed_externally`, `logical_stock_readonly` (`details.variant_id` names the line)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`items_out_of_range`, `ambiguous_adjustment`, `item_not_found_in_store` (`details.variant_id`), `location_not_in_store`, `no_inventory_location`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock/bulk-reorder":{"post":{"tags":["Inventory"],"summary":"Set reorder points in bulk","description":"Replaces the reorder point and quantity of many variants at once.","operationId":"bulkSetReorder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReorderRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReorderResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock/export":{"get":{"tags":["Inventory"],"summary":"Export stock as CSV","description":"The whole filtered stock list (same filters as `listStock`, no paging)\nas a spreadsheet, columns `sku, nome, fisico, logico, em_maos,\nreservado, disponivel, montavel, gargalo_sku, ponto_reposicao,\nquantidade_reposicao`.","operationId":"exportStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"location_id","in":"query","description":"Quantities at this location only; omitted sums every location.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches SKU or name.","required":false,"schema":{"type":"string"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","description":"Which role of stocked item to list. Being a component is a role, not a\ncategory: a component can also be sold on its own.","enum":["all","product","component"]}},{"name":"low_stock","in":"query","description":"Only items at or below their reorder point.","required":false,"schema":{"type":"boolean"}},{"name":"out_of_stock","in":"query","description":"Only items with nothing to sell: buildable 0 for kits, available 0\notherwise.","required":false,"schema":{"type":"boolean"}},{"name":"in_stock_only","in":"query","description":"Only items with something to sell.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock/movements":{"get":{"tags":["Inventory"],"summary":"List stock movements","description":"The store's stock ledger, newest first: every quantity that moved, with\nits kind, reason, the document behind it (order, receipt, count,\ntransfer) and who made it. Keyset-paged (`next_cursor`); `offset` also\nworks for page-number tables.","operationId":"listStockMovements","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","description":"What kind of stock movement a ledger entry records:\n\n- `stock_in` / `stock_out`: goods received (a purchase receipt, an\n  opening balance) or removed outside an order.\n- `reserve` / `release` / `consume`: an order or build job holding units,\n  letting them go, or shipping them.\n- `adjustment`: a manual correction (with a `reason`), or the undo of an\n  earlier movement.\n- `transfer`: units moving between two locations (one entry per side).\n- `count`: the difference a posted stock count wrote.\n- `build_consume` / `build_produce`: parts used and kits made by a build.\n\nMirrors `inventory_events_type_check`. The set may grow; tolerate\nunknown values.","enum":["stock_in","stock_out","reserve","release","consume","adjustment","transfer","count","build_consume","build_produce"]}},{"name":"reason","in":"query","required":false,"schema":{"type":"string","description":"Why stock was adjusted by hand. A closed list so the history can be\ngrouped and reported on; put anything else in the free-text `note`.\n\n`opening_balance` (first load of a real shelf count), `damaged`, `lost`,\n`theft`, `found` (on the shelf but not in the book), `correction` (the\nbook was wrong; the default), `customer_return`, `supplier_return`,\n`expired`, `sample`, `other`.","enum":["opening_balance","damaged","lost","theft","found","correction","customer_return","supplier_return","expired","sample","other"]}},{"name":"location_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"actor_id","in":"query","description":"Movements made by this user.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"reference_type","in":"query","required":false,"schema":{"type":"string","description":"The document a movement came from.","enum":["order","cart","purchase_receipt","stock_count","transfer","erp_sync","reversal"]}},{"name":"variant_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Matches SKU, variant or product title.","required":false,"schema":{"type":"string"}},{"name":"created_after","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StockMovement"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock/movements/{movement_id}/reverse":{"post":{"tags":["Inventory"],"summary":"Reverse a stock movement","description":"Undoes a manual adjustment, a transfer side, a receipt, a removal or a\ncount line by writing the opposite `adjustment` (reason `correction`)\nand linking the two (`reversed_by` / `reversal_of`). Reservations and\norder movements are not reversible here. A movement can be reversed\nonce, so a retried reversal answers 409 `already_reversed`.","operationId":"reverseStockMovement","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"movement_id","in":"path","description":"Movement id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"description":"Optional","content":{"application/json":{"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/StockReverseRequest"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReversalResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`movement_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`already_reversed`, `insufficient_stock` (the units to take back are no longer on hand), `inventory_managed_externally`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`movement_not_reversible`, `cannot_reverse_a_reversal`, `nothing_to_reverse`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock/overview":{"get":{"tags":["Inventory"],"summary":"Get the stock overview","description":"What needs attention today: out-of-stock and low-stock counts, totals,\nstock value at cost, open and overdue purchase orders, counts in\nprogress, and whether an ERP owns the numbers.","operationId":"getStockOverview","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockOverview"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/stock/reorder-draft":{"post":{"tags":["Purchasing"],"summary":"Draft a purchase order from low stock","description":"Creates a `draft` purchase order with one line per variant whose\navailable plus incoming units are at or below its reorder point:\n`reorder_quantity` units (or enough to reach the point), at the last\npurchase cost or the variant's cost.","operationId":"createReorderDraft","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderDraftRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`nothing_below_reorder_point`, `supplier_not_found`, `location_not_in_store`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/storefront/deployments":{"get":{"tags":["Storefront"],"summary":"List theme deployments","description":"Builds of the store's connected theme repository, newest first, with\n`is_active` set on the one the production storefront serves.","operationId":"listStorefrontDeployments","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StorefrontDeployment"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/storefront/deployments/{deployment_id}/promote":{"post":{"tags":["Storefront"],"summary":"Promote a deployment","description":"Makes a `ready` deployment the one the production storefront serves\n(also the rollback button: promote an older one) and purges the CDN\ncache so the change is live at once.","operationId":"promoteStorefrontDeployment","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deployment_id","in":"path","description":"Deployment id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Promoted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such deployment in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`deployment_not_ready`: the deployment is building, failed or archived; `storefront_repo_not_connected`: the store has no connected repository","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/storefront/preview-suffix":{"get":{"tags":["Storefront"],"summary":"Get preview settings","description":"The host suffix preview deployments are served under, for building\npreview links per deployment.","operationId":"getStorefrontPreviewSettings","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPreviewSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/suppliers":{"get":{"tags":["Purchasing"],"summary":"List suppliers","description":"Active suppliers first, then by name, with their open order counts.","operationId":"listSuppliers","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Supplier"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Purchasing"],"summary":"Create a supplier","operationId":"createSupplier","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/suppliers/{supplier_id}":{"put":{"tags":["Purchasing"],"summary":"Update a supplier","description":"Replaces every field (`is_active` omitted keeps the current value).","operationId":"updateSupplier","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"supplier_id","in":"path","description":"Supplier id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`supplier_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/transfer-ownership":{"post":{"tags":["Team"],"summary":"Transfer store ownership","description":"Hands the store to another member. Only the current owner or the\ntenant owner may do this. The previous owner keeps access as Manager.","operationId":"transferStoreOwnership","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferOwnershipRequest"}}},"required":true},"responses":{"204":{"description":"Ownership transferred"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`not_owner`: only the owner may transfer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store, or `not_a_member`: the target is not a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/usage":{"get":{"tags":["Stores"],"summary":"Get the store's usage","description":"Daily counters of metered usage (e-mails sent, assistant use...) and\ntoday's marketing e-mail cap.","operationId":"getStoreUsage","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","description":"Days back, 1 to 365. Defaults to 30.","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreUsage"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/users/{user_id}/roles":{"get":{"tags":["Team"],"summary":"List a member's roles","operationId":"listUserRoles","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"path","description":"The member's user id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StoreRole"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Team"],"summary":"Set a member's roles","description":"Replaces every role the user holds in the store with `role_ids` and\nreturns the roles now held. Also adds a user to the store. The roles\ntogether may not grant permissions the caller does not hold. The\nstore owner's roles cannot be changed; transfer ownership first.","operationId":"replaceUserRoles","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"path","description":"The member's user id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceUserRolesRequest"}}},"required":true},"responses":{"200":{"description":"The roles the user now holds, by position","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StoreRole"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`missing_permission` or `grant_exceeds_actor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`owner_roles_locked`: the user owns the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/lookup":{"get":{"tags":["Products"],"summary":"Look up a variant by SKU or barcode","description":"For scanning: finds the variant whose SKU (case-insensitive) or barcode\nequals `code`, falling back to a product whose GTIN, EAN or UPC equals\nit. Returns the variant with its options and stock per location, and its\nproduct as a list row. Drafts and archived products are found too. When\nthe code is shared (`match_count` above 1), `matches` lists every\nmatch so the user can pick one.","operationId":"lookupVariant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"code","in":"query","description":"An exact SKU (case-insensitive) or barcode/GTIN/EAN/UPC, as typed\nor scanned. Surrounding whitespace is ignored.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantLookup"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`: nothing in the store has this code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}":{"get":{"tags":["Products"],"summary":"Get a variant","operationId":"getVariant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVariantDetail"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Products"],"summary":"Update a variant","description":"Partial: omitted fields keep their value, an explicit `null` clears a\nnullable one (`clear_compare_at: true` also clears the compare-at\nprice). Use it to change a price (`price_cents`, `compare_at_cents`)\nor to hide a variant (`is_active`). Price,\navailability and title changes are pushed to the Meta catalog when the\nstore has one.","operationId":"updateVariant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVariant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`sku_taken`: another variant already uses this SKU","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Products"],"summary":"Delete a variant","description":"Refused while any order references the variant or it has stock on hand\nor reserved; deactivate it instead. Emits the `product_variant.deleted`\nwebhook.","operationId":"deleteVariant","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`variant_has_orders`: orders reference this variant; `variant_has_stock`: it has units on hand or reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/options":{"get":{"tags":["Products"],"summary":"Get a variant's options","operationId":"getVariantOptions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantWithOptions"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Products"],"summary":"Give a variant an option value","description":"Idempotent. The value must belong to one of the product's option groups.","operationId":"assignVariantOption","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantOptionAssignRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantWithOptions"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`, or `option_value_not_found` when the value is not one of the product's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/shipping-boxes":{"get":{"tags":["Shipping Boxes"],"summary":"List a variant's shipping boxes","description":"The primary box first, then by name.","operationId":"listVariantShippingBoxes","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_AssignedShippingBox"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Shipping Boxes"],"summary":"Assign a shipping box to a variant","description":"Adds the box to the variant (or updates the assignment when it is\nalready there).","operationId":"assignVariantShippingBox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantBoxAssignRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantShippingBox"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`shipping_box_not_in_store`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/shipping-boxes/{box_id}":{"put":{"tags":["Shipping Boxes"],"summary":"Update a variant's shipping box","operationId":"updateVariantShippingBox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"box_id","in":"path","description":"Shipping box id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantBoxUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantShippingBox"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`, `shipping_box_not_found` (not assigned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Shipping Boxes"],"summary":"Remove a shipping box from a variant","operationId":"removeVariantShippingBox","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"box_id","in":"path","description":"Shipping box id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`, `shipping_box_not_found` (not assigned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/stock":{"get":{"tags":["Inventory"],"summary":"Get a variant's stock per location","description":"Totals, the stock at every active location of the store (zero-filled, so\na client can offer any location as a target), incoming purchase-order\nunits, the reorder settings, and who owns the store's stock. After a\nbarcode scan, `GET /stores/{store_id}/variants/lookup?code=` gives the\nvariant id.","operationId":"getVariantStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VariantStock"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/stock/adjust":{"post":{"tags":["Inventory"],"summary":"Adjust a variant's stock","description":"Changes the units on hand at one location by a signed `delta`, or sets\nthem to an absolute count with `set_to`, with a reason and an optional\nnote. Writes an `adjustment` entry to the ledger and answers with the\nvariant's new levels. Emits the `inventory.updated` webhook\n(`inventory.out_of_stock` / `inventory.low_stock` too when the location\nreaches 0 / 5 or fewer).\n\nSafe on a flaky network: send an `Idempotency-Key` and retry with the\nsame key until you get an answer; a `set_to` is idempotent even without\none.\n\nRefused while an ERP owns the store's stock (409\n`inventory_managed_externally`, unless `force: true`) and for kits\n(409 `logical_stock_readonly`).","operationId":"adjustVariantStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockAdjustRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockAdjustResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`insufficient_stock` (a negative `delta` larger than the units on hand; `details.on_hand`), `multiple_locations` (`set_to` without `location_id` on a variant stocked in several places), `inventory_managed_externally` (`details.owner`, `details.owner_name`), `logical_stock_readonly` (a kit; `details.max_shippable`, `details.limiting_sku`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`ambiguous_adjustment` (both or neither of `delta` and `set_to`), `location_not_in_store`, `no_inventory_location` (the store has no active location), `validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/stock/movements":{"get":{"tags":["Inventory"],"summary":"List a variant's stock movements","description":"Why a variant's quantity is what it is: its ledger entries, newest first,\nkeyset-paged. Same rows as `listStockMovements` filtered to the variant.","operationId":"listVariantStockMovements","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","description":"What kind of stock movement a ledger entry records:\n\n- `stock_in` / `stock_out`: goods received (a purchase receipt, an\n  opening balance) or removed outside an order.\n- `reserve` / `release` / `consume`: an order or build job holding units,\n  letting them go, or shipping them.\n- `adjustment`: a manual correction (with a `reason`), or the undo of an\n  earlier movement.\n- `transfer`: units moving between two locations (one entry per side).\n- `count`: the difference a posted stock count wrote.\n- `build_consume` / `build_produce`: parts used and kits made by a build.\n\nMirrors `inventory_events_type_check`. The set may grow; tolerate\nunknown values.","enum":["stock_in","stock_out","reserve","release","consume","adjustment","transfer","count","build_consume","build_produce"]}},{"name":"location_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StockMovement"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/stock/reorder":{"put":{"tags":["Inventory"],"summary":"Set a variant's reorder point","description":"Replaces the reorder point and quantity that drive the low-stock filter,\nthe overview's low-stock count and `createReorderDraft`.","operationId":"setVariantReorder","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderSettings"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderSettings"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/variants/{variant_id}/stock/transfer":{"post":{"tags":["Inventory"],"summary":"Transfer a variant's stock between locations","description":"Moves units from one location to another in one transaction: two\n`transfer` ledger entries sharing a `reference_id` (the `transfer_id`).\nAnswers with the variant's new levels. Send an `Idempotency-Key`: a\ntransfer retried without one moves the units twice.","operationId":"transferVariantStock","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransferResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`variant_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`insufficient_stock` (`details.available` at the source), `inventory_managed_externally`, `logical_stock_readonly`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`quantity_must_be_positive`, `same_location`, `location_not_in_store`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"Newest first. `event` narrows to webhooks subscribed to that event.","operationId":"listWebhooks","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event","in":"query","description":"Only webhooks subscribed to this event.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Webhook"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook","description":"Registers an endpoint for the store's events. Subscribe to events with\n`events` here or `POST .../webhooks/{webhook_id}/events`.","operationId":"createWebhook","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: invalid URL, or an event name not in `GET /events/catalog`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/webhooks/{webhook_id}":{"put":{"tags":["Webhooks"],"summary":"Update a webhook","description":"Fields left out stay as they are.","operationId":"updateWebhook","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhook_id","in":"path","description":"Webhook id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such webhook in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: invalid URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","description":"Removes the webhook with its subscriptions and delivery log.","operationId":"deleteWebhook","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhook_id","in":"path","description":"Webhook id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Webhook deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such webhook in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/webhooks/{webhook_id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List a webhook's deliveries","description":"Delivery attempts, newest first.","operationId":"listWebhookDeliveries","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhook_id","in":"path","description":"Webhook id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_WebhookDelivery"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such webhook in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/webhooks/{webhook_id}/events":{"get":{"tags":["Webhooks"],"summary":"List a webhook's events","description":"The event names the webhook is subscribed to, alphabetically. Also on\nthe webhook itself as `events`.","operationId":"listWebhookEvents","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhook_id","in":"path","description":"Webhook id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_WebhookEventRow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such webhook in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Webhooks"],"summary":"Subscribe a webhook to events","description":"Adds event names to the webhook's subscriptions. Names already\nsubscribed are ignored.","operationId":"addWebhookEvents","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhook_id","in":"path","description":"Webhook id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddWebhookEventsRequest"}}},"required":true},"responses":{"204":{"description":"Subscribed"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such webhook in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: an event name is not in `GET /events/catalog`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/webhooks/{webhook_id}/events/{event}":{"delete":{"tags":["Webhooks"],"summary":"Unsubscribe a webhook from an event","operationId":"removeWebhookEvent","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhook_id","in":"path","description":"Webhook id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","description":"Event name, e.g. `orders.paid`","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Unsubscribed (also when it was not subscribed)"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such webhook in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflow-runs":{"get":{"tags":["Workflows"],"summary":"List the store's runs","description":"Runs of every workflow, newest first.","operationId":"listStoreWorkflowRuns","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only runs in this state.","required":false,"schema":{"type":"string"}},{"name":"workflow_id","in":"query","description":"Only runs of this workflow.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_StoreWorkflowRun"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflow-runs/{run_id}/approval":{"post":{"tags":["Workflows"],"summary":"Decide a run's approval","description":"Approves or rejects the approval step the run is waiting on; the run\ncontinues on the matching path. Also possible from the links in the\napprover's e-mail.","operationId":"decideWorkflowRunApproval","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"run_id","in":"path","description":"Run id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowApprovalRequest"}}},"required":true},"responses":{"204":{"description":"Decided"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such run in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`run_not_awaiting_approval`: already decided, or not on an approval step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflow-runs/{run_id}/cancel":{"post":{"tags":["Workflows"],"summary":"Cancel a run","description":"Stops a pending, running, waiting or approval-waiting run where it is.","operationId":"cancelWorkflowRun","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"run_id","in":"path","description":"Run id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Cancelled"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such run in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`run_not_active`: already finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflow-runs/{run_id}/retry":{"post":{"tags":["Workflows"],"summary":"Retry a run","description":"Starts a new run with the same trigger payload and customer (linked by\n`retry_of`); answers 202 with it.","operationId":"retryWorkflowRun","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"run_id","in":"path","description":"Run id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"Started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRun"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such run in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`run_active`: the run has not finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`run_not_retryable`: e.g. the workflow is gone or was never published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflow-secrets":{"get":{"tags":["Workflows"],"summary":"List workflow secrets","description":"Names only, alphabetically. Needs `workflows.read`.","operationId":"listWorkflowSecrets","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_WorkflowSecret"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Workflows"],"summary":"Save a workflow secret","description":"Creates the secret, or replaces the value of the one with this name.\nValues are encrypted at rest and masked in run logs.","operationId":"saveWorkflowSecret","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertWorkflowSecretRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowSecret"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: bad name, or empty or too long value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflow-secrets/{name}":{"delete":{"tags":["Workflows"],"summary":"Delete a workflow secret","description":"Steps that still reference it no longer get its value.","operationId":"deleteWorkflowSecret","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"path","description":"Secret name (case-insensitive)","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such secret in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows":{"get":{"tags":["Workflows"],"summary":"List workflows","description":"The store's workflows and journeys, most recently edited first, each with\nrun counts over the last 7 days.","operationId":"listWorkflows","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"kind","in":"query","description":"Only journeys or only workflows.","required":false,"schema":{"$ref":"#/components/schemas/WorkflowKind"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_WorkflowListItem"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Workflows"],"summary":"Create a workflow","description":"Starts as a draft with the given graph and trigger (an empty graph and a\nmanual trigger by default). Nothing fires until it is published.","operationId":"createWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkflowRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/catalog":{"get":{"tags":["Workflows"],"summary":"Get the workflow node catalog","description":"Every node type the editor offers with its fields, ports and outputs, the\nexpression roots (`trigger`, `customer`, `store`, step outputs) and the\nfilters expressions can use. The shape follows the editor and grows with\nnew node types.","operationId":"getWorkflowNodeCatalog","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`{roots, nodes, ports, filters, ...}`","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}":{"get":{"tags":["Workflows"],"summary":"Get a workflow","operationId":"getWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Workflows"],"summary":"Delete a workflow","description":"Its runs, versions and history go with it.","operationId":"deleteWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Workflows"],"summary":"Update a workflow","description":"Changes the draft (name, description, graph, trigger) or sets it to\n`draft` / `paused`. What fires changes only on publish.","operationId":"updateWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkflowRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/duplicate":{"post":{"tags":["Workflows"],"summary":"Duplicate a workflow","description":"A draft copy of the current draft graph and trigger, named \"(cópia)\".\nWebhook tokens are not copied: the copy gets its own when configured.","operationId":"duplicateWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/fire":{"post":{"tags":["Workflows"],"summary":"Run a workflow now","description":"Starts a run of the published version with `payload` as its trigger\npayload; answers 202 with the run, which continues in the background. A\nworkflow that was never published runs its draft as a test (`dry_run`).","operationId":"runWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FireWorkflowRequest"}}},"required":true},"responses":{"202":{"description":"Started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRun"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `customer_id` is not a customer of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/publish":{"post":{"tags":["Workflows"],"summary":"Publish a workflow","description":"Freezes the draft as a new version and makes it fire (status `active`).\nRuns already in flight keep the version they started with.","operationId":"publishWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PublishWorkflowRequest"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowPublishResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`workflow_invalid`: the draft has errors; `details.problems` lists them (`WorkflowProblem`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/resume":{"post":{"tags":["Workflows"],"summary":"Resume a workflow","description":"A paused workflow fires again with its last published version (the draft\nis not published).","operationId":"resumeWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`workflow_not_published`: nothing to resume; publish instead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/runs":{"get":{"tags":["Workflows"],"summary":"List a workflow's runs","description":"Newest first, test runs included.","operationId":"listWorkflowRuns","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only runs in this state (`pending`, `running`, `waiting`,\n`awaiting_approval`, `completed`, `failed`, `cancelled`).","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_WorkflowRun"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/runs/{run_id}":{"get":{"tags":["Workflows"],"summary":"Get a run","description":"The run with every step it executed, oldest first, and each step's\noutput.","operationId":"getWorkflowRun","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"run_id","in":"path","description":"Run id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunWithSteps"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such run of this workflow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/test-node":{"post":{"tags":["Workflows"],"summary":"Test a workflow step","description":"Runs one step against real data without side effects: steps that send,\nwrite or call out describe what they would do; steps that read really\nread. Nothing the test writes persists.","operationId":"testWorkflowNode","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestWorkflowNodeRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowNodeTestResult"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow (or `run_id` run of it) in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: `customer_id` is not a customer of this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/unpublish":{"post":{"tags":["Workflows"],"summary":"Pause a workflow","description":"Stops firing (status `paused`) and clears the next scheduled fire. The\npublished version is kept; resume brings it back. Runs in flight carry on.","operationId":"unpublishWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/validate":{"get":{"tags":["Workflows"],"summary":"Validate a workflow","description":"Checks the current draft (graph and trigger) the way publishing does.","operationId":"validateWorkflow","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowValidation"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow in this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/versions":{"get":{"tags":["Workflows"],"summary":"List a workflow's versions","description":"Every published version, newest first.","operationId":"listWorkflowVersions","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_WorkflowVersion"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/stores/{store_id}/workflows/{workflow_id}/versions/{version}/restore":{"post":{"tags":["Workflows"],"summary":"Restore a workflow version","description":"Copies a past version's graph and trigger into the draft. Publish to make\nit fire.","operationId":"restoreWorkflowVersion","parameters":[{"name":"store_id","in":"path","description":"Store id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"workflow_id","in":"path","description":"Workflow id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","description":"Version number","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such workflow or version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/taxonomy/by-id":{"get":{"tags":["Categories"],"summary":"Get a marketplace category","description":"By the provider's id, with its full path in the requested language.\nPublic.","operationId":"getTaxonomyCategory","parameters":[{"name":"id","in":"query","description":"The provider's category id.","required":true,"schema":{"type":"string"}},{"name":"provider","in":"query","description":"Inferred when omitted: numeric ids are Google's.","required":false,"schema":{"type":"string","description":"Whose taxonomy.","enum":["google","facebook"]}},{"name":"locale","in":"query","description":"`en-US` (default) or `pt-BR`.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxonomyCategory"}}}},"404":{"description":"`taxonomy_category_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/taxonomy/search":{"get":{"tags":["Categories"],"summary":"Search marketplace categories","description":"Google product taxonomy and Meta product categories. Exact matches\nfirst, then prefix matches, then the rest alphabetically. Public.","operationId":"searchTaxonomy","parameters":[{"name":"q","in":"query","description":"Matches part of the category path, case-insensitively. Empty lists\neverything.","required":false,"schema":{"type":"string"}},{"name":"provider","in":"query","description":"One provider; both when omitted.","required":false,"schema":{"type":"string","description":"Whose taxonomy.","enum":["google","facebook"]}},{"name":"locale","in":"query","description":"`en-US` (default) or `pt-BR`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_TaxonomyCategory"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/tenants":{"get":{"tags":["Tenants"],"summary":"List tenants","description":"Tenants the caller owns or belongs to through a role in any of their\nstores, by name. An empty list means the user still has to create one.","operationId":"listTenants","parameters":[{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Tenant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Tenants"],"summary":"Create a tenant","description":"Creates an organization owned by the caller. Its slug is derived from\nthe name. It starts in BRL and São Paulo time, in the caller's language\n(`pt-BR` unless they use `en-US`); new stores inherit these. It also\nstarts a free trial of `plan_code` (14 days, no payment method) and its\nowner gets a welcome e-mail. Emits the `tenant.created` webhook.","operationId":"createTenant","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTenantRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden`: a store API token cannot create tenants; `account_disabled`: the account was deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`slug_taken`: a tenant with this name's slug exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty name or a plan not on sale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}":{"get":{"tags":["Tenants"],"summary":"Get a tenant","operationId":"getTenant","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Tenants"],"summary":"Update a tenant","description":"Fields left out stay as they are. Store defaults changed here apply to\nstores created afterwards.","operationId":"updateTenant","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTenantRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: unsupported currency or locale, or malformed feature flags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files":{"get":{"tags":["Files"],"summary":"List files","description":"Newest first.","operationId":"listFiles","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"folder_id","in":"query","description":"Only files in this folder.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"root_only","in":"query","description":"Only files at the root. Wins over `folder_id`.","required":false,"schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Matches part of the name, the original name, the MIME type, the\ndescription or a tag, case-insensitively.","required":false,"schema":{"type":"string"}},{"name":"file_type","in":"query","required":false,"schema":{"type":"string","description":"A family of MIME types.","enum":["image","video","document","archive"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_MediaFile"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/search":{"get":{"tags":["Files"],"summary":"Search files","description":"Across the tenant's library, newest first.","operationId":"searchFiles","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Matches part of the name, the original name, the MIME type, the\ndescription or a tag, case-insensitively.","required":false,"schema":{"type":"string"}},{"name":"folder_id","in":"query","description":"Only files in this folder.","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"file_type","in":"query","required":false,"schema":{"type":"string","description":"A family of MIME types.","enum":["image","video","document","archive"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_MediaFile"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/storage-summary":{"get":{"tags":["Files"],"summary":"Get the tenant's storage use","operationId":"getFileStorageSummary","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSummary"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/tree":{"get":{"tags":["Files"],"summary":"Get the file tree","description":"Every folder of the tenant, and every file with whether the current\nuser starred it and how many products use it.","operationId":"getFileTree","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include_files","in":"query","description":"Defaults to true.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFileTree"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/upload":{"post":{"tags":["Files"],"summary":"Upload a file","description":"`multipart/form-data` with the bytes in `file`. Images get resized JPEG\nand WebP renditions; everything else (videos, 3D models, documents) is\nstored as-is.","operationId":"uploadFile","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/MediaFileUploadForm"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFileUpload"}}}},"400":{"description":"`bad_request`: malformed multipart body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`folder_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"`file_too_large`: over 50 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`invalid_image`: an image that cannot be processed; `validation_failed`: no `file` part","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/{file_id}":{"delete":{"tags":["Files"],"summary":"Delete a file","description":"Removes the stored bytes and renditions. Product images copied from it\nare not affected.","operationId":"deleteFile","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file_id","in":"path","description":"File id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`file_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Files"],"summary":"Update a file","description":"Rename it, move it to another folder (`folder_id: null` for the root)\nor change its alt text.","operationId":"updateFile","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file_id","in":"path","description":"File id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFileUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFile"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`file_not_found`, `folder_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`: empty name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/{file_id}/connected-products":{"get":{"tags":["Files"],"summary":"List the products using a file","description":"Products whose gallery was made from this file, by title.","operationId":"listFileConnectedProducts","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file_id","in":"path","description":"File id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_ConnectedProduct"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`file_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/{file_id}/content/{variant}":{"get":{"tags":["Files"],"summary":"Get a file's content","description":"The bytes of a file in the organization's library, or one of its\nrenditions. Unlike the public `/files/{file_id}/{variant}` URL, this\nserves private files too, to signed-in members with `files.read`.\n`variant` is `original` or a rendition name such as `thumbnail_jpeg`.","operationId":"getFileContent","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file_id","in":"path","description":"File id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant","in":"path","description":"`original` or a rendition name such as `thumbnail_jpeg`","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file, with its own Content-Type","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such file or rendition in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/files/{file_id}/star":{"post":{"tags":["Files"],"summary":"Star a file","description":"For the current user. Idempotent.","operationId":"starFile","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file_id","in":"path","description":"File id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Starred"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`file_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Files"],"summary":"Unstar a file","description":"For the current user. Idempotent.","operationId":"unstarFile","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file_id","in":"path","description":"File id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Unstarred"},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/folders":{"post":{"tags":["Files"],"summary":"Create a folder","operationId":"createFolder","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFolderCreateRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFolder"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`folder_not_found`: the parent is not in this tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`folder_exists`: a folder with this name already exists there","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/folders/{folder_id}":{"patch":{"tags":["Files"],"summary":"Update a folder","description":"Renaming updates the paths of the folder and everything under it.","operationId":"updateFolder","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"folder_id","in":"path","description":"Folder id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFolderUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFolder"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`folder_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`folder_exists`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`validation_failed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/folders/{folder_id}/files":{"get":{"tags":["Files"],"summary":"List a folder's files","description":"By name.","operationId":"listFolderFiles","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"folder_id","in":"path","description":"Folder id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file_type","in":"query","required":false,"schema":{"type":"string","description":"A family of MIME types.","enum":["image","video","document","archive"]}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_MediaFile"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`folder_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/invoices":{"get":{"tags":["Billing"],"summary":"List invoices","description":"The organization's invoices, newest first. Voided invoices (replaced\nafter a plan change) are left out.","operationId":"listInvoices","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Invoice"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/subscription":{"get":{"tags":["Billing"],"summary":"Get the subscription","description":"The organization's plan, where the subscription stands (trial, active,\noverdue, suspended, canceled), the invoice waiting for payment and what\nthe organization uses against the plan's limits.","operationId":"getSubscription","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Billing"],"summary":"Change the plan","description":"Moves the organization to another plan or billing cycle, and takes back\na pending cancellation. During the trial the change is immediate and\nfree. On a paid subscription an upgrade is immediate (the new price is\ncharged from the next invoice) and a downgrade waits for the renewal.\nOpen invoices are issued again at the new price. A subscription that\nnever paid (a partner organization) moving to a paid plan gets its\nfirst invoice, due today. Owner only.","operationId":"changePlan","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePlanRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`owner_only`: only the organization's owner changes the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`usage_exceeds_plan`: the organization has more stores or seats than the plan allows; `details` has `limit`, `max` and `used`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`unknown_plan`: not a plan on sale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/subscription/cancel":{"post":{"tags":["Billing"],"summary":"Cancel the subscription","description":"The subscription ends when the paid period (or the trial) ends; nothing\nis charged after that. Data stays exportable for 90 days. Undo with\n`resumeSubscription` or by choosing a plan. Owner only.","operationId":"cancelSubscription","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`owner_only`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/subscription/pay":{"post":{"tags":["Billing"],"summary":"Pay the subscription","description":"The invoice to pay now, issued if there is none open: during the trial\nit pays for the period that starts when the trial ends (paying early\nnever shortens the trial); a suspended or canceled subscription restarts\ntoday. The invoice carries a Pix \"copia e cola\" and/or a payment page.\nOwner only.","operationId":"paySubscription","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`owner_only`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`nothing_to_pay`: the plan is free for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/tenants/{tenant_id}/subscription/resume":{"post":{"tags":["Billing"],"summary":"Resume the subscription","description":"Takes back a cancellation that has not taken effect yet. Owner only.","operationId":"resumeSubscription","parameters":[{"name":"tenant_id","in":"path","description":"Tenant id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`owner_only`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/users":{"get":{"tags":["Team"],"summary":"List users","description":"People who belong to the stores where the caller may read the team\n(`users.read`): members holding a role there and the store owners.\nOrdered by e-mail.","operationId":"listUsers","parameters":[{"name":"limit","in":"query","description":"Page size, 1 to 200. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int64","maximum":200,"minimum":1},"example":50},{"name":"cursor","in":"query","description":"`next_cursor` from the previous page. Omit for the first page.","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","description":"Rows to skip, for UIs that jump to a page number. Ignored when\n`cursor` is set. Prefer `cursor` for walking a whole list.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"include_total","in":"query","description":"Also return `total`, the count of all matching rows. Costs an extra\nquery; leave off when you only walk pages.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_User"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"AcceptInviteRequest":{"type":"object","required":["token","full_name","password"],"properties":{"device_name":{"type":["string","null"],"description":"See `LoginRequest.device_name`."},"full_name":{"type":"string","description":"Name for a new account. Ignored when the e-mail already has one."},"password":{"type":"string","description":"For a new account, its password (at least 8 characters). When the\ninvited e-mail already has an account, that account's password."},"token":{"type":"string","description":"The invite's `token`, from the acceptance link."}}},"AcceptInviteResponse":{"type":"object","required":["user_id","email","store_id"],"properties":{"email":{"type":"string"},"session":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Session","description":"The signed-in session. Absent when the account has two-factor\nsign-in enabled: the roles are granted, finish with\n`POST /auth/login`."}]},"store_id":{"type":"string","format":"uuid","description":"The store joined."},"token":{"type":["string","null"],"description":"Access token of `session`, for clients that predate sessions.\nAbsent when `session` is."},"user_id":{"type":"string","format":"uuid"}}},"ActorKind":{"type":"string","description":"Who performed an audited action.","enum":["user","assistant","system"]},"AdAudience":{"type":"object","description":"A segment mirrored to a Meta Custom Audience.","required":["id","segment_id","name","provider","status","auto_sync","last_count","created_at"],"properties":{"auto_sync":{"type":"boolean","description":"Re-synced about daily."},"created_at":{"type":"string","format":"date-time"},"external_id":{"type":["string","null"],"description":"The audience id on Meta, once created there."},"id":{"type":"string","format":"uuid"},"last_count":{"type":"integer","format":"int32","description":"Contacts sent in the last sync."},"last_error":{"type":["string","null"]},"last_synced_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"provider":{"type":"string","description":"`meta`."},"segment_id":{"type":"string","format":"uuid"},"segment_name":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/AdAudienceStatus"}}},"AdAudienceStatus":{"type":"string","description":"Sync state of an ad audience.","enum":["pending","syncing","ready","error"]},"AddDomainRequest":{"type":"object","required":["hostname"],"properties":{"hostname":{"type":"string","example":"loja.example.com.br"}}},"AddEmailDomainRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"e.g. `minhaloja.com.br` (scheme, `www.` and trailing slash are dropped)."}}},"AddEmailSuppressionRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string"}}},"AddWebhookEventsRequest":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"type":"string"},"description":"Event names to subscribe to. Already subscribed ones are ignored."}}},"AdjustReason":{"type":"string","description":"Why stock was adjusted by hand. A closed list so the history can be\ngrouped and reported on; put anything else in the free-text `note`.\n\n`opening_balance` (first load of a real shelf count), `damaged`, `lost`,\n`theft`, `found` (on the shelf but not in the book), `correction` (the\nbook was wrong; the default), `customer_return`, `supplier_return`,\n`expired`, `sample`, `other`.","enum":["opening_balance","damaged","lost","theft","found","correction","customer_return","supplier_return","expired","sample","other"]},"AdminRefundRequest":{"type":"object","description":"How much to refund.","properties":{"amount_cents":{"type":["integer","null"],"format":"int64","description":"Cents to return, at least 1. Omit to refund everything still\nrefundable on the payment."},"reason":{"type":["string","null"],"description":"Kept with the refund for the team; not sent to the customer."}}},"AdsConnection":{"type":"object","description":"Whether the store's ad accounts are connected.","required":["meta_configured"],"properties":{"meta_configured":{"type":"boolean","description":"A Meta ad account id and access token are set in the marketing\nsettings, so audiences can sync."}}},"AdsPerformance":{"type":"object","description":"Meta ad spend next to the revenue our attribution gives Meta.","required":["days","meta","attributed","all_orders"],"properties":{"all_orders":{"$ref":"#/components/schemas/OrdersTotal","description":"Every order in the window, for scale."},"attributed":{"$ref":"#/components/schemas/MetaAttributedOrders"},"days":{"type":"integer","format":"int64"},"meta":{"$ref":"#/components/schemas/MetaAdsInsights"},"roas":{"type":["number","null"],"format":"double","description":"Attributed revenue over spend; null without spend."}}},"AlertSubscription":{"type":"object","description":"A team member and the sale alerts they get on WhatsApp.","required":["user_id","email","has_phone","enabled_events","is_enabled"],"properties":{"email":{"type":"string"},"enabled_events":{"type":"array","items":{"$ref":"#/components/schemas/TeamAlertEvent"}},"has_phone":{"type":"boolean","description":"Whether the member has a phone in their profile. The number itself\nis never returned: a member must not see another's phone."},"is_enabled":{"type":"boolean"},"name":{"type":["string","null"]},"user_id":{"type":"string","format":"uuid"}}},"ApiTokenSummary":{"type":"object","description":"A store API token, without its secret.","required":["id","name","token_prefix","token_last4","user_id","store_id","scopes","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"last_used_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"},"description":"Permission codes the token may use; `[\"*\"]` = everything the user has."},"store_id":{"type":"string","format":"uuid"},"token_last4":{"type":"string"},"token_prefix":{"type":"string","description":"First characters of the token (`mobi_st_AbCd`), to recognize it."},"user_id":{"type":"string","format":"uuid","description":"The user the token acts as."}}},"AssignedShippingBox":{"type":"object","description":"A box assigned to a variant, with the box's name.","required":["id","box_id","box_name"],"properties":{"box_id":{"type":"string","format":"uuid"},"box_name":{"type":"string"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid","description":"The assignment id."},"is_primary":{"type":["boolean","null"]},"quantity":{"type":["integer","null"],"format":"int32"}}},"AssistantAction":{"type":"object","description":"A write the assistant applied after approval.","required":["id","tool_name","tool_input","status","approved_at"],"properties":{"after_state":{"type":["object","null"]},"approved_at":{"type":"string","format":"date-time"},"before_state":{"type":["object","null"],"description":"Snapshot taken before the write (what undo restores)."},"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/AssistantActionStatus"},"tool_input":{"type":"object"},"tool_name":{"type":"string"},"undone_at":{"type":["string","null"],"format":"date-time"}}},"AssistantActionStatus":{"type":"string","description":"State of an applied action.","enum":["approved","undone"]},"AssistantChannel":{"type":"string","description":"Where a conversation happened.","enum":["web","whatsapp"]},"AssistantChatRequest":{"type":"object","description":"A message to the assistant.","required":["message"],"properties":{"context":{"type":["object","null"],"description":"What the admin is looking at (page, selected order or product...),\ngiven to the model as context."},"conversation_id":{"type":["string","null"],"format":"uuid","description":"Continue this conversation (yours, in this store); omit or send an\nunknown id to start a new one."},"message":{"type":"string","description":"Not blank."}}},"AssistantConversation":{"type":"object","description":"One of your assistant conversations.","required":["id","channel","updated_at","message_count","pending_proposals"],"properties":{"channel":{"$ref":"#/components/schemas/AssistantChannel"},"id":{"type":"string","format":"uuid"},"message_count":{"type":"integer","format":"int64"},"pending_proposals":{"type":"integer","format":"int64","description":"Proposals waiting for a decision."},"title":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}},"AssistantConversationMessages":{"type":"object","description":"A conversation with its whole transcript.","required":["id","channel","messages","pending_proposals"],"properties":{"channel":{"$ref":"#/components/schemas/AssistantChannel"},"id":{"type":"string","format":"uuid"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AssistantMessage"},"description":"Every message, oldest first."},"pending_proposals":{"type":"array","items":{"$ref":"#/components/schemas/AssistantProposal"},"description":"Proposals still awaiting a decision, so a reload can render the cards."},"title":{"type":["string","null"]}}},"AssistantLinkedPhone":{"type":"object","description":"A phone linked (or being linked) to you for the assistant.","required":["phone_e164","store_id"],"properties":{"phone_e164":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"verified_at":{"type":["string","null"],"format":"date-time","description":"Null while the code has not been confirmed."}}},"AssistantMessage":{"type":"object","description":"A stored message, content as the model API has it.","required":["id","role","content","created_at"],"properties":{"content":{"type":"array","items":{"type":"object"},"description":"Content blocks: `{type: \"text\", text}`, `{type: \"tool_use\", id, name,\ninput}`, `{type: \"tool_result\", tool_use_id, content, is_error}`..."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"role":{"$ref":"#/components/schemas/AssistantMessageRole"}}},"AssistantMessageRole":{"type":"string","description":"Who wrote a message.","enum":["user","assistant"]},"AssistantPhoneVerification":{"type":"object","description":"A verification code was sent.","required":["phone_e164","expires_in_seconds"],"properties":{"expires_in_seconds":{"type":"integer","format":"int64","description":"The code expires after this long."},"phone_e164":{"type":"string","description":"The number as stored: digits only, with country code."}}},"AssistantPreferences":{"type":"object","description":"Store-wide assistant settings.","required":["store_id"],"properties":{"store_id":{"type":"string","format":"uuid"},"system_prompt_extra":{"type":["string","null"],"description":"Extra instructions added to every conversation of the store (tone,\npolicies, what to avoid)."}}},"AssistantProposal":{"type":"object","description":"A write waiting for the admin's decision.","required":["proposal_id","tool_use_id","tool_name","preview","expires_at"],"properties":{"expires_at":{"type":"string","format":"date-time"},"preview":{"type":"object","description":"What would change (tool-specific: before/after, the rows...)."},"proposal_id":{"type":"string","format":"uuid"},"tool_name":{"type":"string"},"tool_use_id":{"type":"string"}}},"AssistantUsage":{"type":"object","description":"The store's assistant use this month.","required":["year_month","input_tokens","output_tokens","messages","cap"],"properties":{"cap":{"type":"integer","format":"int32","description":"Messages allowed per month, set by the organization's plan."},"input_tokens":{"type":"integer","format":"int64"},"messages":{"type":"integer","format":"int32"},"output_tokens":{"type":"integer","format":"int64"},"year_month":{"type":"string","description":"`YYYY-MM`, UTC."}}},"AssociateFileRequest":{"type":"object","description":"Turn a file of the tenant's library into a product image.","required":["file_id"],"properties":{"alt_text":{"type":["string","null"]},"file_id":{"type":"string","format":"uuid","description":"A file of the store's tenant. Must be an image."},"image_kind":{"type":["string","null"],"description":"`gallery` (default) or `measurement`."},"position":{"type":["integer","null"],"format":"int32"},"product_variant_id":{"type":["string","null"],"format":"uuid"}}},"AttachNfeRequest":{"type":"object","description":"A nota fiscal for the order: the XML, a DANFE link, or both.","properties":{"danfe_url":{"type":["string","null"]},"xml":{"type":["string","null"],"description":"Raw NFe XML. Omit to attach only a DANFE link."}}},"AttachVideoRequest":{"type":"object","description":"Attach an external or library-hosted video to a product gallery by\nURL. The storefront renders it next to images. `provider` is\nauto-detected from the URL when omitted.","required":["url"],"properties":{"alt_text":{"type":["string","null"]},"position":{"type":["integer","null"],"format":"int32"},"poster_url":{"type":["string","null"]},"product_variant_id":{"type":["string","null"],"format":"uuid"},"provider":{"type":["string","null"],"description":"`upload`, `youtube`, `vimeo` or `external`."},"url":{"type":"string","description":"An `http(s)` URL: YouTube, Vimeo, or a video file."}}},"AttributedOrdersDay":{"type":"object","required":["day","orders","revenue_cents"],"properties":{"day":{"type":"string","format":"date"},"orders":{"type":"integer","format":"int64"},"revenue_cents":{"type":"integer","format":"int64"}}},"AttributionRow":{"type":"object","description":"Paid orders and revenue from one source / medium / campaign.","required":["orders","revenue_cents","capi_meta_sent","google_ads_sent"],"properties":{"campaign":{"type":["string","null"]},"capi_meta_sent":{"type":"integer","format":"int64","description":"Of `orders`, how many reached Meta through the Conversions API."},"google_ads_sent":{"type":"integer","format":"int64","description":"Of `orders`, how many were uploaded to Google Ads."},"medium":{"type":["string","null"]},"orders":{"type":"integer","format":"int64"},"revenue_cents":{"type":"integer","format":"int64"},"source":{"type":["string","null"],"description":"`utm_source` or the referrer-derived source; null when direct."}}},"AttributionTouch":{"type":"string","description":"Which touch of the visitor's journey an order is credited to.","enum":["first_touch","last_touch"]},"AuditEvent":{"type":"object","description":"One audited change.","required":["id","actor_kind","action","summary","meta","created_at"],"properties":{"action":{"type":"string","description":"Dotted action, e.g. `customers.merged`, `settings.updated`."},"actor_kind":{"$ref":"#/components/schemas/ActorKind"},"actor_name":{"type":["string","null"],"description":"The actor's name, or e-mail when they have no name."},"actor_user_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"meta":{"type":"object","description":"Action-specific details."},"subject_id":{"type":["string","null"]},"subject_type":{"type":["string","null"],"description":"Kind of record acted on, e.g. `customer`."},"summary":{"type":"string","description":"Human summary, in Portuguese."}}},"AutomaticDiscount":{"type":"object","description":"A store-wide discount rule the cart applies on its own, without a code.\n\nAt most one rule applies to a cart: among the active rules whose window,\nminimum subtotal and payment method match, the highest `priority` wins,\nthen the larger discount.","required":["id","store_id","name","kind","value_int","is_active","priority","created_at","updated_at"],"properties":{"condition_payment_method":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscountPaymentMethod","description":"Only applies when paying with this method; null for any method."}]},"created_at":{"type":"string","format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"kind":{"$ref":"#/components/schemas/AutomaticDiscountKind"},"min_subtotal_cents":{"type":["integer","null"],"format":"int64","description":"Only applies from this cart subtotal up."},"name":{"type":"string"},"priority":{"type":"integer","format":"int32","description":"Higher wins when several rules match."},"starts_at":{"type":["string","null"],"format":"date-time"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"value_int":{"type":"integer","format":"int32","description":"Whole percent for `percent_off`, cents for `fixed_off`."}}},"AutomaticDiscountCreateRequest":{"type":"object","description":"A new automatic discount.","required":["name","kind","value_int"],"properties":{"condition_payment_method":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscountPaymentMethod"}]},"ends_at":{"type":["string","null"],"format":"date-time"},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"kind":{"$ref":"#/components/schemas/AutomaticDiscountKind"},"min_subtotal_cents":{"type":["integer","null"],"format":"int64"},"name":{"type":"string"},"priority":{"type":["integer","null"],"format":"int32","description":"Defaults to 0."},"starts_at":{"type":["string","null"],"format":"date-time"},"value_int":{"type":"integer","format":"int32","description":"Whole percent (0 to 100) for `percent_off`, cents for `fixed_off`."}}},"AutomaticDiscountKind":{"type":"string","description":"How an automatic discount is computed: `percent_off` (`value_int` is a\nwhole percent, 0 to 100) or `fixed_off` (`value_int` is cents, capped at\nthe subtotal).","enum":["percent_off","fixed_off"]},"AutomaticDiscountUpdateRequest":{"type":"object","description":"Fields to change. Omitted fields keep their value; for the nullable ones\n(`condition_payment_method`, `min_subtotal_cents`, `starts_at`,\n`ends_at`) an explicit `null` clears them.","properties":{"condition_payment_method":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscountPaymentMethod"}]},"ends_at":{"type":["string","null"],"format":"date-time"},"is_active":{"type":["boolean","null"]},"kind":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AutomaticDiscountKind"}]},"min_subtotal_cents":{"type":["integer","null"],"format":"int64"},"name":{"type":["string","null"]},"priority":{"type":["integer","null"],"format":"int32"},"starts_at":{"type":["string","null"],"format":"date-time"},"value_int":{"type":["integer","null"],"format":"int32"}}},"BillingCycle":{"type":"string","description":"Monthly or annual billing.","enum":["monthly","annual"]},"BomLine":{"type":"object","description":"One line of a bill of materials, with the part's stock.","required":["component_variant_id","sku","name","product_name","quantity_required","on_hand","reserved","available"],"properties":{"available":{"type":"integer","format":"int32"},"component_variant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"on_hand":{"type":"integer","format":"int32"},"product_name":{"type":"string"},"quantity_required":{"type":"integer","format":"int32","description":"Units of the part per kit."},"reserved":{"type":"integer","format":"int32"},"sku":{"type":"string"}}},"BomLineRequest":{"type":"object","required":["component_variant_id","quantity_required"],"properties":{"component_variant_id":{"type":"string","format":"uuid","description":"The part: a variant of the same store."},"quantity_required":{"type":"integer","format":"int32","minimum":1}}},"BrandAliases":{"type":"object","properties":{"action_primary":{"type":"string","default":""},"action_primary_hover":{"type":"string","default":""},"action_primary_text":{"type":"string","default":""},"action_secondary":{"type":"string","default":""},"action_secondary_text":{"type":"string","default":""},"border":{"type":"string","default":""},"border_strong":{"type":"string","default":""},"error":{"type":"string","default":""},"link":{"type":"string","default":""},"sale":{"type":"string","default":""},"success":{"type":"string","default":""},"surface_card":{"type":"string","default":""},"surface_inverse":{"type":"string","default":""},"surface_muted":{"type":"string","default":""},"surface_page":{"type":"string","default":""},"text_body":{"type":"string","default":""},"text_caption":{"type":"string","default":""},"text_inverse":{"type":"string","default":""},"text_muted":{"type":"string","default":""},"text_strong":{"type":"string","default":""}}},"BrandAsset":{"type":"object","properties":{"kind":{"type":"string","default":""},"note":{"type":"string","default":""},"url":{"type":"string","default":""}}},"BrandAssetKind":{"type":"string","description":"What an uploaded brand asset is.","enum":["image","font"]},"BrandAssetUploadForm":{"type":"object","description":"A brand asset upload.","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file: an image (PNG, JPEG, WebP, GIF, SVG, AVIF) or a font\n(WOFF2, WOFF, OTF, TTF), up to 12 MB. The first part with a file\nname is used, whatever its field name."}}},"BrandAssets":{"type":"object","properties":{"favicon_url":{"type":["string","null"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/BrandAsset"},"default":[]},"logo_dark_url":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"logo_width":{"type":"integer","format":"int32","default":0,"minimum":0}}},"BrandAttachment":{"type":"object","description":"A text file handed to the generator.","required":["name","content"],"properties":{"content":{"type":"string"},"name":{"type":"string"}}},"BrandChange":{"type":"object","properties":{"at":{"type":"string","default":""},"prompt":{"type":"string","default":""},"summary":{"type":"string","default":""},"version":{"type":"integer","format":"int32","default":0,"minimum":0}}},"BrandColorScale":{"type":"object","properties":{"name":{"type":"string","default":""},"steps":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]}}},"BrandColors":{"type":"object","properties":{"accents":{"type":"array","items":{"$ref":"#/components/schemas/BrandSwatch"},"default":[]},"aliases":{"oneOf":[{"$ref":"#/components/schemas/BrandAliases"}],"default":{"action_primary":"","action_primary_hover":"","action_primary_text":"","action_secondary":"","action_secondary_text":"","border":"","border_strong":"","error":"","link":"","sale":"","success":"","surface_card":"","surface_inverse":"","surface_muted":"","surface_page":"","text_body":"","text_caption":"","text_inverse":"","text_muted":"","text_strong":""}},"brand":{"type":"array","items":{"$ref":"#/components/schemas/BrandSwatch"},"default":[]},"rules":{"type":"array","items":{"type":"string"},"default":[]},"scales":{"type":"array","items":{"$ref":"#/components/schemas/BrandColorScale"},"default":[]},"semantic":{"type":"array","items":{"$ref":"#/components/schemas/BrandSwatch"},"default":[]}}},"BrandComponentSpec":{"type":"object","properties":{"description":{"type":"string","default":""},"name":{"type":"string","default":""},"rules":{"type":"array","items":{"type":"string"},"default":[]},"tokens":{"type":"object","default":{},"additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}}}},"BrandEffects":{"type":"object","properties":{"borders":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"durations":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"easing":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"rings":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"rules":{"type":"array","items":{"type":"string"},"default":[]},"shadows":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]}}},"BrandEmailPrefs":{"type":"object","properties":{"button_shape":{"type":"string","description":"`rounded` (uses radii md), `pill`, `square`.","default":"rounded"},"width":{"type":"integer","format":"int32","default":600,"minimum":0}}},"BrandFamily":{"type":"object","properties":{"google_family":{"type":["string","null"]},"name":{"type":"string","default":""},"role":{"type":"string","description":"`display`, `body`, `logo`, `mono`.","default":""},"stack":{"type":"string","description":"CSS stack with fallbacks, e-mail safe.","default":""},"substitute_for":{"type":["string","null"],"description":"The licensed face this one stands in for, when the real one is not available."},"usage":{"type":"string","default":""},"weights":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"default":[]}}},"BrandFontSource":{"type":"object","description":"Where a web font comes from. `google` (family name), `adobe` (Typekit kit id or kit CSS\nURL), `url` (a stylesheet URL), `file` (a hosted font file URL, needs `family`).","properties":{"family":{"type":"string","default":""},"kind":{"type":"string","default":""},"note":{"type":"string","default":""},"value":{"type":"string","default":""}}},"BrandFooter":{"type":"object","properties":{"address":{"type":"string","default":""},"company":{"type":"string","default":""},"extra":{"type":"string","default":""},"social":{"type":"array","items":{"$ref":"#/components/schemas/BrandSocialLink"},"default":[]}}},"BrandIconography":{"type":"object","properties":{"glyphs":{"type":"array","items":{"type":"string"},"default":[]},"notes":{"type":"string","default":""},"set":{"type":"string","default":""},"stroke":{"type":"string","default":""}}},"BrandIdentity":{"type":"object","properties":{"audience":{"type":"string","default":""},"name":{"type":"string","default":""},"origin":{"type":"string","default":""},"since":{"type":"string","default":""},"story":{"type":"string","default":""},"tagline":{"type":"string","default":""},"values":{"type":"array","items":{"type":"string"},"default":[]},"wordmark":{"type":"string","default":""},"wordmark_rules":{"type":"string","default":""}}},"BrandImagery":{"type":"object","properties":{"avoid":{"type":"array","items":{"type":"string"},"default":[]},"frame_radius":{"type":"string","default":""},"style":{"type":"string","default":""},"subjects":{"type":"array","items":{"type":"string"},"default":[]},"treatment":{"type":"array","items":{"type":"string"},"default":[]}}},"BrandImportForm":{"type":"object","description":"A design-system package upload.","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The `.zip` package (up to 40 MB): tokens, CSS, guides, images and\nfonts, in any layout."}}},"BrandJob":{"type":"object","description":"A background brand job (generation, revision or import). Jobs live in\nmemory for an hour after they start; a server restart loses them (the\nsaved versions are the durable record).","required":["id","store_id","kind","status","stage","started_at"],"properties":{"error":{"type":["string","null"],"description":"When `failed`: what went wrong."},"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/BrandJobKind"},"result":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BrandSystemSaved","description":"When `done`: the saved system, as `BrandSystemSaved`, plus\nkind-specific extras (`evidence` for generate, `imported_files` and\n`skipped` for import, `summary` for revise)."}]},"stage":{"type":"string","description":"Human-readable progress (Portuguese), e.g. \"salvando a nova versão\"."},"started_at":{"type":"string","format":"date-time"},"status":{"$ref":"#/components/schemas/BrandJobStatus"},"store_id":{"type":"string","format":"uuid"}}},"BrandJobKind":{"type":"string","description":"What a brand job does.","enum":["generate","revise","import"]},"BrandJobStarted":{"type":"object","description":"A background job was started (or one was already running).","required":["job_id"],"properties":{"already_running":{"type":"boolean","description":"The store already had a job running; this is its id and nothing new\nwas started."},"job_id":{"type":"string","format":"uuid","description":"Poll `getBrandJob` with it."}}},"BrandJobStatus":{"type":"string","enum":["running","done","failed"]},"BrandPackageFile":{"type":"string","format":"binary","description":"A `.zip` design-system package."},"BrandRule":{"type":"object","properties":{"example":{"type":"string","default":""},"name":{"type":"string","default":""},"rule":{"type":"string","default":""}}},"BrandSocialLink":{"type":"object","properties":{"kind":{"type":"string","default":""},"url":{"type":"string","default":""}}},"BrandSpacing":{"type":"object","properties":{"base_px":{"type":"integer","format":"int32","default":0,"minimum":0},"container_max":{"type":"string","default":""},"gutters":{"type":"string","default":""},"rules":{"type":"array","items":{"type":"string"},"default":[]},"scale":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]}}},"BrandSwatch":{"type":"object","properties":{"hex":{"type":"string","default":""},"name":{"type":"string","default":""},"role":{"type":"string","default":""},"usage":{"type":"string","default":""}}},"BrandSystem":{"type":"object","description":"The store's design system. Responses carry every field; in requests\nevery field is optional (missing ones take their defaults) and values\nare read leniently (`\"16px\"` for a number, a string for a list).","properties":{"assets":{"oneOf":[{"$ref":"#/components/schemas/BrandAssets"}],"default":{"favicon_url":null,"images":[],"logo_dark_url":null,"logo_url":null,"logo_width":0}},"changelog":{"type":"array","items":{"$ref":"#/components/schemas/BrandChange"},"default":[]},"colors":{"oneOf":[{"$ref":"#/components/schemas/BrandColors"}],"default":{"accents":[],"aliases":{"action_primary":"","action_primary_hover":"","action_primary_text":"","action_secondary":"","action_secondary_text":"","border":"","border_strong":"","error":"","link":"","sale":"","success":"","surface_card":"","surface_inverse":"","surface_muted":"","surface_page":"","text_body":"","text_caption":"","text_inverse":"","text_muted":"","text_strong":""},"brand":[],"rules":[],"scales":[],"semantic":[]}},"components":{"type":"array","items":{"$ref":"#/components/schemas/BrandComponentSpec"},"default":[]},"effects":{"oneOf":[{"$ref":"#/components/schemas/BrandEffects"}],"default":{"borders":[],"durations":[],"easing":[],"rings":[],"rules":[],"shadows":[]}},"email":{"oneOf":[{"$ref":"#/components/schemas/BrandEmailPrefs"}],"default":{"button_shape":"rounded","width":600}},"footer":{"oneOf":[{"$ref":"#/components/schemas/BrandFooter"}],"default":{"address":"","company":"","extra":"","social":[]}},"guide_md":{"type":"string","description":"The narrative guide (markdown): what a designer or an agent reads first.","default":""},"iconography":{"oneOf":[{"$ref":"#/components/schemas/BrandIconography"}],"default":{"glyphs":[],"notes":"","set":"","stroke":""}},"identity":{"oneOf":[{"$ref":"#/components/schemas/BrandIdentity"}],"default":{"audience":"","name":"","origin":"","since":"","story":"","tagline":"","values":[],"wordmark":"","wordmark_rules":""}},"imagery":{"oneOf":[{"$ref":"#/components/schemas/BrandImagery"}],"default":{"avoid":[],"frame_radius":"","style":"","subjects":[],"treatment":[]}},"open_questions":{"type":"array","items":{"type":"string"},"default":[]},"radii":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"schema_version":{"type":"integer","format":"int32","default":0,"minimum":0},"sources":{"type":"array","items":{"type":"string"},"default":[]},"spacing":{"oneOf":[{"$ref":"#/components/schemas/BrandSpacing"}],"default":{"base_px":0,"container_max":"","gutters":"","rules":[],"scale":[]}},"typography":{"oneOf":[{"$ref":"#/components/schemas/BrandTypography"}],"default":{"base_size_px":0,"families":[],"font_sources":[],"heading_transform":"","heading_weight":0,"leading":[],"rules":[],"scale":[],"tracking":[],"weights":[]}},"updated_at":{"type":"string","default":""},"voice":{"oneOf":[{"$ref":"#/components/schemas/BrandVoice"}],"default":{"casing":[],"conventions":[],"do":[],"dont":[],"emoji":false,"language":"","person":"","sample_copy":[],"signoff":"","tone":[]}}}},"BrandSystemSaved":{"type":"object","description":"A saved brand system version.","required":["system","version","versions"],"properties":{"system":{"$ref":"#/components/schemas/BrandSystem"},"version":{"type":"integer","format":"int32","description":"The version just saved.","minimum":0},"versions":{"type":"array","items":{"$ref":"#/components/schemas/BrandSystemVersion"},"description":"The 60 most recent versions, newest first."}}},"BrandSystemState":{"type":"object","description":"The store's brand system and its history.","required":["versions","assistant_available"],"properties":{"active_job":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BrandJob","description":"A generation, revision or import still running for the store."}]},"assistant_available":{"type":"boolean","description":"Whether AI generation and revision are available on this server."},"system":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BrandSystem","description":"Null until the system is first generated or saved."}]},"versions":{"type":"array","items":{"$ref":"#/components/schemas/BrandSystemVersion"},"description":"The 60 most recent versions, newest first."}}},"BrandSystemVersion":{"type":"object","description":"One saved version of the brand system.","required":["version","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"prompt":{"type":["string","null"],"description":"The instruction the change was made from, for AI edits."},"summary":{"type":["string","null"],"description":"What changed."},"version":{"type":"integer","format":"int32"}}},"BrandSystemVersionDetail":{"type":"object","description":"A past version of the brand system.","required":["system","version"],"properties":{"system":{"$ref":"#/components/schemas/BrandSystem"},"version":{"type":"integer","format":"int32"}}},"BrandToken":{"type":"object","properties":{"key":{"type":"string","default":""},"note":{"type":"string","default":""},"value":{"type":"string","default":""}}},"BrandTypography":{"type":"object","properties":{"base_size_px":{"type":"integer","format":"int32","default":0,"minimum":0},"families":{"type":"array","items":{"$ref":"#/components/schemas/BrandFamily"},"default":[]},"font_sources":{"type":"array","items":{"$ref":"#/components/schemas/BrandFontSource"},"default":[]},"heading_transform":{"type":"string","description":"`none` or `uppercase`.","default":""},"heading_weight":{"type":"integer","format":"int32","default":0,"minimum":0},"leading":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"rules":{"type":"array","items":{"type":"string"},"default":[]},"scale":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"tracking":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]},"weights":{"type":"array","items":{"$ref":"#/components/schemas/BrandToken"},"default":[]}}},"BrandVoice":{"type":"object","properties":{"casing":{"type":"array","items":{"$ref":"#/components/schemas/BrandRule"},"default":[]},"conventions":{"type":"array","items":{"$ref":"#/components/schemas/BrandRule"},"default":[]},"do":{"type":"array","items":{"type":"string"},"default":[]},"dont":{"type":"array","items":{"type":"string"},"default":[]},"emoji":{"type":"boolean","default":false},"language":{"type":"string","default":""},"person":{"type":"string","default":""},"sample_copy":{"type":"array","items":{"type":"string"},"default":[]},"signoff":{"type":"string","default":""},"tone":{"type":"array","items":{"type":"string"},"default":[]}}},"BuildJob":{"type":"object","description":"A production job for an order line.","required":["id","store_id","order_id","order_item_id","product_id","variant_id","quantity","status","requested_at","created_at","updated_at","components"],"properties":{"cancelled_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"components":{"type":"array","items":{"$ref":"#/components/schemas/BuildJobComponent"},"description":"Live bill-of-materials readiness: what each line needs, what this job\nholds, what is still on the shelf, and what is short. Empty for a\nvariant with no bill of materials."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"lead_time_days":{"type":["integer","null"],"format":"int32","description":"The variant's configured lead time, to prefill a start. The batch's\nown promise is `target_ready_at`."},"metadata_json":{"type":["object","null"]},"notes":{"type":["string","null"]},"order_id":{"type":"string","format":"uuid"},"order_item_id":{"type":"string","format":"uuid"},"order_number":{"type":["string","null"]},"product_id":{"type":"string","format":"uuid"},"product_title":{"type":["string","null"]},"quantity":{"type":"integer","format":"int32"},"requested_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/BuildJobStatus"},"store_id":{"type":"string","format":"uuid"},"target_ready_at":{"type":["string","null"],"format":"date-time","description":"When the batch is promised ready."},"updated_at":{"type":"string","format":"date-time"},"variant_id":{"type":"string","format":"uuid"},"variant_sku":{"type":["string","null"]},"variant_title":{"type":["string","null"]}}},"BuildJobComponent":{"type":"object","description":"One bill-of-materials line of a job: what the job needs of a part.","required":["component_variant_id","required","reserved","available","missing"],"properties":{"available":{"type":"integer","format":"int32","description":"Units still free on the shelf (every reservation excluded)."},"component_variant_id":{"type":"string","format":"uuid"},"missing":{"type":"integer","format":"int32","description":"`required - reserved - available`, floored at zero."},"name":{"type":["string","null"]},"required":{"type":"integer","format":"int32","description":"Units the whole job needs."},"reserved":{"type":"integer","format":"int32","description":"Units reserved for this job."},"sku":{"type":["string","null"]}}},"BuildJobStartRequest":{"type":"object","required":["quantity"],"properties":{"lead_time_days":{"type":["integer","null"],"format":"int32","description":"Days from now the batch is expected ready; sets `target_ready_at`.\nOmitted keeps the job's target."},"quantity":{"type":"integer","format":"int32","description":"Units moving to the bench, 1 to the job quantity. Less than the job\nquantity splits it: the remainder stays queued.","minimum":1}}},"BuildJobStatus":{"type":"string","enum":["queued","in_progress","ready","cancelled"]},"BuildJobUpdateRequest":{"type":"object","properties":{"notes":{"type":["string","null"]},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BuildJobStatus","description":"Moving to `in_progress`, `ready` or `cancelled` stamps the matching\ntime; back to `queued` clears them."}]},"target_ready_at":{"type":["string","null"],"format":"date-time"}}},"BulkReorderRequest":{"type":"object","required":["variant_ids"],"properties":{"reorder_point":{"type":["integer","null"],"format":"int32","description":"Null clears.","minimum":0},"reorder_quantity":{"type":["integer","null"],"format":"int32","description":"Null clears.","minimum":1},"variant_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"BulkReorderResult":{"type":"object","required":["updated"],"properties":{"updated":{"type":"integer","format":"int64","description":"Variants of this store that were updated; ids of other stores are\nskipped.","minimum":0}}},"BulkStockAdjustItem":{"type":"object","description":"One line of a bulk adjustment: exactly one of `delta` and `set_to`.","required":["variant_id"],"properties":{"delta":{"type":["integer","null"],"format":"int32"},"set_to":{"type":["integer","null"],"format":"int32","minimum":0},"variant_id":{"type":"string","format":"uuid"}}},"BulkStockAdjustRequest":{"type":"object","required":["items"],"properties":{"force":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BulkStockAdjustItem"},"description":"1 to 500 lines."},"location_id":{"type":["string","null"],"format":"uuid","description":"Defaults to the store's default location."},"note":{"type":["string","null"]},"reason":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdjustReason","description":"Applies to every line. Defaults to `correction`."}]}}},"BulkStockAdjustResult":{"type":"object","required":["applied","levels"],"properties":{"applied":{"type":"integer","description":"Lines processed.","minimum":0},"levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevelChange"},"description":"The new levels, one per line, in request order."}}},"CampaignHit":{"type":"object","required":["id","name","subject","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"subject":{"type":"string"}}},"CancelShipmentRequest":{"type":"object","description":"Why a carrier order is cancelled.","required":["reason"],"properties":{"reason":{"type":"integer","format":"int64","description":"An `id` from `GET /stores/{store_id}/freight/cancel-reasons`."}}},"CannedReply":{"type":"object","description":"A saved answer the composer inserts with `/shortcut`.","required":["id","shortcut","title","body","updated_at"],"properties":{"body":{"type":"string","description":"The text. `{first_name}`, `{name}`, `{store}`, `{agent}` and\n`{order}` are filled in by the client."},"id":{"type":"string","format":"uuid"},"shortcut":{"type":"string","description":"Lowercase, letters, digits, `_` and `-`, without the slash."},"title":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"CannedReplyInput":{"type":"object","required":["shortcut","body"],"properties":{"body":{"type":"string"},"shortcut":{"type":"string","description":"Leading `/` and other characters are dropped; lowercased."},"title":{"type":"string"}}},"Capability":{"type":"object","required":["key","name","question","description","selection","onboarding","modules"],"properties":{"description":{"type":"string"},"key":{"type":"string"},"modules":{"type":"array","items":{"$ref":"#/components/schemas/CapabilityModule"}},"name":{"type":"string"},"onboarding":{"type":"boolean","description":"Shown in the first-run wizard (vs settings-hub-only capabilities)."},"question":{"type":"string","description":"The onboarding question, e.g. \"Como você quer gerenciar seu estoque?\"."},"selection":{"$ref":"#/components/schemas/SelectionMode"}}},"CapabilityModule":{"type":"object","required":["code","name","description","kind","available","needs_setup","connect","icon","accent"],"properties":{"accent":{"type":"string","description":"Accent colour token (`stone`, `emerald`, `sky`, `orange`, `indigo`,\n`teal`, `violet`, `amber`)."},"available":{"type":"boolean","description":"True once the module's backend is wired; false = \"em breve\"."},"code":{"type":"string"},"connect":{"$ref":"#/components/schemas/ConnectSpec","description":"How this module is connected and where its config lives. This is what\nlets the admin render any integration without knowing what it is."},"description":{"type":"string"},"icon":{"type":"string","description":"Icon name from a fixed vocabulary the admin knows how to draw\n(`warehouse`, `boxes`, `credit-card`, `landmark`, `truck`, `store`,\n`map-pin`, `plug`). A new module picks an existing name rather than\nshipping an asset, so it looks right without a frontend change."},"kind":{"$ref":"#/components/schemas/ModuleKind"},"name":{"type":"string"},"needs_setup":{"type":"boolean","description":"Whether picking this module needs a follow-up configuration step\n(an integration to connect). Native modules are usually self-contained."}}},"CapabilitySelections":{"type":"object","description":"What the store runs today, per capability.","required":["inventory","payments","freight"],"properties":{"freight":{"type":"array","items":{"type":"string"},"description":"Active freight modules: carrier provider codes, plus `pickup` and\n`local_delivery` when those are set up."},"inventory":{"type":"string","description":"The active inventory module code (`mobi` or `tiny`)."},"payments":{"type":"array","items":{"type":"string"},"description":"Codes of the active payment providers."}}},"CartCustomerType":{"type":"string","description":"Whether the cart's shopper matched a customer on file (`existing`) or\nnot yet (`new`).","enum":["existing","new"]},"CartDetail":{"allOf":[{"$ref":"#/components/schemas/CartSummary"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CartItem"}}}}],"description":"A cart with its lines."},"CartItem":{"type":"object","description":"One line of a cart.","required":["id","cart_id","product_id","variant_id","title","quantity","unit_price_cents","total_cents"],"properties":{"cart_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","format":"int32"},"sku":{"type":["string","null"]},"title":{"type":"string"},"total_cents":{"type":"integer","format":"int64"},"unit_price_cents":{"type":"integer","format":"int64"},"variant_id":{"type":"string","format":"uuid"}}},"CartKind":{"type":"string","description":"`storefront` (a shopper's cart) or `quote` (built at the counter and\nshared as a link; see Quotes).","enum":["storefront","quote"]},"CartStatus":{"type":"string","description":"`open` (being filled), `abandoned` (no activity for a while; recovery\nmessages go out) or `converted` (became an order).","enum":["open","abandoned","converted"]},"CartSummary":{"type":"object","description":"A cart as the admin sees it: totals, and who the shopper is, from the\ncustomer on file or the contact details typed at checkout (`lead_*`).","required":["id","store_id","customer_type","status","kind","item_count","subtotal_cents","tax_cents","shipping_cents","discount_cents","total_cents","currency","created_at","updated_at","last_activity_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"customer_email":{"type":["string","null"],"description":"The customer's e-mail, or the one typed at checkout."},"customer_id":{"type":["string","null"],"format":"uuid"},"customer_name":{"type":["string","null"],"description":"The customer's name, or the one typed at checkout."},"customer_type":{"$ref":"#/components/schemas/CartCustomerType"},"discount_cents":{"type":"integer","format":"int64"},"id":{"type":"string","format":"uuid"},"identified_customer_id":{"type":["string","null"],"format":"uuid","description":"The cart's customer, or the one its contact details matched."},"item_count":{"type":"integer","format":"int32"},"kind":{"$ref":"#/components/schemas/CartKind"},"last_activity_at":{"type":"string","format":"date-time"},"lead_city":{"type":["string","null"]},"lead_email":{"type":["string","null"]},"lead_name":{"type":["string","null"]},"lead_phone":{"type":["string","null"]},"lead_state":{"type":["string","null"]},"lead_zip_code":{"type":["string","null"]},"shipping_cents":{"type":"integer","format":"int64"},"status":{"$ref":"#/components/schemas/CartStatus"},"store_id":{"type":"string","format":"uuid"},"subtotal_cents":{"type":"integer","format":"int64"},"tax_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogEntry":{"type":"object","description":"An event the platform emits.","required":["name","label","entity","group","payload_keys"],"properties":{"entity":{"type":"string","description":"Resource the event is about (`order`, `customer`, ...)."},"group":{"type":"string","description":"Group for pickers."},"label":{"type":"string","description":"Human label, pt-BR."},"name":{"type":"string","description":"The wire name, e.g. `orders.paid`."},"payload_keys":{"type":"array","items":{"type":"string"},"description":"Keys the payload carries (`trigger.<key>` in workflows)."},"subscribers":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Subscribers","description":"Present when `store_id` was given."}]}}},"CatalogResponse":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEntry"},"description":"Every event, in catalog order. A fixed list that grows with\nreleases; tolerate unknown names."}}},"Category":{"type":"object","description":"A product category. Categories form a tree through `parent_id`.","required":["id","store_id","name","slug","is_active","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"name":{"type":"string"},"parent_id":{"type":["string","null"],"format":"uuid","description":"Null for a top-level category."},"slug":{"type":"string","description":"Derived from the name."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"CategoryCreateRequest":{"type":"object","description":"A new category.","required":["name"],"properties":{"description":{"type":["string","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"name":{"type":"string"},"parent_id":{"type":["string","null"],"format":"uuid","description":"A category of the same store; omit for a top-level one."}}},"CategoryUpdateRequest":{"type":"object","description":"Fields to change. Omitted fields keep their value; an explicit `null`\nclears `description` or makes the category top-level (`parent_id`).","properties":{"description":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"name":{"type":["string","null"]},"parent_id":{"type":["string","null"],"format":"uuid"}}},"ChangePasswordRequest":{"type":"object","required":["current_password","new_password"],"properties":{"current_password":{"type":"string"},"new_password":{"type":"string","description":"At least 8 characters."}}},"ChangePlanRequest":{"type":"object","required":["plan_code","billing_cycle"],"properties":{"billing_cycle":{"$ref":"#/components/schemas/BillingCycle"},"plan_code":{"type":"string","description":"A plan from `GET /billing/plans`.","example":"profissional"}}},"Channels":{"type":"object","required":["email","whatsapp","storefront"],"properties":{"email":{"$ref":"#/components/schemas/EmailChannel"},"storefront":{"$ref":"#/components/schemas/StorefrontChannel"},"whatsapp":{"$ref":"#/components/schemas/WhatsappChannel"}}},"CmsCollection":{"type":"object","description":"A kind of content, with the schema its documents follow.","required":["id","store_id","slug","name","schema_json","is_archived","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_archived":{"type":"boolean"},"name":{"type":"string"},"schema_json":{"type":"object","description":"Field definitions for the documents' `data`."},"slug":{"type":"string","description":"Key themes use: `cms.<slug>`."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"CmsDocument":{"type":"object","description":"One entry of a collection.","required":["id","collection_id","store_id","data","position","is_active","created_at","updated_at"],"properties":{"collection_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","description":"The document's fields, shaped by the collection's `schema_json`."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean","description":"Inactive documents are hidden from the storefront."},"position":{"type":"integer","format":"int32","description":"Order within the collection; lower first."},"slug":{"type":["string","null"]},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"Collection":{"type":"object","description":"A curated list of products.","required":["id","store_id","name","slug","is_active","product_count","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"name":{"type":"string"},"product_count":{"type":"integer","format":"int64","description":"Products in the collection."},"slug":{"type":"string","description":"Derived from the name."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"CollectionCreateRequest":{"type":"object","description":"A new collection.","required":["name"],"properties":{"description":{"type":["string","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"name":{"type":"string"}}},"CollectionProductEntry":{"type":"object","description":"A product in a collection.","required":["product_id","title"],"properties":{"position":{"type":["integer","null"],"format":"int32"},"product_id":{"type":"string","format":"uuid"},"title":{"type":"string"}}},"CollectionProductRequest":{"type":"object","description":"A product and a collection of the same store.","required":["product_id","collection_id"],"properties":{"collection_id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"}}},"CollectionRef":{"type":"object","description":"Lightweight collection reference for the picker. We don't ship the\nfull `Collection` shape (image, sales channels, …) since the spec\neditor only needs a label + handle.","required":["id","title","handle"],"properties":{"handle":{"type":"string"},"id":{"type":"string","format":"uuid"},"title":{"type":"string"}}},"CollectionUpdateRequest":{"type":"object","description":"Fields to change. Omitted fields keep their value; an explicit `null`\nclears `description`.","properties":{"description":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"name":{"type":["string","null"]}}},"CompleteAssistantPhoneVerificationRequest":{"type":"object","required":["phone_e164","code"],"properties":{"code":{"type":"string","description":"The 6-digit code received on WhatsApp."},"phone_e164":{"type":"string"}}},"Component":{"type":"object","description":"A part some kit is built from, with its stock and open build demand.","required":["variant_id","product_id","sku","name","product_name","product_status","is_active","allow_backorder","on_hand","reserved","available","used_in_kits","required_open","shortfall"],"properties":{"allow_backorder":{"type":"boolean","description":"Whether kits may sell with this part missing (it can be purchased)."},"available":{"type":"integer","format":"int32"},"cost_cents":{"type":["integer","null"],"format":"int64"},"height_cm":{"type":["number","null"],"format":"double"},"is_active":{"type":"boolean"},"length_cm":{"type":["number","null"],"format":"double"},"name":{"type":"string"},"on_hand":{"type":"integer","format":"int32"},"product_id":{"type":"string","format":"uuid"},"product_name":{"type":"string"},"product_status":{"type":"string","description":"The product's status; parts created here start as `draft`."},"reorder_point":{"type":["integer","null"],"format":"int32"},"required_open":{"type":"integer","format":"int32","description":"Units this part still owes to queued or running build jobs."},"reserved":{"type":"integer","format":"int32"},"shortfall":{"type":"integer","format":"int32","description":"`required_open - available`, floored at zero."},"sku":{"type":"string"},"used_in_kits":{"type":"integer","format":"int32","description":"Distinct kit variants that list this part."},"variant_id":{"type":"string","format":"uuid"},"weight_grams":{"type":["integer","null"],"format":"int32"},"width_cm":{"type":["number","null"],"format":"double"}}},"ComponentCandidate":{"type":"object","description":"A variant that can be picked as a part.","required":["variant_id","sku","name","product_name","available","is_component"],"properties":{"available":{"type":"integer","format":"int32"},"is_component":{"type":"boolean","description":"Already a part of at least one kit."},"name":{"type":"string"},"product_name":{"type":"string"},"sku":{"type":"string"},"variant_id":{"type":"string","format":"uuid"}}},"ComponentCreateRequest":{"type":"object","required":["name","sku"],"properties":{"allow_backorder":{"type":["boolean","null"],"description":"Defaults to true."},"cost_cents":{"type":["integer","null"],"format":"int64"},"height_cm":{"type":["number","null"],"format":"double"},"initial_on_hand":{"type":["integer","null"],"format":"int32","description":"Opening stock, so a part can be created and counted in one go.","minimum":0},"length_cm":{"type":["number","null"],"format":"double"},"location_id":{"type":["string","null"],"format":"uuid","description":"Location for `initial_on_hand`."},"name":{"type":"string"},"reorder_point":{"type":["integer","null"],"format":"int32"},"reorder_quantity":{"type":["integer","null"],"format":"int32"},"sku":{"type":"string","description":"Unique in the store across every variant."},"weight_grams":{"type":["integer","null"],"format":"int32"},"width_cm":{"type":["number","null"],"format":"double"}}},"ComponentUpdateRequest":{"type":"object","description":"Fields to change; omitted ones stay. The measurements, cost and reorder\nfields accept null to clear.","properties":{"allow_backorder":{"type":["boolean","null"]},"cost_cents":{"type":["integer","null"],"format":"int64"},"height_cm":{"type":["number","null"],"format":"double"},"length_cm":{"type":["number","null"],"format":"double"},"name":{"type":["string","null"]},"reorder_point":{"type":["integer","null"],"format":"int32"},"reorder_quantity":{"type":["integer","null"],"format":"int32"},"sku":{"type":["string","null"]},"weight_grams":{"type":["integer","null"],"format":"int32"},"width_cm":{"type":["number","null"],"format":"double"}}},"ComponentUsage":{"type":"object","description":"A kit that lists the part.","required":["kit_variant_id","kit_product_id","kit_name","kit_product_name","kit_sku","quantity_required","required_open"],"properties":{"kit_name":{"type":"string"},"kit_product_id":{"type":"string","format":"uuid"},"kit_product_name":{"type":"string"},"kit_sku":{"type":"string"},"kit_variant_id":{"type":"string","format":"uuid"},"quantity_required":{"type":"integer","format":"int32"},"required_open":{"type":"integer","format":"int32","description":"Units of this part owed to that kit's open build jobs."}}},"ConfirmWhatsappSetupRequest":{"type":"object","required":["phone","code"],"properties":{"code":{"type":"string","example":"123456"},"phone":{"type":"string","description":"The same phone passed to `start-setup`."}}},"ConnectKind":{"type":"string","enum":["managed","form","oauth"]},"ConnectSpec":{"type":"object","description":"How a module is connected, plus where its configuration is stored.","required":["kind"],"properties":{"docs_url":{"type":["string","null"],"description":"Vendor documentation for obtaining the credentials above."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/ModuleField"}},"kind":{"$ref":"#/components/schemas/ConnectKind"},"provider_api":{"type":["string","null"],"description":"The REST collection holding this module's provider rows, relative to\n`/stores/{store_id}` — e.g. `payment-providers`. The admin uses this to\nsave any module's config without knowing what the module is. `None` for\nnative modules that own their own storage."},"provider_code":{"type":["string","null"],"description":"The value stored in the provider row's `code` column, when it differs\nfrom the module code (the inventory module `tiny` is stored as\n`tiny_erp`). Resolve with [`ConnectSpec::provider_code_or`]."},"webhook_path":{"type":["string","null"],"description":"Callback URL the merchant registers with the provider, as a template\nover `{store_slug}` and `{provider_code}`. Declared here so a new\ngateway documents its own callback instead of the admin hardcoding a\npath per provider."}}},"ConnectedProduct":{"type":"object","description":"A product whose gallery uses a file.","required":["product_id","product_title","product_slug"],"properties":{"image_kind":{"type":["string","null"],"description":"`gallery` or `measurement`."},"product_id":{"type":"string","format":"uuid"},"product_slug":{"type":"string"},"product_title":{"type":"string"},"product_variant_id":{"type":["string","null"],"format":"uuid","description":"Set when the image belongs to one variant."},"variant_title":{"type":["string","null"]}}},"ConsentChannel":{"type":"string","enum":["email","whatsapp"]},"ConsentEntry":{"type":"object","description":"One entry of the append-only consent ledger.","required":["channel","status","at"],"properties":{"at":{"type":"string","format":"date-time"},"channel":{"type":"string","description":"`email` or `whatsapp`."},"evidence":{"type":["object","null"]},"source":{"type":["string","null"]},"status":{"type":"string","description":"`granted` or `revoked`."}}},"ConsentReq":{"type":"object","required":["channel","granted"],"properties":{"channel":{"$ref":"#/components/schemas/ConsentChannel"},"granted":{"type":"boolean","description":"`true` records an opt-in, `false` an opt-out."},"source":{"type":["string","null"],"description":"How consent was obtained, kept in the ledger. Defaults to `manual`.","example":"balcao"}}},"Conversation":{"type":"object","description":"A conversation with a contact on one channel.","required":["id","store_id","channel_kind","status","priority","bot_active","unread_for_agents","unread_for_visitor","tags","attributes","created_at","updated_at"],"properties":{"assignee_user_id":{"type":["string","null"],"format":"uuid"},"attributes":{"type":"object","description":"Free-form context: the page the widget was opened on, user agent,\ne-mail subject, the AI summary (`summary`), the assisted-sale cart\n(`cart_id`)."},"bot_active":{"type":"boolean","description":"The AI agent answers while true; a team reply or a hand-over turns it off."},"channel_id":{"type":["string","null"],"format":"uuid","description":"The channel it arrived on. Null when that channel was deleted."},"channel_kind":{"$ref":"#/components/schemas/ConversationChannelKind"},"contact_email":{"type":["string","null"]},"contact_name":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"csat_comment":{"type":["string","null"]},"csat_score":{"type":["integer","null"],"format":"int32","description":"Satisfaction score the contact gave, 1 to 5."},"customer_id":{"type":["string","null"],"format":"uuid","description":"The store customer this contact was matched to (by e-mail or phone)."},"external_id":{"type":["string","null"],"description":"WhatsApp: the contact's number (`wa_id`, digits only). E-mail: their address."},"handed_over_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"last_message_at":{"type":["string","null"],"format":"date-time"},"last_message_preview":{"type":["string","null"],"description":"The last message, shortened to 140 characters (or a label such as\n\"📎 Anexo\" for an attachment without text)."},"last_message_sender":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationMessageSender"}]},"priority":{"$ref":"#/components/schemas/ConversationPriority"},"resolved_at":{"type":["string","null"],"format":"date-time"},"snoozed_until":{"type":["string","null"],"format":"date-time","description":"Set while `status` is `snoozed`: when it wakes up again."},"status":{"$ref":"#/components/schemas/ConversationStatus"},"store_id":{"type":"string","format":"uuid"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels, lowercase."},"unread_for_agents":{"type":"integer","format":"int32","description":"Contact messages the team has not read yet. `POST .../read` clears it."},"unread_for_visitor":{"type":"integer","format":"int32","description":"Team and bot messages the contact has not read yet."},"updated_at":{"type":"string","format":"date-time"},"visitor_id":{"type":["string","null"],"description":"Web widget: the browser's stable visitor id."}}},"ConversationAgentStats":{"type":"object","required":["resolved","open"],"properties":{"csat_avg":{"type":["number","null"],"format":"double"},"name":{"type":["string","null"]},"open":{"type":"integer","format":"int64"},"resolution_avg_s":{"type":["number","null"],"format":"double"},"resolved":{"type":"integer","format":"int64"},"user_id":{"type":["string","null"],"format":"uuid"}}},"ConversationAttachmentFile":{"type":"string","format":"binary","description":"The bytes of a message attachment."},"ConversationAttribution":{"type":"object","required":["orders","revenue_cents","window_days"],"properties":{"orders":{"type":"integer","format":"int64","description":"Orders placed within `window_days` of a conversation with the same customer."},"revenue_cents":{"type":"integer","format":"int64"},"window_days":{"type":"integer","format":"int32"}}},"ConversationBotSettings":{"type":"object","description":"How the store's customer-facing AI agent behaves.","required":["store_id","enabled","bot_name","greeting","persona","handover_keywords","handover_when_unsure","business_hours_only","business_hours","collect_contact","updated_at","model_configured","embeddings_configured"],"properties":{"bot_name":{"type":"string"},"business_hours":{"type":"object"},"business_hours_only":{"type":"boolean"},"collect_contact":{"type":"boolean","description":"Ask for name and e-mail on the widget."},"embeddings_configured":{"type":"boolean","description":"The server can embed the knowledge base (better retrieval)."},"enabled":{"type":"boolean","description":"The bot answers new conversations."},"greeting":{"type":"string","description":"First message of a widget conversation."},"handover_keywords":{"type":"array","items":{"type":"string"},"description":"Phrases that make the bot hand over to the team."},"handover_when_unsure":{"type":"boolean","description":"Hand over when the knowledge base has no answer."},"model_configured":{"type":"boolean","description":"The server has an AI model configured (without it the bot stays quiet)."},"persona":{"type":"string","description":"Tone and extra policies, in the store's words."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"ConversationBotSettingsUpdate":{"type":"object","properties":{"bot_name":{"type":["string","null"]},"business_hours":{"type":["object","null"]},"business_hours_only":{"type":["boolean","null"]},"collect_contact":{"type":["boolean","null"]},"enabled":{"type":["boolean","null"]},"greeting":{"type":["string","null"]},"handover_keywords":{"type":["array","null"],"items":{"type":"string"}},"handover_when_unsure":{"type":["boolean","null"]},"persona":{"type":["string","null"]}}},"ConversationBulkAction":{"type":"string","enum":["assign","unassign","resolve","reopen","snooze","priority","add_tag","remove_tag","read"]},"ConversationBulkRequest":{"type":"object","required":["ids","action"],"properties":{"action":{"$ref":"#/components/schemas/ConversationBulkAction"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"1 to 200 conversation ids. Ids of other stores are ignored."},"value":{"type":["string","null"],"description":"The action's argument (see `action`)."}}},"ConversationBulkResult":{"type":"object","required":["updated"],"properties":{"updated":{"type":"integer","description":"Conversations the action applied to.","minimum":0}}},"ConversationCart":{"type":"object","description":"The assisted-sale cart of a conversation: what the team, the bot and the\ncontact all see, paid through `url`.","required":["cart_id","status","currency","item_count","subtotal_cents","discount_cents","shipping_cents","total_cents","paid","items"],"properties":{"cart_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"discount_cents":{"type":"integer","format":"int64"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the link stops working."},"item_count":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ConversationCartItem"}},"order_id":{"type":["string","null"],"format":"uuid"},"order_number":{"type":["string","null"]},"paid":{"type":"boolean","description":"The order is paid."},"shipping_cents":{"type":"integer","format":"int64"},"status":{"type":"string","description":"`open`, `converted` (an order was created), `abandoned` or `expired`."},"subtotal_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"},"url":{"type":["string","null"],"description":"The payment link to send the contact."}}},"ConversationCartContact":{"type":"object","properties":{"city":{"type":["string","null"]},"complement":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF digits."},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"zip_code":{"type":["string","null"]}}},"ConversationCartCustomer":{"type":"object","description":"The cart's contact draft, and what is still missing for a PIX checkout.","required":["has_cart","requires_shipping","freight_selected","missing","ready"],"properties":{"contact":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCartContact"}]},"freight_selected":{"type":"boolean"},"has_cart":{"type":"boolean","description":"The conversation has a usable cart."},"missing":{"type":"array","items":{"type":"string"},"description":"Fields still needed: `cart`, `name`, `email`, `document`,\n`zip_code`, `street`, `number`, `city`, `state`, `freight`."},"ready":{"type":"boolean","description":"Nothing is missing: `POST .../cart/pix` will work."},"requires_shipping":{"type":"boolean","description":"Something in the cart ships (and pickup was not chosen)."}}},"ConversationCartCustomerInput":{"type":"object","description":"Contact and address details for the order. Fields left out are kept.","properties":{"city":{"type":["string","null"]},"complement":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF, 11 digits (punctuation is ignored). Validated."},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"zip_code":{"type":["string","null"]}}},"ConversationCartItem":{"type":"object","required":["variant_id","product_id","title","quantity","unit_price_cents","total_cents"],"properties":{"image":{"type":["string","null"]},"product_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","format":"int32"},"sku":{"type":["string","null"]},"title":{"type":"string"},"total_cents":{"type":"integer","format":"int64"},"unit_price_cents":{"type":"integer","format":"int64"},"variant_id":{"type":"string","format":"uuid"}}},"ConversationCartItemRequest":{"type":"object","required":["variant_id"],"properties":{"quantity":{"type":"integer","format":"int32","description":"Defaults to 1."},"variant_id":{"type":"string","format":"uuid"}}},"ConversationCartLinkRequest":{"type":"object","properties":{"text":{"type":["string","null"],"description":"The message; defaults to a standard text with the item count, total\nand link."}}},"ConversationCartQuantityRequest":{"type":"object","required":["quantity"],"properties":{"quantity":{"type":"integer","format":"int32","description":"New quantity; 0 removes the item."}}},"ConversationChannel":{"type":"object","description":"A channel the inbox receives conversations on.","required":["id","store_id","kind","name","public_key","config","enabled","created_at","updated_at"],"properties":{"config":{"type":"object","description":"Channel settings. Secrets never come back: `access_token` and\n`app_secret` show as `has_access_token` / `has_app_secret`. Web:\n`title`, `subtitle`, `color`, `position`, `greeting`,\n`allowed_origins`, `bot_enabled`... WhatsApp: `phone_number_id`,\n`waba_id`, `display_phone`, `verify_token`, `api_version`."},"created_at":{"type":"string","format":"date-time"},"enabled":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/ConversationChannelKind"},"name":{"type":"string"},"public_key":{"type":"string","description":"Web: the widget key (`data-key` of the embed script)."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"webhook_path":{"type":["string","null"],"description":"WhatsApp: the webhook path to register with Meta (on the API host)."}}},"ConversationChannelCreateRequest":{"type":"object","properties":{"config":{"type":["object","null"],"description":"Channel settings. Secrets (`access_token`, `app_secret`) are stored\nencrypted."},"enabled":{"type":["boolean","null"]},"kind":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationChannelKind","description":"Defaults to `web`."}]},"name":{"type":["string","null"],"description":"Defaults to \"Chat do site\", \"WhatsApp\" or \"E-mail\"."}}},"ConversationChannelKind":{"type":"string","description":"The channel a conversation runs on: the storefront chat widget (`web`),\nthe store's WhatsApp number or its e-mail inbox. More kinds may be\nadded; treat unknown values as a generic channel.","enum":["web","whatsapp","email"]},"ConversationChannelUpdateRequest":{"type":"object","properties":{"config":{"type":["object","null"],"description":"Replaces the settings. Leave a secret empty or out to keep the stored one."},"enabled":{"type":["boolean","null"]},"name":{"type":["string","null"]}}},"ConversationCounts":{"type":"object","description":"Inbox counts, for the views rail and an app badge.","required":["open","pending","snoozed","resolved","unassigned","mine","unread","unread_messages","mine_unread","unassigned_unread"],"properties":{"mine":{"type":"integer","format":"int64","description":"Open or pending conversations assigned to the caller."},"mine_unread":{"type":"integer","format":"int64","description":"Of `mine`, those with unread messages."},"open":{"type":"integer","format":"int64","description":"Conversations in each status."},"pending":{"type":"integer","format":"int64"},"resolved":{"type":"integer","format":"int64"},"snoozed":{"type":"integer","format":"int64"},"unassigned":{"type":"integer","format":"int64","description":"Open or pending conversations nobody is assigned to."},"unassigned_unread":{"type":"integer","format":"int64","description":"Of `unassigned`, those with unread messages."},"unread":{"type":"integer","format":"int64","description":"Open or pending conversations with unread contact messages."},"unread_messages":{"type":"integer","format":"int64","description":"Unread contact messages across open and pending conversations: the\nnumber for an app icon badge."}}},"ConversationCustomer":{"type":"object","description":"The matched customer, with order totals.","required":["id","name","orders_count","total_spent_cents"],"properties":{"email":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"last_order_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"orders_count":{"type":"integer","format":"int64"},"phone":{"type":["string","null"]},"total_spent_cents":{"type":"integer","format":"int64","description":"Paid orders, in cents."}}},"ConversationDetail":{"type":"object","description":"A conversation with what the thread's side panel shows.","required":["conversation","display_name","notes","recent_orders"],"properties":{"assignee_name":{"type":["string","null"],"description":"Full name of the assignee, else their e-mail."},"conversation":{"$ref":"#/components/schemas/Conversation"},"customer":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCustomer"}]},"display_name":{"type":"string","description":"Who to show (same rule as the list's `display_name`)."},"notes":{"type":"array","items":{"$ref":"#/components/schemas/ConversationNote"},"description":"Internal notes, oldest first."},"recent_orders":{"type":"array","items":{"$ref":"#/components/schemas/ConversationRecentOrder"},"description":"The customer's five latest orders."},"reply_window_expires_at":{"type":["string","null"],"format":"date-time","description":"WhatsApp only: until when a free-form reply is allowed (24 hours\nafter the contact's last message). Null on other channels, or when\nthe contact never wrote. Past it, sending answers 422\n`whatsapp_window_closed`."}}},"ConversationFreightOption":{"type":"object","description":"A shipping option for the cart.","required":["price_cents","price"],"properties":{"carrier":{"type":["string","null"]},"delivery_days":{"type":["integer","null"],"format":"int64"},"name":{"type":["string","null"]},"option_id":{"type":["string","null"],"description":"Pass back as `option_id` to select it."},"price":{"type":"string","description":"Formatted (\"R$ 29,90\")."},"price_cents":{"type":"integer","format":"int64"}}},"ConversationFreightRequest":{"type":"object","description":"Quote or pick freight: send `cep` to quote, `option_id` to select.","properties":{"cep":{"type":["string","null"],"description":"Destination CEP: quote the options."},"option_id":{"type":["string","null"],"description":"An `option_id` from a quote: select it."}}},"ConversationFreightResult":{"type":"object","description":"Quote results (`cep`) or the cart with the chosen option (`option_id`).","properties":{"cart":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCart","description":"After selecting: the cart with the shipping cost."}]},"destination":{"type":["string","null"],"description":"The CEP quoted (digits)."},"options":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ConversationFreightOption"}}}},"ConversationHit":{"type":"object","required":["id","channel","status"],"properties":{"channel":{"type":"string"},"email":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"preview":{"type":["string","null"]},"status":{"type":"string"}}},"ConversationHourPoint":{"type":"object","required":["hour","count"],"properties":{"count":{"type":"integer","format":"int64","description":"Contact messages received in that hour."},"hour":{"type":"integer","format":"int32","description":"Hour of day, São Paulo time."}}},"ConversationListItem":{"allOf":[{"$ref":"#/components/schemas/Conversation"},{"type":"object","required":["display_name"],"properties":{"assignee_name":{"type":["string","null"],"description":"Full name of the assignee, else their e-mail."},"customer_name":{"type":["string","null"],"description":"Name of the matched customer."},"display_name":{"type":"string","description":"Who to show: the contact's name, else the matched customer's name,\ne-mail, phone or WhatsApp number, else \"Visitante\"."},"waiting_since":{"type":["string","null"],"format":"date-time","description":"Since when the contact has been waiting for a reply (null when the\nlast word is the team's or the conversation is not open or pending)."}}}],"description":"An inbox row: the conversation plus what a list needs to render it."},"ConversationMessage":{"type":"object","description":"One message of a conversation.","required":["id","conversation_id","store_id","sender","text","payload","delivery_status","created_at","attachments"],"properties":{"agent_user_id":{"type":["string","null"],"format":"uuid","description":"The team member who wrote it (`sender` = `agent`)."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageAttachment"},"description":"Files that came with the message, each with a download URL."},"conversation_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"delivery_error":{"type":["string","null"],"description":"Why delivery failed, as the provider said it."},"delivery_status":{"$ref":"#/components/schemas/MessageDeliveryStatus"},"external_id":{"type":["string","null"],"description":"The provider's id (WhatsApp message id, `email:<Message-ID>`)."},"id":{"type":"string","format":"uuid"},"payload":{"$ref":"#/components/schemas/ConversationMessagePayload","description":"Structured extras: product cards, quick replies, the assisted-sale\ncart, a PIX charge, e-mail headers, system event details."},"read_at":{"type":["string","null"],"format":"date-time","description":"When the other side read it."},"sender":{"$ref":"#/components/schemas/ConversationMessageSender"},"store_id":{"type":"string","format":"uuid"},"text":{"type":"string","description":"Plain text. May be empty when the message is only an attachment or a card."}}},"ConversationMessageAttachment":{"type":"object","description":"A file attached to a message. `url` is an Admin API endpoint: download it\nwith the same `Authorization` header as any other call (the server\nfetches the file from WhatsApp or the mailbox on demand).","required":["index","kind","url"],"properties":{"index":{"type":"integer","format":"int32","description":"Position in the message, as used in the download path."},"kind":{"type":"string","description":"`image`, `video`, `audio`, `sticker`, `document` or `file`."},"mime_type":{"type":["string","null"]},"name":{"type":["string","null"],"description":"File name, when the sender gave one."},"path":{"type":["string","null"],"description":"The download path relative to the API origin (starting with\n`/v1/`), when the file is served by this API; null for direct\nlinks. Resolve it against the base URL your client already uses."},"size":{"type":["integer","null"],"format":"int64","description":"Size in bytes, when known."},"url":{"type":"string","description":"Where to download the file: a direct link, or `GET\n.../attachments/{index}` on this API (send the usual\n`Authorization` header). In REST responses the API link uses the\nscheme and host the request came in on; in WebSocket events, the\nAPI's configured public address."}}},"ConversationMessagePayload":{"type":"object","description":"The documented keys of a message `payload`. All optional; others may appear.","properties":{"assignee_user_id":{"type":["string","null"],"format":"uuid","description":"System `assignment` messages: the new assignee (null when unassigned)."},"attachments":{"type":["array","null"],"items":{"type":"object"},"description":"Attachment metadata as the channel sent it. Use the message's\n`attachments` for download URLs."},"cart":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCart","description":"Assisted-sale cart snapshot: render a cart card with its payment link."}]},"email":{"type":["object","null"],"description":"E-mail messages: subject, sender, sanitized HTML body, attachments."},"interactive":{"type":["boolean","null"],"description":"The contact tapped a button instead of typing."},"kind":{"type":["string","null"],"description":"System messages: `assignment`, `handover` or `resolved`."},"location":{"type":["object","null"],"description":"WhatsApp location messages: `latitude`, `longitude`, `name`, `address`."},"paid_order_id":{"type":["string","null"],"description":"The bot's payment confirmation: the paid order."},"pix":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationPixCharge","description":"A PIX charge created from the cart: render the QR code."}]},"pix_code":{"type":["boolean","null"],"description":"True on the follow-up message that carries only the PIX copy-and-paste code."},"products":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ConversationProductCard"},"description":"Product cards the bot suggested."},"quick_replies":{"type":["array","null"],"items":{"type":"string"},"description":"Up to three suggested answers, shown as buttons."},"reason":{"type":["string","null"],"description":"System `handover` messages: why the bot handed over."}}},"ConversationMessageSender":{"type":"string","description":"Who wrote a message. `visitor` is the contact (the customer, on any\nchannel), `agent` a team member, `bot` the store's AI agent, `system` an\nevent line (assignment, hand-over, resolution).","enum":["visitor","agent","bot","system"]},"ConversationMessageSent":{"type":"object","description":"The stored message and the conversation after it.","required":["message","conversation"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"message":{"$ref":"#/components/schemas/ConversationMessage"}}},"ConversationNote":{"type":"object","description":"An internal note: visible to the team only, never sent to the contact.","required":["id","conversation_id","text","created_at"],"properties":{"author_name":{"type":["string","null"]},"author_user_id":{"type":["string","null"],"format":"uuid"},"conversation_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"text":{"type":"string"}}},"ConversationNoteRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}},"ConversationPixCharge":{"type":"object","description":"A PIX charge for the order created from the cart.","required":["order_id","order_number","amount_cents","amount"],"properties":{"amount":{"type":"string","description":"Formatted (\"R$ 129,90\")."},"amount_cents":{"type":"integer","format":"int64"},"cart":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCart","description":"The cart the order came from. Absent in the bot's PIX messages."}]},"copy_paste":{"type":["string","null"],"description":"The PIX copy-and-paste code."},"expires_at":{"type":["string","null"],"format":"date-time"},"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"qr_code_base64":{"type":["string","null"],"description":"PNG of the QR code, base64."}}},"ConversationPixSent":{"type":"object","description":"The PIX message, the conversation and the charge.","required":["message","conversation","pix"],"properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"message":{"$ref":"#/components/schemas/ConversationMessage","description":"The message with the QR code card (`payload.pix`)."},"pix":{"$ref":"#/components/schemas/ConversationPixCharge"}}},"ConversationPriority":{"type":"string","enum":["low","normal","high","urgent"]},"ConversationProductCard":{"type":"object","description":"A product card inside a bot message.","required":["id","title","price","url"],"properties":{"compare_at":{"type":["string","null"],"description":"Formatted original price when on promotion."},"id":{"type":"string","format":"uuid"},"image":{"type":["string","null"]},"price":{"type":"string","description":"Formatted price (\"R$ 129,90\")."},"title":{"type":"string"},"url":{"type":"string","description":"Product page on the storefront."}}},"ConversationRecentOrder":{"type":"object","required":["id","status","fulfillment_status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"fulfillment_status":{"$ref":"#/components/schemas/OrderFulfillmentStatus"},"id":{"type":"string","format":"uuid"},"number":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/OrderStatus"},"total_cents":{"type":["integer","null"],"format":"int64"}}},"ConversationReplyRequest":{"type":"object","description":"A reply to the contact.","properties":{"payload":{"type":["object","null"],"description":"Structured extras, e.g. `{\"quick_replies\": [\"Sim\", \"Não\"]}` (up to\nthree buttons on WhatsApp). Sending files is not supported yet."},"text":{"type":"string","description":"The message text, up to 4096 characters."}}},"ConversationReport":{"type":"object","description":"The attendance report.","required":["days","totals","times","volume","by_hour","agents","attributed","tags"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/ConversationAgentStats"},"description":"The 20 busiest assignees."},"attributed":{"$ref":"#/components/schemas/ConversationAttribution"},"by_hour":{"type":"array","items":{"$ref":"#/components/schemas/ConversationHourPoint"}},"days":{"type":"integer","format":"int64"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/ConversationTagCount"},"description":"The 12 most used labels."},"times":{"$ref":"#/components/schemas/ConversationReportTimes"},"totals":{"$ref":"#/components/schemas/ConversationReportTotals"},"volume":{"type":"array","items":{"$ref":"#/components/schemas/ConversationVolumePoint"},"description":"Conversations per day and channel."}}},"ConversationReportTimes":{"type":"object","properties":{"first_response_avg_s":{"type":["number","null"],"format":"double","description":"Seconds from opening to the first team or bot reply."},"first_response_median_s":{"type":["number","null"],"format":"double"},"resolution_avg_s":{"type":["number","null"],"format":"double","description":"Seconds from opening to resolution."},"resolution_median_s":{"type":["number","null"],"format":"double"}}},"ConversationReportTotals":{"type":"object","required":["conversations","resolved","open","bot_resolved","csat_count","customers","previous_conversations"],"properties":{"bot_resolved":{"type":"integer","format":"int64","description":"Resolved by the bot without a hand-over."},"conversations":{"type":"integer","format":"int64","description":"Conversations opened in the window."},"csat_avg":{"type":["number","null"],"format":"double"},"csat_count":{"type":"integer","format":"int64"},"customers":{"type":"integer","format":"int64","description":"Distinct customers."},"open":{"type":"integer","format":"int64"},"previous_conversations":{"type":"integer","format":"int64","description":"Conversations in the window before this one, for comparison."},"resolved":{"type":"integer","format":"int64"}}},"ConversationSocketTicket":{"type":"object","description":"A one-time ticket for the agent WebSocket.","required":["ticket","expires_in"],"properties":{"expires_in":{"type":"integer","format":"int64","description":"Seconds the ticket stays valid (60)."},"ticket":{"type":"string","description":"Pass as `?ticket=` to `/ws/conversations`. Single use."}}},"ConversationStats":{"type":"object","description":"Inbox health for the last days.","required":["new_7d","open_now","resolved_7d","bot_resolved_7d","agents_online"],"properties":{"agents_online":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Team members connected to the inbox right now."},"bot_resolved_7d":{"type":"integer","format":"int64","description":"Resolved by the bot alone, last 7 days."},"csat_avg_30d":{"type":["number","null"],"format":"double","description":"Average satisfaction (1 to 5) over the last 30 days."},"first_response_seconds_7d":{"type":["number","null"],"format":"double","description":"Average seconds from hand-over to the first team reply, last 7 days."},"new_7d":{"type":"integer","format":"int64","description":"Conversations opened in the last 7 days."},"open_now":{"type":"integer","format":"int64","description":"Open or pending now."},"resolved_7d":{"type":"integer","format":"int64","description":"Resolved in the last 7 days."}}},"ConversationStatus":{"type":"string","description":"Where a conversation stands. `open`: someone should answer; `pending`:\nthe bot handed over and nobody took it yet; `snoozed`: hidden until\n`snoozed_until` (a new customer message wakes it); `resolved`: closed\n(a new customer message reopens it).","enum":["open","pending","snoozed","resolved"]},"ConversationSuggestRequest":{"type":"object","properties":{"draft":{"type":["string","null"],"description":"The composer's current text, for `rewrite` and `translate`."},"mode":{"type":["string","null"],"description":"`reply` (default): draft an answer to the contact's last message;\n`rewrite`: polish `draft` in the brand's voice; `translate:<language>`:\ntranslate `draft`."}}},"ConversationSuggestion":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"Ready to send; nothing was sent."}}},"ConversationSummary":{"type":"object","description":"The AI summary of a thread.","required":["done","pending","suggested_tags","message_count","at"],"properties":{"at":{"type":"string","format":"date-time"},"done":{"type":"array","items":{"type":"string"},"description":"What was already done."},"intent":{"type":["string","null"],"description":"What the contact wants, in one sentence."},"message_count":{"type":"integer","format":"int64","description":"Messages the summary covers; a new message makes it stale."},"pending":{"type":"array","items":{"type":"string"},"description":"What is still open."},"sentiment":{"type":["string","null"],"description":"`positivo`, `neutro` or `negativo`."},"suggested_tags":{"type":"array","items":{"type":"string"},"description":"Up to three labels the model suggests."}}},"ConversationSummaryResult":{"type":"object","required":["summary","cached"],"properties":{"cached":{"type":"boolean","description":"The stored summary was still current (no new message since)."},"summary":{"$ref":"#/components/schemas/ConversationSummary"}}},"ConversationTagCount":{"type":"object","required":["tag","count"],"properties":{"count":{"type":"integer","format":"int64"},"tag":{"type":"string"}}},"ConversationTypingRequest":{"type":"object","required":["typing"],"properties":{"typing":{"type":"boolean","description":"True while typing; send false when the draft is cleared or sent."}}},"ConversationVariantHit":{"type":"object","description":"A variant the team can add to the cart.","required":["variant_id","product_id","product_title","title","price_cents","price","variants_of_product"],"properties":{"available":{"type":["boolean","null"],"description":"In stock. Null when the store manages stock elsewhere."},"image":{"type":["string","null"]},"price":{"type":"string","description":"Formatted (\"R$ 129,90\")."},"price_cents":{"type":"integer","format":"int64"},"product_id":{"type":"string","format":"uuid"},"product_title":{"type":"string"},"sku":{"type":["string","null"]},"title":{"type":"string","description":"Product and variant title together."},"variant_id":{"type":"string","format":"uuid"},"variant_title":{"type":["string","null"],"description":"Null for single-variant products."},"variants_of_product":{"type":"integer","format":"int64","description":"How many active variants the product has."}}},"ConversationVolumePoint":{"type":"object","required":["day","channel","count"],"properties":{"channel":{"$ref":"#/components/schemas/ConversationChannelKind"},"count":{"type":"integer","format":"int64"},"day":{"type":"string","format":"date"}}},"ConversionDelivery":{"type":"object","description":"An order and how its conversion reached Meta and Google Ads.","required":["order_id","created_at"],"properties":{"capi_meta_error":{"type":["string","null"],"description":"Meta's error message for the last failed attempt."},"capi_meta_sent_at":{"type":["string","null"],"format":"date-time"},"capi_meta_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversionDeliveryStatus","description":"Meta Conversions API; null when never attempted."}]},"created_at":{"type":"string","format":"date-time"},"currency":{"type":["string","null"]},"google_ads_sent_at":{"type":["string","null"],"format":"date-time"},"google_ads_skip_reason":{"type":["string","null"],"description":"Why the Google Ads upload was skipped (`no_gclid`,\n`config_incomplete`...)."},"google_ads_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversionDeliveryStatus","description":"Google Ads click conversion; null when never attempted."}]},"last_campaign":{"type":["string","null"]},"last_medium":{"type":["string","null"]},"last_source":{"type":["string","null"]},"number":{"type":["string","null"]},"order_id":{"type":"string","format":"uuid"},"payment_status":{"type":["string","null"],"description":"Payment status; only `captured` orders send conversions."},"total_cents":{"type":["integer","null"],"format":"int64"}}},"ConversionDeliveryStatus":{"type":"string","description":"Where an order's conversion upload to an ad platform stands.","enum":["sending","sent","failed","skipped"]},"CreateAdAudienceRequest":{"type":"object","required":["segment_id"],"properties":{"auto_sync":{"type":["boolean","null"],"description":"Defaults to true."},"name":{"type":["string","null"],"description":"Defaults to \"Mobiari · <segment name>\"."},"segment_id":{"type":"string","format":"uuid"}}},"CreateApiTokenRequest":{"type":"object","required":["name","scopes"],"properties":{"expires_at":{"type":["string","null"],"format":"date-time","description":"When the token stops working. Omit for no expiry."},"name":{"type":"string","description":"Human-readable label, e.g. \"POS terminal\" or \"Stock sync script\"."},"scopes":{"type":"array","items":{"type":"string"},"description":"Permission codes the token may use. Must be a subset of the\ncreator's own permissions."}}},"CreateApiTokenResponse":{"allOf":[{"$ref":"#/components/schemas/ApiTokenSummary"},{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The raw token, prefixed with `mobi_st_`. Shown only in this response."}}}]},"CreateDocumentRequest":{"type":"object","properties":{"data":{"type":["object","null"],"description":"Defaults to `{}`."},"is_active":{"type":["boolean","null"],"description":"Defaults to `true`."},"position":{"type":["integer","null"],"format":"int32","description":"Defaults to the end of the collection."},"slug":{"type":["string","null"]}}},"CreateEmailBroadcastRequest":{"type":"object","description":"A new campaign. Subject and body come from the template unless\noverridden; one of them must give both.","required":["name"],"properties":{"ab_test":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EmailAbTest"}]},"audience":{"$ref":"#/components/schemas/EmailAudienceFilter"},"html_override":{"type":["string","null"]},"name":{"type":"string"},"optimize_send_time":{"type":"boolean","description":"Send each recipient at the hour they usually open."},"reply_to":{"type":["string","null"]},"scheduled_at":{"type":["string","null"],"format":"date-time","description":"If null, broadcast is created in 'draft' status. The /send endpoint\nkicks it off; otherwise scheduled_at sets status='scheduled' and\nthe worker picks it up when the time arrives."},"subject_override":{"type":["string","null"],"description":"Optional overrides — when present, take priority over the\ntemplate fields. Useful for one-off subject A/Bs without forking\nthe template."},"template_id":{"type":["string","null"],"format":"uuid"},"text_override":{"type":["string","null"]}}},"CreateEmailTemplateRequest":{"type":"object","description":"A new template: a block `design` (compiled to `html`) or raw `html`.","required":["name","subject"],"properties":{"design":{"type":["object","null"]},"html":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"name":{"type":"string"},"preview_text":{"type":["string","null"]},"reply_to":{"type":["string","null"]},"subject":{"type":"string"},"text_body":{"type":["string","null"]}}},"CreateInviteRequest":{"type":"object","required":["email","role_ids"],"properties":{"email":{"type":"string","example":"joao@example.com"},"role_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Roles to grant on acceptance. At least one."}}},"CreateKbArticleRequest":{"type":"object","properties":{"body_md":{"type":["string","null"]},"collection_id":{"type":["string","null"],"format":"uuid"},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/KbArticleStatus","description":"Defaults to `draft`."}]},"title":{"type":["string","null"],"description":"Defaults to \"Novo artigo\"."}}},"CreateNotificationChannelRequest":{"type":"object","required":["name","channel_type"],"properties":{"channel_type":{"$ref":"#/components/schemas/NotificationChannelType"},"config_json":{"type":["object","null"]},"enabled_events":{"type":["array","null"],"items":{"type":"string"}},"is_enabled":{"type":["boolean","null"],"description":"Defaults to true."},"locale":{"type":["string","null"],"description":"Defaults to `pt-BR`."},"name":{"type":"string","description":"1 to 255 characters."}}},"CreateOrderItem":{"type":"object","description":"A line of a new order.","required":["product_variant_id","quantity"],"properties":{"product_variant_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","format":"int32","description":"At least 1."}}},"CreateOrderItemAdjustmentRequest":{"type":"object","required":["order_item_id","adjustment_type","amount_cents"],"properties":{"adjustment_type":{"type":"string","description":"1 to 50 characters, e.g. `discount` or `surcharge`."},"amount_cents":{"type":"integer","format":"int64","description":"Signed amount in cents."},"description":{"type":["string","null"],"description":"Up to 255 characters."},"order_item_id":{"type":"string","format":"uuid","description":"A line of this order."}}},"CreateOrderRequest":{"type":"object","description":"A new order, priced from the catalog.","required":["items"],"properties":{"customer_id":{"type":["string","null"],"format":"uuid"},"discount_code":{"type":["string","null"],"description":"An active discount code of the store."},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateOrderItem"}},"sales_channel_id":{"type":["string","null"],"format":"uuid"},"shipping_method_id":{"type":["string","null"],"description":"Accepted for compatibility; not used."}}},"CreatePaymentProviderRequest":{"type":"object","description":"A gateway to connect.","required":["name","code"],"properties":{"code":{"type":"string","description":"Gateway code from the catalog, e.g. `mercado_pago`."},"config_json":{"type":["object","null"],"description":"Settings, keyed as the catalog's `fields` say."},"is_active":{"type":["boolean","null"]},"is_default":{"type":["boolean","null"]},"name":{"type":"string"}}},"CreateShipmentRequest":{"type":"object","description":"A new shipment.","properties":{"carrier_name":{"type":["string","null"]},"freight_external_order_code":{"type":["string","null"],"description":"Link an order already created at the carrier."},"freight_provider_code":{"type":["string","null"],"description":"`central_do_frete`, `local_delivery`, `other_carrier` or `pickup`."},"items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ShipmentItemInput"},"description":"Omit to load the box with everything still unshipped."},"notes":{"type":["string","null"]},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ShipmentStatus","description":"Defaults to `draft`."}]},"tracking_code":{"type":["string","null"]}}},"CreateStoreRequest":{"type":"object","required":["tenant_id","name"],"properties":{"name":{"type":"string","example":"Loja Centro"},"tenant_id":{"type":"string","format":"uuid"}}},"CreateStoreRoleRequest":{"type":"object","required":["name","permission_codes"],"properties":{"color":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":"string","description":"1 to 80 characters."},"permission_codes":{"type":"array","items":{"type":"string"}},"position":{"type":["integer","null"],"format":"int32","description":"Defaults to 50."}}},"CreateStorefrontPageRequest":{"type":"object","required":["title","slug"],"properties":{"content":{"type":["string","null"]},"published":{"type":["boolean","null"],"description":"Defaults to `false`."},"slug":{"type":"string","description":"1 to 255 characters, unique in the store."},"template":{"type":["string","null"],"description":"Up to 100 characters."},"title":{"type":"string","description":"1 to 255 characters."}}},"CreateTenantRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Loja da Ana"},"plan_code":{"type":["string","null"],"description":"The plan to try, from `GET /billing/plans` (the plan picked on the\npricing page). Defaults to `profissional`.","example":"profissional"}}},"CreateWebhookRequest":{"type":"object","required":["url"],"properties":{"events":{"type":"array","items":{"type":"string"},"description":"Event names to subscribe to right away."},"is_active":{"type":["boolean","null"],"description":"Defaults to `true`."},"secret":{"type":["string","null"],"description":"Signing secret. Omit to have one generated."},"url":{"type":"string","description":"`https://` (or `http://`) URL that receives the POSTs.","example":"https://example.com/hooks/mobiari"}}},"CreateWorkflowRequest":{"type":"object","required":["kind","name"],"properties":{"description":{"type":["string","null"]},"graph":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/WorkflowGraph","description":"Defaults to an empty graph."}]},"kind":{"$ref":"#/components/schemas/WorkflowKind"},"name":{"type":"string"},"trigger":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/WorkflowTrigger","description":"Defaults to a manual trigger."}]}}},"Customer":{"type":"object","description":"A customer of the store.","required":["id","store_id","marketing_opt_in","email_verified","phone_verified","total_orders","total_spent","created_at","updated_at","lifecycle"],"properties":{"acquisition":{"type":["object","null"],"description":"First-touch attribution of their first order (UTM parameters, click\nids, referrer, landing page). Only on the customer record, null in\nlists."},"company":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"date_of_birth":{"type":["string","null"],"format":"date"},"document":{"type":["string","null"],"description":"CPF/CNPJ, digits only. Captured at checkout the first time they buy."},"email":{"type":["string","null"]},"email_verified":{"type":"boolean"},"first_name":{"type":["string","null"]},"gender":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"last_login_at":{"type":["string","null"],"format":"date-time","description":"Last storefront sign-in; null for guests who never signed in."},"last_name":{"type":["string","null"]},"last_order_at":{"type":["string","null"],"format":"date-time"},"lifecycle":{"$ref":"#/components/schemas/CustomerLifecycle","description":"Derived on every read, never stored."},"marketing_opt_in":{"type":"boolean"},"notes":{"type":["string","null"],"description":"Internal notes; never shown to the customer."},"phone":{"type":["string","null"]},"phone_verified":{"type":"boolean"},"store_id":{"type":"string","format":"uuid"},"tags":{"type":["array","null"],"items":{"type":"string"}},"total_orders":{"type":"integer","format":"int32","description":"Paid orders."},"total_spent":{"type":"integer","format":"int32","description":"Paid order totals, in cents."},"updated_at":{"type":"string","format":"date-time"}}},"CustomerAddress":{"type":"object","description":"A saved address.","required":["id","customer_id","address_type","is_default","address_line_1","city","country","created_at","updated_at"],"properties":{"address_line_1":{"type":"string","description":"Street and number, e.g. `Rua das Flores, 88`."},"address_line_2":{"type":["string","null"],"description":"Neighborhood and complement."},"address_type":{"type":"string","description":"`shipping`, `billing`, `home`, `work` or `other`; clients should\ntolerate other values."},"city":{"type":"string"},"company":{"type":["string","null"]},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"customer_id":{"type":"string","format":"uuid"},"first_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean","description":"The default address of its type."},"last_name":{"type":["string","null"]},"phone":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"state":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}},"CustomerAddressCreateRequest":{"type":"object","description":"A new address.","required":["address_type","address_line_1","city","country"],"properties":{"address_line_1":{"type":"string"},"address_line_2":{"type":["string","null"]},"address_type":{"type":"string","description":"`shipping`, `billing`, `home`, `work` or `other`."},"city":{"type":"string"},"company":{"type":["string","null"]},"country":{"type":"string"},"first_name":{"type":["string","null"]},"is_default":{"type":["boolean","null"],"description":"Make it the default of its type (clears the previous default)."},"last_name":{"type":["string","null"]},"phone":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"state":{"type":["string","null"]}}},"CustomerAddressUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value.","properties":{"address_line_1":{"type":["string","null"]},"address_line_2":{"type":["string","null"]},"address_type":{"type":["string","null"]},"city":{"type":["string","null"]},"company":{"type":["string","null"]},"country":{"type":["string","null"]},"first_name":{"type":["string","null"]},"is_default":{"type":["boolean","null"],"description":"`true` makes it the default of its type (clears the previous one)."},"last_name":{"type":["string","null"]},"phone":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"state":{"type":["string","null"]}}},"CustomerCreateRequest":{"type":"object","description":"A new customer.","properties":{"company":{"type":["string","null"]},"date_of_birth":{"type":["string","null"],"format":"date"},"document":{"type":["string","null"],"description":"CPF/CNPJ; stored as digits."},"email":{"type":["string","null"]},"first_name":{"type":["string","null"]},"gender":{"type":["string","null"]},"last_name":{"type":["string","null"]},"marketing_opt_in":{"type":["boolean","null"],"description":"Defaults to false."},"notes":{"type":["string","null"]},"phone":{"type":["string","null"]},"tags":{"type":["array","null"],"items":{"type":"string"}}}},"CustomerDetail":{"allOf":[{"$ref":"#/components/schemas/Customer"},{"type":"object","required":["addresses","recent_interactions","orders"],"properties":{"addresses":{"type":"array","items":{"$ref":"#/components/schemas/CustomerAddress"},"description":"Default first, then newest."},"orders":{"type":"array","items":{"$ref":"#/components/schemas/CustomerOrder"},"description":"The 50 most recent orders, newest first. `GET /stores/{store_id}/orders?customer_id=`\nlists them all."},"recent_interactions":{"type":"array","items":{"$ref":"#/components/schemas/CustomerInteraction"},"description":"The 50 most recent timeline entries, newest first. Page through\n`GET .../interactions` for the rest."}}}],"description":"The customer record: the customer plus their addresses, recent\nactivity and recent orders."},"CustomerEmailActivity":{"type":"object","description":"A customer's e-mail consent and recent e-mail activity.","required":["summary","events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/EmailActivityEvent"},"description":"The 200 most recent events, newest first."},"summary":{"$ref":"#/components/schemas/EmailConsentSummary"}}},"CustomerGraph":{"type":"object","description":"Everything known about how to reach a customer.","required":["customer","identities","channels","lead_score","consent","duplicates"],"properties":{"channels":{"$ref":"#/components/schemas/Channels"},"consent":{"type":"array","items":{"$ref":"#/components/schemas/ConsentEntry"},"description":"The 50 most recent consent changes, newest first."},"customer":{"$ref":"#/components/schemas/GraphCustomer"},"duplicates":{"type":"array","items":{"$ref":"#/components/schemas/DuplicateCandidate"},"description":"Other customers that look like the same person."},"identities":{"type":"array","items":{"$ref":"#/components/schemas/Identity"}},"lead_score":{"type":"integer","format":"int32"}}},"CustomerHit":{"type":"object","required":["id","name","total_orders","total_spent"],"properties":{"email":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"phone":{"type":["string","null"]},"total_orders":{"type":"integer","format":"int32"},"total_spent":{"type":"integer","format":"int32","description":"Lifetime spend in cents."}}},"CustomerInteraction":{"type":"object","description":"An entry on the customer's activity timeline: a note, call or e-mail\nlogged by the team, or an event the system recorded (`order_placed`,\n`order_fulfilled`, `order_cancelled`, `marketing_opt_in`, ...).","required":["id","customer_id","interaction_type","is_private","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"format":"uuid","description":"Who logged it; null for system events."},"customer_id":{"type":"string","format":"uuid"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"interaction_type":{"type":"string","description":"`note`, `call`, `email`, `meeting`, `complaint`, `other` for team\nentries; system events use their own types. The set grows; tolerate\nunknown values."},"is_private":{"type":"boolean"},"metadata":{"type":["object","null"],"description":"Free-form context, e.g. `{\"order_id\": ...}` on order events."},"title":{"type":["string","null"]}}},"CustomerInteractionCreateRequest":{"type":"object","description":"A timeline entry logged by the team.","required":["interaction_type"],"properties":{"description":{"type":["string","null"]},"interaction_type":{"type":"string","description":"`note`, `call`, `email`, `meeting`, `complaint` or `other`."},"is_private":{"type":["boolean","null"],"description":"Defaults to false."},"metadata":{"type":["object","null"]},"title":{"type":["string","null"]}}},"CustomerLifecycle":{"type":"string","description":"Where a customer is in their relationship with the store, derived from\ntheir paid orders:\n\n| Stage | Meaning |\n| --- | --- |\n| `vip` | Spent at least the store's 90th percentile. |\n| `new` | No paid order yet. |\n| `active` | Last order within 60 days. |\n| `at_risk` | Last order 60 to 180 days ago. |\n| `dormant` | Last order more than 180 days ago. |","enum":["new","active","at_risk","dormant","vip"]},"CustomerOrder":{"type":"object","description":"One of the customer's orders, with how it was paid and where it is.","required":["id","status","total_cents","currency","created_at","shipments"],"properties":{"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"danfe_url":{"type":["string","null"]},"fulfillment_method":{"type":["string","null"],"description":"`shipping`, `pickup` or `local_delivery`."},"fulfillment_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OrderFulfillmentStatus"}]},"id":{"type":"string","format":"uuid"},"nfe_number":{"type":["string","null"],"description":"Nota fiscal number and DANFE link, once attached."},"number":{"type":["string","null"]},"payer_document":{"type":["string","null"],"description":"Payer CPF/CNPJ from the latest payment attempt, when the gateway\nreported one."},"payment_method":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaymentIntentMethod","description":"Method of the latest payment attempt."}]},"payment_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OrderPaymentStatus"}]},"shipments":{"type":"array","items":{"$ref":"#/components/schemas/CustomerShipment"},"description":"Oldest first."},"status":{"$ref":"#/components/schemas/OrderStatus"},"total_cents":{"type":"integer","format":"int64"}}},"CustomerShipment":{"type":"object","description":"A shipment of one of the customer's orders.","required":["status","tracking_events"],"properties":{"carrier_name":{"type":["string","null"]},"delivered_at":{"type":["string","null"],"format":"date-time"},"freight_external_order_code":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"tracking_code":{"type":["string","null"]},"tracking_events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"},"description":"Carrier tracking events, oldest first, when synced."}}},"CustomerUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value.","properties":{"company":{"type":["string","null"]},"date_of_birth":{"type":["string","null"],"format":"date"},"document":{"type":["string","null"],"description":"CPF/CNPJ; stored as digits."},"email":{"type":["string","null"]},"email_verified":{"type":["boolean","null"]},"first_name":{"type":["string","null"]},"gender":{"type":["string","null"]},"last_name":{"type":["string","null"]},"marketing_opt_in":{"type":["boolean","null"]},"notes":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_verified":{"type":["boolean","null"]},"tags":{"type":["array","null"],"items":{"type":"string"}}}},"DashboardActivityItem":{"type":"object","required":["action","activity_type","created_at","kind","params"],"properties":{"action":{"type":"string","description":"What happened, in English, e.g. `Order #1042 created`. For display\nonly; translate from `kind` and `params` instead."},"activity_type":{"type":"string","description":"`order`, `product` or `customer`."},"created_at":{"type":"string","format":"date-time"},"customer_id":{"type":["string","null"],"format":"uuid","description":"Set for `customer_registered`, and for `order_created` when the\norder has a customer record."},"kind":{"$ref":"#/components/schemas/DashboardActivityKind"},"order_id":{"type":["string","null"],"format":"uuid","description":"Set for `order_created`."},"params":{"$ref":"#/components/schemas/DashboardActivityParams","description":"Values for the `kind` message."},"product_id":{"type":["string","null"],"format":"uuid","description":"Set for `product_created`."}}},"DashboardActivityKind":{"type":"string","description":"What happened, for translation and deep links. More kinds may be\nadded; show `action` for kinds you don't know.","enum":["order_created","product_created","customer_registered"]},"DashboardActivityParams":{"type":"object","description":"Values to fill a translated `kind` message with.","properties":{"customer_name":{"type":["string","null"],"description":"`customer_registered`: the customer's full name, else their e-mail."},"order_number":{"type":["string","null"],"description":"`order_created`: the order number (or the id's first 8 characters\nwhen it has none)."},"product_title":{"type":["string","null"],"description":"`product_created`: the product title."}}},"DashboardAttention":{"type":"object","description":"Counts of things waiting on someone.","required":["orders_to_fulfill","orders_awaiting_payment","low_stock_items","out_of_stock_items","failed_runs_24h","runs_awaiting_approval","assistant_proposals_pending","purchase_orders_overdue","carts_abandoned_24h","reviews_pending"],"properties":{"assistant_proposals_pending":{"type":"integer","format":"int64"},"carts_abandoned_24h":{"type":"integer","format":"int64"},"failed_runs_24h":{"type":"integer","format":"int64"},"low_stock_items":{"type":"integer","format":"int64"},"orders_awaiting_payment":{"type":"integer","format":"int64"},"orders_to_fulfill":{"type":"integer","format":"int64"},"out_of_stock_items":{"type":"integer","format":"int64"},"purchase_orders_overdue":{"type":"integer","format":"int64"},"reviews_pending":{"type":"integer","format":"int64"},"runs_awaiting_approval":{"type":"integer","format":"int64"}}},"DashboardDayPoint":{"type":"object","description":"One day of a daily series.","required":["date","value"],"properties":{"date":{"type":"string","format":"date","description":"The day, in the store's time zone."},"value":{"type":"integer","format":"int64"}}},"DashboardStats":{"type":"object","description":"Headline numbers for the selected period, each with its change against\nthe period before.\n\n**Time zone.** Every day boundary is midnight in the store's time zone\n(`timezone`: the store's own setting, else its tenant's, else UTC).\n`range=month` starts at 00:00 local time on the 1st of the current\nlocal month; `7d`, `30d` and `90d` are today plus the 6, 29 or 89 local\ndays before it, starting at local midnight. The period ends now.\n`period_start` is the first instant counted, and every daily series\nhas one point per local date from `period_start` through `today`.\n\n**Revenue** is always paid revenue: the `total_cents` of orders with\nstatus `paid` or `fulfilled` (refunded, cancelled, pending and draft\norders are left out), by the local day the order was created. So\n`revenue_cents` is the sum of `revenue_series`, and\n`revenue_today_cents` is its last point.\n\n**Orders** in `orders_series` and `orders_today` are every order\ncreated that local day except drafts and cancelled ones, paid or not.","required":["total_products","active_customers","pending_orders","revenue_this_month_cents","revenue_currency","total_products_change_pct","active_customers_change_pct","pending_orders_change_pct","revenue_this_month_change_pct","recent_activity","visitors","support_open_count","revenue_series","orders_series","revenue_cents","revenue_change_pct","revenue_today_cents","orders_today","timezone","today","period_start"],"properties":{"active_customers":{"type":"integer","format":"int64","description":"Customers in the store now."},"active_customers_change_pct":{"type":"number","format":"double","description":"Change in new customers against the previous period."},"orders_series":{"type":"array","items":{"$ref":"#/components/schemas/DashboardDayPoint"},"description":"Orders per local day over the period (every status except draft\nand cancelled), oldest first, ending with today."},"orders_today":{"type":"integer","format":"int64","description":"Orders created today (store-local day), every status except draft\nand cancelled."},"pending_orders":{"type":"integer","format":"int64","description":"Orders waiting to be handled now (draft or pending)."},"pending_orders_change_pct":{"type":"number","format":"double","description":"Change in pending orders against those created before the period\nand still pending."},"period_start":{"type":"string","format":"date-time","description":"First instant of the period (local midnight, as UTC)."},"recent_activity":{"type":"array","items":{"$ref":"#/components/schemas/DashboardActivityItem"},"description":"The 8 latest orders, products and customers, newest first."},"revenue_cents":{"type":"integer","format":"int64","description":"Paid revenue over the selected period, in cents."},"revenue_change_pct":{"type":"number","format":"double","description":"Change in paid revenue against the previous period: the previous\ncalendar month in full for `range=month`, the same number of local\ndays before `period_start` otherwise."},"revenue_currency":{"type":"string","description":"ISO 4217 currency of the revenue figures.","example":"BRL"},"revenue_series":{"type":"array","items":{"$ref":"#/components/schemas/DashboardDayPoint"},"description":"Paid revenue per local day (cents) over the period, oldest first,\nending with today."},"revenue_this_month_cents":{"type":"integer","format":"int64","description":"Same value as `revenue_cents`: paid revenue over the selected\n`range`, which is the calendar month only when `range=month`. Use\n`revenue_cents`.","deprecated":true},"revenue_this_month_change_pct":{"type":"number","format":"double","description":"Same value as `revenue_change_pct`. Use `revenue_change_pct`.","deprecated":true},"revenue_today_cents":{"type":"integer","format":"int64","description":"Paid revenue of orders created today (store-local day), in cents."},"support_open_count":{"type":"integer","format":"int64","description":"Complaints and refund requests in the last 30 days (a rolling\n30 × 24 h window, not local days)."},"timezone":{"type":"string","description":"IANA time zone the day boundaries are computed in.","example":"America/Sao_Paulo"},"today":{"type":"string","format":"date","description":"Today's date in the store's time zone: the last point of every\ndaily series."},"total_products":{"type":"integer","format":"int64","description":"Products in the store now."},"total_products_change_pct":{"type":"number","format":"double","description":"Change in the product count since the period started."},"visitors":{"type":"array","items":{"$ref":"#/components/schemas/DashboardVisitorsPoint"},"description":"Storefront traffic per local day over the period."}}},"DashboardVisitorsPoint":{"type":"object","required":["date","visitors","sessions"],"properties":{"date":{"type":"string","format":"date","description":"The day, in the store's time zone."},"sessions":{"type":"integer","format":"int64","description":"Sessions that day."},"visitors":{"type":"integer","format":"int64","description":"Unique visitors that day (distinct visitor cookie)."}}},"DedupeDraftsResult":{"type":"object","description":"What a draft dedupe did (or would do, for a dry run).","required":["dry_run","groups_examined","products_deleted","products_kept","skipped_due_to_orders"],"properties":{"dry_run":{"type":"boolean"},"groups_examined":{"type":"integer","format":"int64","description":"Groups of drafts sharing a title."},"products_deleted":{"type":"integer","format":"int64"},"products_kept":{"type":"integer","format":"int64","description":"One per group: the most recently updated draft."},"skipped_due_to_orders":{"type":"array","items":{"type":"string","format":"uuid"}}}},"DeliveryZone":{"type":"object","description":"A CEP range the store delivers to itself, at a flat price.","required":["id","label","cep_from","cep_to","shipping_cents","is_active","sort_order"],"properties":{"cep_from":{"type":"integer","format":"int64","description":"First CEP of the range, as a number (`1310100` for 01310-100)."},"cep_to":{"type":"integer","format":"int64","description":"Last CEP of the range, inclusive."},"delivery_days":{"type":["integer","null"],"format":"int32"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"label":{"type":"string","description":"What the shopper sees as the freight option's name."},"shipping_cents":{"type":"integer","format":"int64"},"sort_order":{"type":"integer","format":"int32","description":"Sort order, ascending."}}},"DeliveryZoneRequest":{"type":"object","description":"A zone to create.","required":["label","cep_from","cep_to","shipping_cents"],"properties":{"cep_from":{"type":"integer","format":"int64","description":"0 to 99999999."},"cep_to":{"type":"integer","format":"int64","description":"At least `cep_from`."},"delivery_days":{"type":["integer","null"],"format":"int32"},"description":{"type":["string","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"label":{"type":"string"},"shipping_cents":{"type":"integer","format":"int64","description":"0 or more."},"sort_order":{"type":["integer","null"],"format":"int32","description":"Defaults to 0."}}},"DeliveryZoneUpdateRequest":{"type":"object","description":"New values for a zone. `label`, the CEP range and the price are\nrequired; omitted optional fields keep their value, and `null` clears\n`description` or `delivery_days`.","required":["label","cep_from","cep_to","shipping_cents"],"properties":{"cep_from":{"type":"integer","format":"int64","description":"0 to 99999999."},"cep_to":{"type":"integer","format":"int64","description":"At least `cep_from`."},"delivery_days":{"type":["integer","null"],"format":"int32"},"description":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"label":{"type":"string"},"shipping_cents":{"type":"integer","format":"int64","description":"0 or more."},"sort_order":{"type":["integer","null"],"format":"int32"}}},"DeviceSession":{"type":"object","description":"A device the user is signed in on.","required":["id","created_at","last_used_at","expires_at","current"],"properties":{"created_at":{"type":"string","format":"date-time","description":"When the user signed in."},"current":{"type":"boolean","description":"Whether this request was made with this session's access token."},"device_name":{"type":["string","null"],"description":"Name the client gave at sign-in (`device_name`), e.g. \"iPhone de Ana\"."},"expires_at":{"type":"string","format":"date-time","description":"When the session ends unless it is refreshed."},"id":{"type":"string","format":"uuid","description":"Session id; revoke with `DELETE /me/sessions/{session_id}`."},"last_used_at":{"type":"string","format":"date-time","description":"When the session was last refreshed (its sign-in time if never)."},"user_agent":{"type":["string","null"],"description":"`User-Agent` of the last sign-in or refresh."}}},"Disable2FARequest":{"type":"object","description":"Proof that the signed-in user is present before a second factor is\nturned off: the current password, or a current code of that factor.","properties":{"code":{"type":["string","null"],"description":"A current code of the factor being turned off.","example":"123456"},"current_password":{"type":["string","null"]},"totp_code":{"type":["string","null"],"description":"A current authenticator code (`/me/2fa/totp/disable` only).","example":"123456"}}},"DiscountCode":{"type":"object","description":"A discount code.","required":["id","store_id","code","discount_type","value","used_count","is_active","created_at"],"properties":{"code":{"type":"string","description":"What the shopper types. Unique within the store."},"created_at":{"type":"string","format":"date-time"},"discount_type":{"$ref":"#/components/schemas/DiscountType"},"expires_at":{"type":["string","null"],"format":"date-time","description":"Not valid from this instant on."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"min_order_cents":{"type":["integer","null"],"format":"int64","description":"Only valid from this order total up."},"starts_at":{"type":["string","null"],"format":"date-time","description":"Not valid before this instant."},"store_id":{"type":"string","format":"uuid"},"usage_limit":{"type":["integer","null"],"format":"int32","description":"How many orders may use it; null for unlimited."},"used_count":{"type":"integer","format":"int32","description":"Orders that used it so far."},"value":{"type":"integer","format":"int32","description":"Whole percent for `percentage`, cents for `fixed_amount`."}}},"DiscountCodeCreateRequest":{"type":"object","description":"A new discount code.","required":["code","discount_type","value"],"properties":{"code":{"type":"string","description":"1 to 50 characters, unique within the store."},"discount_type":{"$ref":"#/components/schemas/DiscountType"},"expires_at":{"type":["string","null"],"format":"date-time"},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"min_order_cents":{"type":["integer","null"],"format":"int64"},"starts_at":{"type":["string","null"],"format":"date-time"},"usage_limit":{"type":["integer","null"],"format":"int32"},"value":{"type":"integer","format":"int32","description":"Whole percent (0 to 100) for `percentage`, cents for `fixed_amount`."}}},"DiscountCodeRejection":{"type":"string","description":"Why a code does not apply.","enum":["not_found","not_started","expired","below_minimum","usage_limit_reached"]},"DiscountCodeUpdateRequest":{"type":"object","description":"Fields to change. Omitted fields keep their value; for the nullable ones\nan explicit `null` clears them.","properties":{"code":{"type":["string","null"]},"discount_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscountType"}]},"expires_at":{"type":["string","null"],"format":"date-time"},"is_active":{"type":["boolean","null"]},"min_order_cents":{"type":["integer","null"],"format":"int64"},"starts_at":{"type":["string","null"],"format":"date-time"},"usage_limit":{"type":["integer","null"],"format":"int32"},"value":{"type":["integer","null"],"format":"int32"}}},"DiscountCodeValidateRequest":{"type":"object","description":"Check a discount code against an order total.","required":["code","order_total_cents"],"properties":{"code":{"type":"string"},"order_total_cents":{"type":"integer","format":"int64","description":"The order total the code would apply to, in cents."}}},"DiscountCodeValidation":{"type":"object","description":"Whether a code applies, and what it gives.","required":["valid","value"],"properties":{"discount_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscountType","description":"Null when no such code exists."}]},"message":{"type":["string","null"],"description":"Human-readable reason, set when `valid` is false."},"reason":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscountCodeRejection","description":"Set when `valid` is false."}]},"valid":{"type":"boolean"},"value":{"type":"integer","format":"int32","description":"Whole percent or cents, per `discount_type`; 0 when no such code exists."}}},"DiscountPaymentMethod":{"type":"string","description":"The payment method a rule is limited to.","enum":["pix","card"]},"DiscountType":{"type":"string","description":"`percentage` (`value` is a whole percent, 0 to 100) or `fixed_amount`\n(`value` is cents).","enum":["percentage","fixed_amount"]},"DocsAskMessage":{"type":"object","description":"A message of the conversation, as the AI SDK `useChat` sends it.","required":["role","parts"],"properties":{"parts":{"type":"array","items":{"type":"object"},"description":"Message parts; `{ \"type\": \"text\", \"text\": \"...\" }` parts are read,\nothers ignored."},"role":{"type":"string","description":"`user` or `assistant`."}}},"DocsAskRequest":{"type":"object","required":["messages"],"properties":{"locale":{"type":["string","null"],"description":"Docs language the visitor is reading: `pt` (default) or `en`.\nAnswers follow the language of the question.","example":"pt"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/DocsAskMessage"},"description":"The conversation so far, ending with the user's question."}}},"DomainKind":{"type":"string","description":"`platform` (`<slug>.<platform domain>`, managed by us) or `custom`.","enum":["platform","custom"]},"DomainOut":{"type":"object","description":"A hostname the storefront answers on.","required":["id","hostname","kind","verification_failures","is_primary"],"properties":{"cname_target":{"type":["string","null"],"description":"Where the merchant points a CNAME once verified (Cloudflare for SaaS fallback\norigin). `None` on hosts that still route through Traefik by IP."},"dns_challenge":{"type":["string","null"],"description":"The value to publish in a TXT record at `txt_record_name`."},"hostname":{"type":"string","example":"loja.example.com.br"},"id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean","description":"The store's canonical domain (feeds, sitemaps, absolute links)."},"kind":{"$ref":"#/components/schemas/DomainKind"},"last_verification_attempt_at":{"type":["string","null"],"format":"date-time"},"txt_record_name":{"type":["string","null"],"description":"`_bp-verify.<hostname>`."},"verification_failures":{"type":"integer","format":"int32","description":"Consecutive failed checks; the domain is unverified after 5."},"verified_at":{"type":["string","null"],"format":"date-time","description":"When DNS ownership was proven; absent while unverified."}}},"DraftEmailRequest":{"type":"object","required":["prompt"],"properties":{"design":{"type":["object","null"],"description":"Current design to revise (omit to start fresh)."},"prompt":{"type":"string","description":"What the e-mail should say, in the merchant's words."},"subject":{"type":["string","null"]}}},"DuplicateCandidate":{"type":"object","description":"A customer that shares an e-mail or phone with another.","required":["id","total_orders","total_spent","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":["string","null"]},"first_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"last_name":{"type":["string","null"]},"phone":{"type":["string","null"]},"reason":{"type":["string","null"],"description":"What the two customers share: `email` or `phone`. Absent inside a\nduplicate group, whose `reason` says it for every member."},"total_orders":{"type":"integer","format":"int32"},"total_spent":{"type":"integer","format":"int32","description":"Lifetime spend in cents."}}},"DuplicateGroup":{"type":"object","description":"Customers that look like the same person.","required":["reason","key","members"],"properties":{"key":{"type":"string","description":"The shared value: a lowercased e-mail, or the last 9 phone digits."},"members":{"type":"array","items":{"$ref":"#/components/schemas/DuplicateCandidate"},"description":"Oldest first; merge into the first to keep the original record."},"reason":{"type":"string","description":"What the members share: `email` or `phone`."}}},"EmailAbResults":{"type":"object","required":["variants"],"properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/EmailAbVariantResult"}}}},"EmailAbTest":{"type":"object","description":"Subject test: a sample gets A or B, the rest waits for the winner.","properties":{"enabled":{"type":"boolean","default":false},"metric":{"type":"string","description":"`opens` or `clicks`.","default":""},"sample_pct":{"type":"integer","format":"int32","description":"Share of the audience used for the test (both variants together), 10..=50.","default":0,"minimum":0},"subject_b":{"type":"string","default":""},"wait_minutes":{"type":"integer","format":"int32","description":"Minutes to wait before picking the winner.","default":0,"minimum":0}}},"EmailAbVariantResult":{"type":"object","description":"Results of one subject variant.","required":["sent","opened","clicked"],"properties":{"clicked":{"type":"integer","format":"int64"},"opened":{"type":"integer","format":"int64"},"sent":{"type":"integer","format":"int64"},"variant":{"type":["string","null"],"description":"`A`, `B`, or null for recipients sent after the test (the winner)."}}},"EmailActivityEvent":{"type":"object","description":"Something e-mail related that happened to a contact.","required":["kind","at"],"properties":{"at":{"type":"string","format":"date-time"},"broadcast_id":{"type":["string","null"],"format":"uuid"},"detail":{"type":["string","null"],"description":"Subject, link or bounce reason."},"kind":{"type":"string","description":"`sent`, `opened`, `clicked`, `unsubscribed`, or a provider event\n(`delivery`, `bounce`, `complaint`, `reject`, `delay`, `click`)."},"title":{"type":["string","null"],"description":"Campaign name, when it came from a campaign."}}},"EmailAttribution90d":{"type":"object","required":["orders","revenue_cents"],"properties":{"orders":{"type":"integer","format":"int64"},"revenue_cents":{"type":"integer","format":"int64"}}},"EmailAudienceFilter":{"type":"object","description":"Audience filter. All conditions are AND-ed; arrays inside a field\n(lifecycle, tags_any, tags_all) are OR/ALL respectively.\n\nDefault `marketing_opt_in_only=true` keeps us out of GDPR/CASL\ntrouble: only customers who explicitly opted in receive blasts.","properties":{"conditions":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EmailSegmentConditions","description":"Inline conditions (same language as segments)."}]},"customer_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"An explicit list (resend to non-openers, one-off sends)."},"label":{"type":["string","null"],"description":"Human label shown in the campaign list."},"lifecycle":{"type":"array","items":{"type":"string"},"description":"Lifecycle stages (`new`, `active`, `vip`, `at_risk`, `lost`, `lead`), any of."},"marketing_opt_in_only":{"type":"boolean","description":"Only customers who accepted marketing. Defaults to true."},"require_email":{"type":["boolean","null"],"description":"Unused."},"segment_id":{"type":["string","null"],"format":"uuid","description":"A saved segment; its conditions are resolved at send time."},"tags_all":{"type":"array","items":{"type":"string"},"description":"Customers with all of these tags."},"tags_any":{"type":"array","items":{"type":"string"},"description":"Customers with any of these tags."}}},"EmailAudiencePreview":{"type":"object","description":"How many people an audience reaches, with a few of them.","required":["total","sample"],"properties":{"sample":{"type":"array","items":{"$ref":"#/components/schemas/EmailAudienceSample"},"description":"Up to 20 of them."},"total":{"type":"integer","format":"int64","description":"Reachable contacts (opted in when required, valid e-mail, not suppressed)."}}},"EmailAudienceSample":{"type":"object","required":["customer_id","email"],"properties":{"customer_id":{"type":"string","format":"uuid"},"email":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]}}},"EmailBrandKitResponse":{"type":"object","description":"The brand kit e-mails are rendered with.","required":["kit","font_presets"],"properties":{"font_presets":{"type":"array","items":{"type":"object"},"description":"Font stacks the editor offers."},"kit":{"type":"object","description":"Logo, colors, fonts, radius, width, footer, voice and the rest of the\nbrand profile."}}},"EmailBrandKitRevision":{"type":"object","description":"A brand kit revised by the assistant.","required":["kit","notes","patch"],"properties":{"kit":{"type":"object","description":"The whole kit with the patch applied."},"notes":{"type":"string","description":"What changed and why, in Portuguese."},"patch":{"type":"object","description":"Only the fields that changed."}}},"EmailBroadcast":{"type":"object","description":"A campaign: one e-mail sent to an audience.","required":["id","store_id","name","subject","html","audience","status","total_recipients","sent_count","failed_count","opened_count","clicked_count","unsubscribed_count","created_at","updated_at","delivered_count","bounced_count","complained_count","optimize_send_time"],"properties":{"ab_decide_at":{"type":["string","null"],"format":"date-time"},"ab_test":{"type":["object","null"],"description":"The `EmailAbTest` settings, when the campaign tests a second subject."},"ab_winner":{"type":["string","null"],"description":"`A` or `B` once decided."},"audience":{"type":"object","description":"The `EmailAudienceFilter` it was created with."},"bounced_count":{"type":"integer","format":"int32"},"clicked_count":{"type":"integer","format":"int32"},"complained_count":{"type":"integer","format":"int32"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"format":"uuid"},"delivered_count":{"type":"integer","format":"int32"},"design":{"type":["object","null"]},"failed_count":{"type":"integer","format":"int32"},"finished_at":{"type":["string","null"],"format":"date-time"},"html":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"opened_count":{"type":"integer","format":"int32"},"optimize_send_time":{"type":"boolean"},"parent_broadcast_id":{"type":["string","null"],"format":"uuid"},"reply_to":{"type":["string","null"]},"scheduled_at":{"type":["string","null"],"format":"date-time"},"sent_count":{"type":"integer","format":"int32"},"started_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/EmailBroadcastStatus"},"store_id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"template_id":{"type":["string","null"],"format":"uuid"},"text_body":{"type":["string","null"]},"total_recipients":{"type":"integer","format":"int32"},"unsubscribed_count":{"type":"integer","format":"int32"},"updated_at":{"type":"string","format":"date-time"}}},"EmailBroadcastStatus":{"type":"string","description":"Where a campaign is in its life. Documented set; tolerate new values.","enum":["draft","scheduled","sending","testing","sent","cancelled","failed"]},"EmailCampaignAttribution":{"type":"object","description":"Orders by recipients who opened or clicked, placed within `window_days`\nof their send.","required":["orders","revenue_cents","buyers","window_days"],"properties":{"buyers":{"type":"integer","format":"int64"},"orders":{"type":"integer","format":"int64"},"revenue_cents":{"type":"integer","format":"int64"},"window_days":{"type":"integer","format":"int64"}}},"EmailCampaignBounce":{"type":"object","required":["type","count"],"properties":{"count":{"type":"integer","format":"int64"},"type":{"type":"string","description":"Bounce type as the provider reports it."}}},"EmailCampaignFunnel":{"type":"object","required":["total","sent","delivered","opened","clicked","bounced","complained","unsubscribed","failed"],"properties":{"bounced":{"type":"integer","format":"int64"},"clicked":{"type":"integer","format":"int64"},"complained":{"type":"integer","format":"int64"},"delivered":{"type":"integer","format":"int64"},"failed":{"type":"integer","format":"int64"},"opened":{"type":"integer","format":"int64"},"sent":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"Recipients written."},"unsubscribed":{"type":"integer","format":"int64"}}},"EmailCampaignHour":{"type":"object","required":["hour","opens","clicks"],"properties":{"clicks":{"type":"integer","format":"int64"},"hour":{"type":"string","format":"date-time"},"opens":{"type":"integer","format":"int64"}}},"EmailCampaignLink":{"type":"object","required":["url","clicks","unique"],"properties":{"clicks":{"type":"integer","format":"int64"},"unique":{"type":"integer","format":"int64","description":"Distinct recipients who clicked."},"url":{"type":"string"}}},"EmailCampaignRates":{"type":"object","description":"Rates over `sent` (click-to-open over `opened`), 0 to 1.","required":["delivery","open","click","ctor","bounce","complaint","unsubscribe"],"properties":{"bounce":{"type":"number","format":"double"},"click":{"type":"number","format":"double"},"complaint":{"type":"number","format":"double"},"ctor":{"type":"number","format":"double","description":"Clicks over opens."},"delivery":{"type":"number","format":"double"},"open":{"type":"number","format":"double"},"unsubscribe":{"type":"number","format":"double"}}},"EmailCampaignReport":{"type":"object","description":"One campaign in depth.","required":["funnel","rates","timeline","links","bounces","attribution","time_to_open"],"properties":{"attribution":{"$ref":"#/components/schemas/EmailCampaignAttribution"},"bounces":{"type":"array","items":{"$ref":"#/components/schemas/EmailCampaignBounce"}},"funnel":{"$ref":"#/components/schemas/EmailCampaignFunnel"},"links":{"type":"array","items":{"$ref":"#/components/schemas/EmailCampaignLink"},"description":"The 20 most clicked links."},"rates":{"$ref":"#/components/schemas/EmailCampaignRates"},"time_to_open":{"type":"array","items":{"$ref":"#/components/schemas/EmailTimeToOpenBucket"}},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/EmailCampaignHour"},"description":"Opens and clicks per hour over the first 7 days."}}},"EmailChannel":{"type":"object","required":["reachable","opt_in","status"],"properties":{"address":{"type":["string","null"]},"opt_in":{"type":"boolean"},"reachable":{"type":"boolean","description":"Has a deliverable address and marketing consent."},"source":{"type":["string","null"]},"status":{"type":"string","description":"`ok`, `bounced`, `complained` or `unsubscribed`."}}},"EmailConsentSummary":{"type":"object","description":"Where a contact stands for marketing e-mail.","required":["marketing_opt_in","email_status","lead_score","topics"],"properties":{"email_status":{"type":"string","description":"`ok`, `bounced`, `complained` or `unsubscribed`."},"lead_score":{"type":"integer","format":"int32"},"marketing_opt_in":{"type":"boolean"},"opted_in_at":{"type":["string","null"],"format":"date-time"},"source":{"type":["string","null"],"description":"Where the consent came from (`checkout`, `form:<slug>`, `importacao`...)."},"topics":{"type":"array","items":{"type":"string"}}}},"EmailContactImportForm":{"type":"object","description":"The multipart form of a contact import.","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"CSV with a header row, comma or semicolon separated. Columns are\nmatched by name in Portuguese or English (`email`/`e-mail`, `nome`/\n`first_name`, `sobrenome`, `nome_completo`, `telefone`, `tags`,\n`opt_in`/`consentimento`); the e-mail is the key. Up to 20,000 rows."},"opt_in":{"type":["boolean","null"],"description":"Opt contacts in when the CSV has no consent column. Defaults to true;\nsend `false` to import without consent."},"source":{"type":["string","null"],"description":"Consent source recorded for new opt-ins. Defaults to `importacao`."},"tags":{"type":["string","null"],"description":"Comma-separated tags added to every contact."}}},"EmailContactImportResult":{"type":"object","description":"What an import did.","required":["created","updated","skipped","errors"],"properties":{"created":{"type":"integer","format":"int64"},"errors":{"type":"array","items":{"type":"string"},"description":"Up to 10 row errors, and a note when the row limit was hit."},"skipped":{"type":"integer","format":"int64","description":"Rows without a valid e-mail."},"updated":{"type":"integer","format":"int64"}}},"EmailDesignCatalog":{"type":"object","description":"What the block editor can build with.","required":["blocks","starters","variables"],"properties":{"blocks":{"type":"array","items":{"type":"object"},"description":"Block types with their fields."},"starters":{"type":"array","items":{"$ref":"#/components/schemas/EmailDesignStarter"}},"variables":{"type":"array","items":{"$ref":"#/components/schemas/EmailDesignVariable"}}}},"EmailDesignStarter":{"type":"object","required":["id","label","design"],"properties":{"design":{"type":"object"},"id":{"type":"string"},"label":{"type":"string"}}},"EmailDesignVariable":{"type":"object","required":["token","sample"],"properties":{"sample":{"type":"string","description":"What it renders to in previews."},"token":{"type":"string","description":"What to type, e.g. `{{customer.first_name}}`."}}},"EmailDnsRecord":{"type":"object","description":"A DNS record to publish for a sending domain.","required":["type","name","value","purpose"],"properties":{"name":{"type":"string"},"optional":{"type":["boolean","null"],"description":"Recommended, not required for verification."},"purpose":{"type":"string","description":"`DKIM`, `MAIL FROM`, `SPF`, `DMARC (recomendado)`."},"type":{"type":"string","description":"`CNAME`, `MX` or `TXT`."},"value":{"type":"string"}}},"EmailDomain":{"type":"object","description":"A domain the store sends e-mail from (an SES identity).","required":["id","domain","status","dkim_tokens","created_at","dns_records"],"properties":{"created_at":{"type":"string","format":"date-time"},"dkim_status":{"type":["string","null"],"description":"As SES reports it: `PENDING`, `SUCCESS`, `FAILED`..."},"dkim_tokens":{"type":"array","items":{"type":"string"}},"dns_records":{"type":"array","items":{"$ref":"#/components/schemas/EmailDnsRecord"},"description":"What to publish in the domain's DNS, including the store-ownership\n`TXT` record."},"domain":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"mail_from_domain":{"type":["string","null"]},"mail_from_status":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/EmailDomainStatus"},"txt_record_name":{"type":["string","null"],"description":"Name of the ownership `TXT` record (`_bp-email-verify.<domain>`). The\ndomain is verified only once SES verifies it and this record carries\nthe store's challenge."},"verified_at":{"type":["string","null"],"format":"date-time"}}},"EmailDomainStatus":{"type":"string","description":"Verification state of a sending domain.","enum":["pending","verified","failed"]},"EmailDraft":{"type":"object","description":"An e-mail drafted by the assistant.","required":["name","subject","preview_text","design"],"properties":{"design":{"type":"object","description":"Block design, only block types from the catalog."},"name":{"type":"string"},"preview_text":{"type":"string"},"subject":{"type":"string"}}},"EmailForm":{"type":"object","description":"A subscription form.","required":["id","store_id","name","slug","fields","tags","topics","double_opt_in","submissions","is_active","created_at","updated_at","embed"],"properties":{"created_at":{"type":"string","format":"date-time"},"double_opt_in":{"type":"boolean","description":"Ask for confirmation by e-mail before opting in."},"embed":{"$ref":"#/components/schemas/EmailFormEmbed"},"fields":{"type":"array","items":{"type":"object"},"description":"Inputs: `{key, label, type, required}`. `email` is the key field."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"name":{"type":"string"},"redirect_url":{"type":["string","null"],"description":"Where a browser goes after a plain (non-JSON) submit."},"slug":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"submissions":{"type":"integer","format":"int32"},"success_message":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"},"description":"Tags added to the contact."},"topics":{"type":"array","items":{"type":"string"},"description":"Preference-center topics the contact joins."},"updated_at":{"type":"string","format":"date-time"},"welcome_template_id":{"type":["string","null"],"format":"uuid","description":"Template sent once the contact is confirmed."}}},"EmailFormEmbed":{"type":"object","description":"Ready-made embed code for a form.","required":["action","html","js"],"properties":{"action":{"type":"string","description":"Where the form posts (JSON or form-encoded)."},"html":{"type":"string","description":"A plain HTML form."},"js":{"type":"string","description":"A script that submits the form without leaving the page."}}},"EmailFormRequest":{"type":"object","description":"A subscription form's settings.","required":["name"],"properties":{"double_opt_in":{"type":"boolean","description":"Defaults to true."},"fields":{"type":["array","null"],"items":{"type":"object"},"description":"Inputs `{key, label, type, required}`. Defaults to e-mail and first name."},"is_active":{"type":"boolean","description":"Defaults to true."},"name":{"type":"string"},"redirect_url":{"type":["string","null"]},"slug":{"type":["string","null"],"description":"Defaults to the name, slugified."},"success_message":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"welcome_template_id":{"type":["string","null"],"format":"uuid"}}},"EmailHealth":{"type":"object","description":"Deliverability of the store's campaigns over `window_days`.","required":["window_days","sent","delivered","bounced","complained","unsubscribed","opened","bounce_rate","complaint_rate","open_rate","thresholds","suppressed","provider","verified_domains"],"properties":{"account":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SesAccountQuota","description":"The platform's SES quota; null when SES is not reachable."}]},"bounce_rate":{"type":"number","format":"double","description":"Over `sent`, 0 to 1."},"bounced":{"type":"integer","format":"int64"},"complained":{"type":"integer","format":"int64"},"complaint_rate":{"type":"number","format":"double"},"delivered":{"type":"integer","format":"int64"},"open_rate":{"type":"number","format":"double"},"opened":{"type":"integer","format":"int64"},"provider":{"$ref":"#/components/schemas/EmailProvider"},"sent":{"type":"integer","format":"int64"},"suppressed":{"type":"integer","format":"int64","description":"Addresses on the suppression list."},"thresholds":{"$ref":"#/components/schemas/EmailHealthThresholds"},"unsubscribed":{"type":"integer","format":"int64"},"verified_domains":{"type":"array","items":{"type":"string"}},"window_days":{"type":"integer","format":"int64"}}},"EmailHealthThresholds":{"type":"object","required":["bounce_warn","complaint_warn"],"properties":{"bounce_warn":{"type":"number","format":"double","description":"Bounce rate above which to worry (SES reviews accounts at 5%)."},"complaint_warn":{"type":"number","format":"double","description":"Complaint rate above which to worry (0.1%)."}}},"EmailInboxMode":{"type":"string","description":"Where customers' replies go.","enum":["conversas","reply_to"]},"EmailListGrowthWeek":{"type":"object","required":["week","contacts","opt_ins"],"properties":{"contacts":{"type":"integer","format":"int64"},"opt_ins":{"type":"integer","format":"int64"},"week":{"type":"string","format":"date-time"}}},"EmailListHealth":{"type":"object","required":["contacts","reachable","new_opt_ins_30d","unhealthy"],"properties":{"contacts":{"type":"integer","format":"int64","description":"Customers with an e-mail."},"new_opt_ins_30d":{"type":"integer","format":"int64"},"reachable":{"type":"integer","format":"int64","description":"Opted in with a healthy address."},"unhealthy":{"type":"integer","format":"int64","description":"Addresses that bounced, complained or unsubscribed."}}},"EmailOpensByHour":{"type":"object","required":["hour","opens"],"properties":{"hour":{"type":"integer","format":"int32","description":"0 to 23, store time."},"opens":{"type":"integer","format":"int64"}}},"EmailOpensByWeekday":{"type":"object","required":["weekday","opens"],"properties":{"opens":{"type":"integer","format":"int64"},"weekday":{"type":"integer","format":"int32","description":"0 (Sunday) to 6, store time."}}},"EmailOverview":{"type":"object","description":"The store's e-mail marketing at a glance.","required":["list","growth","campaigns","best_hours","best_weekdays","attribution_90d"],"properties":{"attribution_90d":{"$ref":"#/components/schemas/EmailAttribution90d","description":"Orders by engaged recipients within 7 days of a send, last 90 days."},"best_hours":{"type":"array","items":{"$ref":"#/components/schemas/EmailOpensByHour"},"description":"Opens per hour of day over 90 days."},"best_weekdays":{"type":"array","items":{"$ref":"#/components/schemas/EmailOpensByWeekday"}},"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/EmailOverviewCampaign"},"description":"The last 12 sent campaigns."},"growth":{"type":"array","items":{"$ref":"#/components/schemas/EmailListGrowthWeek"},"description":"New contacts per week over 12 weeks."},"list":{"$ref":"#/components/schemas/EmailListHealth"}}},"EmailOverviewCampaign":{"type":"object","required":["id","name","sent","delivered","opened","clicked","bounced","unsubscribed","open_rate","click_rate"],"properties":{"bounced":{"type":"integer","format":"int32"},"click_rate":{"type":"number","format":"double"},"clicked":{"type":"integer","format":"int32"},"delivered":{"type":"integer","format":"int32"},"finished_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"open_rate":{"type":"number","format":"double"},"opened":{"type":"integer","format":"int32"},"sent":{"type":"integer","format":"int32"},"unsubscribed":{"type":"integer","format":"int32"}}},"EmailProductCard":{"type":"object","description":"A product as e-mail blocks show it.","required":["id","product_id","title","slug","url","price","image_url"],"properties":{"id":{"type":"string","format":"uuid"},"image_url":{"type":"string","description":"Empty when the product has no photo."},"price":{"type":"string","description":"Formatted price (`R$ 89,90`), empty when unknown."},"product_id":{"type":"string","format":"uuid","description":"Same as `id`."},"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","description":"Product page on the storefront."}}},"EmailProvider":{"type":"string","description":"Who sends the store's e-mail.","enum":["platform","ses","resend"]},"EmailRecipient":{"type":"object","description":"One recipient of a campaign.","required":["id","broadcast_id","store_id","email","status","open_count","click_count","created_at"],"properties":{"broadcast_id":{"type":"string","format":"uuid"},"click_count":{"type":"integer","format":"int32"},"clicked_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"customer_id":{"type":["string","null"],"format":"uuid"},"email":{"type":"string"},"error_message":{"type":["string","null"]},"first_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"last_clicked_at":{"type":["string","null"],"format":"date-time"},"last_name":{"type":["string","null"]},"last_opened_at":{"type":["string","null"],"format":"date-time"},"open_count":{"type":"integer","format":"int32"},"opened_at":{"type":["string","null"],"format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/EmailRecipientStatus"},"store_id":{"type":"string","format":"uuid"},"unsubscribed_at":{"type":["string","null"],"format":"date-time"}}},"EmailRecipientStatus":{"type":"string","description":"Delivery state of one recipient. Documented set; tolerate new values.","enum":["pending","sending","sent","delivered","failed","bounced","complained","suppressed"]},"EmailSegment":{"type":"object","description":"A saved segment.","required":["id","name","conditions","created_at","updated_at","member_count"],"properties":{"conditions":{"$ref":"#/components/schemas/EmailSegmentConditions"},"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"member_count":{"type":"integer","format":"int64","description":"Matching customers with an e-mail, counted now."},"name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"EmailSegmentConditions":{"type":"object","description":"A segment's rules.","properties":{"match":{"oneOf":[{"$ref":"#/components/schemas/EmailSegmentMatch","description":"`all` (AND, the default) or `any` (OR)."}],"default":"all"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/EmailSegmentRule"},"default":[]}}},"EmailSegmentField":{"type":"object","description":"A field segments can filter on.","required":["field","label","kind","ops"],"properties":{"field":{"type":"string"},"kind":{"type":"string","description":"How to edit the value: `bool`, `number`, `money` (reais), `days`,\n`text`, `list`, `tags`, `products`, `categories` or `choice`."},"label":{"type":"string"},"ops":{"type":"array","items":{"type":"string"}},"options":{"type":["array","null"],"items":{"type":"string"},"description":"Allowed values for `choice` fields."}}},"EmailSegmentMatch":{"type":"string","description":"How a segment's rules combine.","enum":["all","any"]},"EmailSegmentMember":{"type":"object","description":"A customer matching a segment.","required":["customer_id","total_orders","total_spent","marketing_opt_in"],"properties":{"customer_id":{"type":"string","format":"uuid"},"email":{"type":["string","null"]},"email_status":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"last_order_at":{"type":["string","null"],"format":"date-time"},"marketing_opt_in":{"type":"boolean"},"tags":{"type":["array","null"],"items":{"type":"string"}},"total_orders":{"type":"integer","format":"int32"},"total_spent":{"type":"integer","format":"int32"}}},"EmailSegmentPreview":{"type":"object","description":"Who a set of rules matches right now.","required":["count","with_email","reachable","sample"],"properties":{"count":{"type":"integer","format":"int64","description":"Matching customers."},"reachable":{"type":"integer","format":"int64","description":"Of those, opted in with a healthy address."},"sample":{"type":"array","items":{"$ref":"#/components/schemas/EmailSegmentMember"},"description":"Up to 8 of them."},"with_email":{"type":"integer","format":"int64","description":"Of those, with an e-mail."}}},"EmailSegmentRequest":{"type":"object","description":"A segment's name and rules.","required":["name","conditions"],"properties":{"conditions":{"$ref":"#/components/schemas/EmailSegmentConditions"},"description":{"type":["string","null"]},"name":{"type":"string"}}},"EmailSegmentRule":{"type":"object","description":"One condition: a field, an operator and a value, from the field catalog\n(`GET .../email/segments/fields`).","properties":{"field":{"type":"string","description":"e.g. `total_orders`, `last_order`, `tags`.","default":""},"op":{"type":"string","description":"One of the field's `ops`, e.g. `gte`, `within_days`, `any`.","default":""},"value":{"oneOf":[{"$ref":"#/components/schemas/EmailSegmentRuleValue","description":"A number, a string, a boolean or a list of strings, per the field's `kind`."}]}}},"EmailSegmentRuleValue":{"oneOf":[{"type":"boolean"},{"type":"number","format":"double"},{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"A rule's value; its type follows the field's `kind`."},"EmailSendCap":{"type":"object","description":"Today's send cap.","required":["sent_today","source","exhausted"],"properties":{"exhausted":{"type":"boolean","description":"Over the cap: more sends wait until tomorrow."},"limit":{"type":["integer","null"],"format":"int64","description":"Marketing e-mails allowed today; null when unlimited."},"sent_today":{"type":"integer","format":"int64"},"source":{"type":"string","description":"`manual` (pinned in the settings), `warmup` (new SES domain) or `none`."},"warmup_day":{"type":["integer","null"],"format":"int64","description":"Day of the warm-up, from 1."}}},"EmailSettings":{"type":"object","description":"The store's e-mail sending settings. The Resend API key never leaves the\nserver: reads only say whether one is set.","required":["resend_configured","provider","topics","inbox_mode","inbox_available"],"properties":{"from_email":{"type":["string","null"]},"from_name":{"type":["string","null"]},"inbox_available":{"type":"boolean","description":"Whether this deployment has the platform inbox at all."},"inbox_mode":{"$ref":"#/components/schemas/EmailInboxMode"},"provider":{"$ref":"#/components/schemas/EmailProvider"},"reply_address":{"type":["string","null"],"description":"The platform reply address used when `inbox_mode` is `conversas`."},"reply_to":{"type":["string","null"]},"resend_configured":{"type":"boolean","description":"A Resend API key is stored."},"topics":{"type":"array","items":{"type":"string"},"description":"Topics offered in the subscriber preference center."}}},"EmailSuppression":{"type":"object","description":"An address the store never e-mails.","required":["id","email","reason","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":"string"},"id":{"type":"string","format":"uuid"},"reason":{"type":"string","description":"`bounce`, `complaint`, `unsubscribe` or `manual`."},"source":{"type":["string","null"],"description":"Who added it (`admin`, `ses`, `link`...)."}}},"EmailTemplate":{"type":"object","description":"A marketing e-mail template.","required":["id","store_id","name","subject","html","is_active","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"format":"uuid"},"design":{"type":["object","null"],"description":"Block design the editor works on; `html` is compiled from it when present."},"html":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"name":{"type":"string"},"preview_text":{"type":["string","null"]},"reply_to":{"type":["string","null"]},"store_id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"text_body":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}},"EmailTimeToOpenBucket":{"type":"object","required":["bucket","count"],"properties":{"bucket":{"type":"string","description":"`1h`, `6h`, `24h`, `3d` or `later`."},"count":{"type":"integer","format":"int64"}}},"EnableTotpRequest":{"type":"object","required":["totp_code"],"properties":{"totp_code":{"type":"string","description":"A current code from the authenticator app, proving it was set up.","example":"123456"}}},"EraseReq":{"type":"object","properties":{"reason":{"type":["string","null"],"description":"Free-text reason kept in the audit trail (e.g. ticket number)."}}},"EraseResult":{"type":"object","required":["erased","skipped"],"properties":{"erased":{"type":"array","items":{"type":"string"},"description":"Tables whose personal data was removed or scrubbed."},"skipped":{"type":"array","items":{"type":"string"},"description":"Tables skipped because they do not exist on this deployment."}}},"ErpHealthChecks":{"type":"object","required":["has_access_token","can_fetch_account_info"],"properties":{"can_fetch_account_info":{"type":"boolean","description":"Tiny's `/info` answered with success."},"has_access_token":{"type":"boolean"},"provider_status":{"type":["integer","null"],"format":"int32","description":"Tiny's HTTP status for `/info`, when it was called.","minimum":0}}},"ErpImportStarted":{"type":"object","description":"A background job accepted.","required":["status","job_id","message"],"properties":{"job_id":{"type":"string","format":"uuid","description":"The sync log that tracks the job (`getErpSyncLog`)."},"message":{"type":"string"},"status":{"type":"string","description":"Always `accepted`."}}},"ErpProvider":{"type":"object","description":"An ERP connection of the store. Secrets in `config_json` (OAuth app\nsecret, access and refresh tokens) come back masked.","required":["id","store_id","name","code","config_json","is_active","is_default","created_at","updated_at"],"properties":{"code":{"type":"string","description":"The integration's code in the capability registry, e.g. `tiny_erp`."},"config_json":{"type":"object","description":"Connection settings; the fields depend on `code`."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_default":{"type":"boolean"},"name":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"ErpProviderCreateRequest":{"type":"object","required":["name","code"],"properties":{"code":{"type":"string","description":"The integration's code, e.g. `tiny_erp`."},"config_json":{"type":["object","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"is_default":{"type":["boolean","null"],"description":"Makes it the store's default ERP (unsetting the others). Defaults to\nfalse."},"name":{"type":"string"}}},"ErpProviderHealth":{"type":"object","required":["provider_code","healthy","status","checks"],"properties":{"checks":{"$ref":"#/components/schemas/ErpHealthChecks"},"healthy":{"type":"boolean"},"provider_body":{"type":["string","null"],"description":"Tiny's error body when `/info` failed."},"provider_code":{"type":"string"},"status":{"$ref":"#/components/schemas/ErpProviderStatus"}}},"ErpProviderStatus":{"type":"object","description":"Connection and sync state kept for an ERP provider.","required":["connected","needs_reauth","webhook_configured"],"properties":{"auto_sync_interval_minutes":{"type":["integer","null"],"format":"int64","description":"Minutes between scheduled syncs, from the provider's settings."},"connected":{"type":"boolean","description":"Holds an access or refresh token."},"last_error":{"type":["string","null"]},"last_error_at":{"type":["string","null"],"format":"date-time"},"last_sync_at":{"type":["string","null"],"format":"date-time"},"last_sync_status":{"type":["string","null"]},"needs_reauth":{"type":"boolean","description":"The refresh token stopped working: authorize again."},"token_expires_at":{"type":["string","null"]},"token_refreshed_at":{"type":["string","null"],"format":"date-time"},"webhook_configured":{"type":"boolean"},"webhook_url":{"type":["string","null"],"description":"The stock webhook URL (with its secret) to paste into Tiny."}}},"ErpProviderUpdateRequest":{"type":"object","description":"Fields to change; omitted ones stay.","properties":{"config_json":{"type":["object","null"],"description":"Merged into the stored settings. Masked placeholders sent back\nunchanged keep the stored secret."},"is_active":{"type":["boolean","null"]},"is_default":{"type":["boolean","null"]},"name":{"type":["string","null"]}}},"ErpSyncLog":{"type":"object","description":"One run of an ERP sync or import.","required":["id","trigger","started_at","running","total_fetched","synced_count","kit_count","component_count","skipped_count","error_count"],"properties":{"component_count":{"type":"integer","format":"int32"},"details":{"type":["object","null"],"description":"Per-item outcomes and errors."},"error_count":{"type":"integer","format":"int32"},"finished_at":{"type":["string","null"],"format":"date-time","description":"Null while running. A run that stalls for 30 minutes is closed as\nfailed (`details.stalled`)."},"id":{"type":"string","format":"uuid"},"kit_count":{"type":"integer","format":"int32"},"running":{"type":"boolean"},"skipped_count":{"type":"integer","format":"int32"},"started_at":{"type":"string","format":"date-time"},"synced_count":{"type":"integer","format":"int32"},"total_fetched":{"type":"integer","format":"int32"},"trigger":{"type":"string","description":"`manual`, `auto`, `webhook` or `import`."}}},"ErpSyncPreview":{"type":"object","description":"What a dry-run sync would change.","required":["trigger","dry_run","location_id","total_fetched","synced_count","kit_count","component_count","skipped_count","error_count","errors"],"properties":{"component_count":{"type":"integer","format":"int64"},"dry_run":{"type":"boolean"},"error_count":{"type":"integer","minimum":0},"errors":{"type":"array","items":{"type":"object"},"description":"Per-item problems, as Tiny and the matcher reported them."},"kit_count":{"type":"integer","format":"int64"},"location_id":{"type":"string","format":"uuid"},"skipped_count":{"type":"integer","format":"int64"},"synced_count":{"type":"integer","format":"int64"},"total_fetched":{"type":"integer","format":"int64"},"trigger":{"type":"string","description":"`manual`."}}},"ErpSyncStarted":{"type":"object","description":"A background sync accepted.","required":["started","message"],"properties":{"message":{"type":"string"},"started":{"type":"boolean"}}},"ErrorResponse":{"type":"object","description":"Canonical error body. Every error response from the API has this shape,\nwhatever produced it: handlers that build an [`ApiError`], the older\nhelpers below, bare status codes and axum's own rejections (the last two\nare rewritten by `common::api::normalize_errors`).\n\n`error` stays the human-readable message so consumers written against\nthe original `{\"error\": \"...\"}` body keep working; `code` is the stable,\nmachine-readable part clients should branch on.","required":["error","code"],"properties":{"code":{"type":"string","description":"Stable snake_case identifier for the failure, e.g. `not_found`,\n`validation_failed`, `discount_code_expired`.","example":"not_found"},"details":{"type":["object","null"],"description":"Structured context for the failure, such as per-field validation\nmessages. Shape depends on `code`."},"error":{"type":"string","description":"Human-readable message. Wording may change; do not match on it.","example":"Order not found"}}},"EventRow":{"allOf":[{"$ref":"#/components/schemas/StoredEvent"},{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EventStatus"}}}]},"EventStatus":{"type":"string","description":"Where an event is in delivery.","enum":["dispatched","pending","failed"]},"ExportFile":{"type":"object","description":"A file of the active deployment.","required":["path","content_base64"],"properties":{"content_base64":{"type":"string"},"path":{"type":"string"}}},"FieldOption":{"type":"object","required":["value","label"],"properties":{"label":{"type":"string"},"value":{"type":"string"}}},"FieldType":{"type":"string","enum":["text","password","boolean","select","multi_select","number","file"]},"FireWorkflowRequest":{"type":"object","properties":{"customer_id":{"type":["string","null"],"format":"uuid","description":"Run for this customer (of the store); otherwise the run has no\ncustomer."},"dry_run":{"type":"boolean","description":"Simulate: steps with side effects describe instead of act. Always on\nfor a workflow that was never published."},"payload":{"type":["object","null"],"description":"Surfaces in the run as `trigger_payload`."}}},"FreightCancelReason":{"type":"object","description":"A reason the carrier accepts for cancelling an order.","required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"FreightCargoType":{"type":"object","description":"A cargo type Central do Frete quotes for.","required":["id","name"],"properties":{"cargo_type_id":{"type":["integer","null"],"format":"int64"},"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"FreightProvider":{"type":"object","description":"A carrier integration of the store.","required":["id","store_id","name","code","config_json","is_active","is_default","created_at","updated_at"],"properties":{"code":{"type":"string","description":"The registry module, e.g. `central_do_frete`."},"config_json":{"type":"object","description":"Module settings. Secret values come back as `__stored__`; send that\nplaceholder back to keep the stored secret."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_default":{"type":"boolean","description":"The store's primary carrier."},"name":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"FreightProviderCreateRequest":{"type":"object","description":"A new freight provider.","required":["name","code"],"properties":{"code":{"type":"string","description":"The registry module, e.g. `central_do_frete`."},"config_json":{"type":["object","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"is_default":{"type":["boolean","null"],"description":"Defaults to false. Setting it clears the previous default."},"name":{"type":"string"}}},"FreightProviderHealth":{"type":"object","description":"Whether a provider has every setting it needs.","required":["provider_code","healthy","checks"],"properties":{"checks":{"type":"object","description":"Per-setting presence, e.g. `{\"has_token\": true}`."},"healthy":{"type":"boolean","description":"Every required setting is present."},"provider_code":{"type":"string"}}},"FreightProviderUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value. `config_json` is\nmerged into the stored settings, and `__stored__` values are ignored.","properties":{"config_json":{"type":["object","null"]},"is_active":{"type":["boolean","null"]},"is_default":{"type":["boolean","null"],"description":"`true` makes it the default and clears the previous one."},"name":{"type":["string","null"]}}},"FreightSettings":{"type":"object","description":"Defaults of the store's Central do Frete integration, for pre-filling\nthe carrier order form.","required":["origin_postal_code"],"properties":{"default_cargo_types":{"type":["array","null"],"items":{"type":"integer","format":"int64"}},"origin_postal_code":{"type":"string"},"sender_complement":{"type":["string","null"]},"sender_number":{"type":["string","null"]}}},"FulfillmentMode":{"type":"string","enum":["stocked","on_demand","stocked_or_on_demand"]},"GenerateBrandSystemRequest":{"type":"object","description":"Sources to generate the brand system from.","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/BrandAttachment"},"description":"Text files (CSS, markdown, brand notes) read client-side; up to\n60 000 characters each, 200 000 in all."},"from_kit":{"type":"boolean","description":"Start from the current e-mail brand kit instead (no crawl, no AI):\nsaves at once and answers 200."},"notes":{"type":"string","description":"Free notes about the brand."},"urls":{"type":"array","items":{"type":"string"},"description":"Pages to crawl for styles, logos and copy, and GitHub repositories\n(`https://github.com/owner/repo`) to read. Defaults to the\nstorefront when empty."}}},"GenerateRecipient":{"type":"object","description":"Who receives the goods, for the carrier order.","required":["document","name"],"properties":{"address_complement":{"type":["string","null"]},"address_number":{"type":["string","null"]},"document":{"type":"string","description":"CPF/CNPJ."},"email":{"type":["string","null"]},"name":{"type":"string"},"phone":{"type":["string","null"]}}},"GenerateShipmentRequest":{"type":"object","description":"The carrier order to create from a quote.","required":["quotation_code","price_id","freight_payer","collect_here","sign_exemption_term","cce_issued","recipient"],"properties":{"carrier_name":{"type":["string","null"]},"cce_issued":{"type":"boolean"},"collect_here":{"type":"boolean","description":"The carrier collects at the store."},"cost_cents":{"type":["integer","null"],"format":"int64","description":"The chosen option's price."},"freight_payer":{"type":"string","description":"`CIF` (store pays) or `FOB` (recipient pays). Anything else is CIF."},"price_id":{"type":"integer","format":"int64","description":"The chosen option's `option_id`."},"quotation_code":{"type":"string"},"recipient":{"$ref":"#/components/schemas/GenerateRecipient"},"schedule_collect":{"type":["string","null"],"description":"Collection date (`YYYY-MM-DD`)."},"sender_complement":{"type":["string","null"]},"sender_number":{"type":["string","null"]},"sign_exemption_term":{"type":"boolean"}}},"GithubInstallUrl":{"type":"object","required":["install_url"],"properties":{"install_url":{"type":"string","description":"Send the browser here (top-level navigation) to install the GitHub\nApp; GitHub then returns the user to the admin."}}},"GraphCustomer":{"type":"object","description":"The customer's own fields, with order aggregates.","required":["id","total_orders","total_spent","created_at","marketing_opt_in","whatsapp_opt_in","lead_score"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":["string","null"]},"first_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"last_name":{"type":["string","null"]},"last_order_at":{"type":["string","null"],"format":"date-time"},"lead_score":{"type":"integer","format":"int32"},"marketing_opt_in":{"type":"boolean"},"phone":{"type":["string","null"]},"total_orders":{"type":"integer","format":"int32"},"total_spent":{"type":"integer","format":"int32","description":"Lifetime spend in cents."},"whatsapp_opt_in":{"type":"boolean"}}},"GroupWithFields":{"allOf":[{"$ref":"#/components/schemas/SpecGroup"},{"type":"object","required":["fields"],"properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/SpecField"}}}}]},"Identity":{"type":"object","description":"One way the customer is known: an e-mail, phone, WhatsApp number,\nstorefront account or browser visitor id.","required":["kind","value","verified","first_seen_at","last_seen_at"],"properties":{"first_seen_at":{"type":"string","format":"date-time"},"kind":{"type":"string","description":"`email`, `phone`, `whatsapp`, `account` or `visitor`."},"last_seen_at":{"type":"string","format":"date-time"},"source":{"type":["string","null"],"description":"Where the identity was learned (`checkout`, `whatsapp`, `import`, ...)."},"value":{"type":"string"},"verified":{"type":"boolean"}}},"ImageUploadResponse":{"type":"object","description":"The stored image and its public URL.","required":["image","upload_url"],"properties":{"image":{"$ref":"#/components/schemas/ProductImageWithVariants"},"upload_url":{"type":"string"}}},"ImageVariant":{"type":"object","description":"A resized rendition of a product image.","required":["id","product_image_id","variant_name","file_path","mime_type","file_size_bytes","created_at"],"properties":{"cdn_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"file_path":{"type":"string"},"file_size_bytes":{"type":"integer","format":"int32"},"height":{"type":["integer","null"],"format":"int32"},"id":{"type":"string","format":"uuid"},"mime_type":{"type":"string"},"product_image_id":{"type":"string","format":"uuid"},"quality":{"type":["integer","null"],"format":"int32"},"variant_name":{"type":"string","description":"e.g. `thumbnail_jpeg`, `medium_webp`."},"width":{"type":["integer","null"],"format":"int32"}}},"ImportEmailBrandKitRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Public page to read colors, fonts and logo from (`https://` assumed)."}}},"InboxNotification":{"type":"object","description":"A log entry with the caller's read state.","required":["id","store_id","channel_name","channel_type","event","message","status","sent_at"],"properties":{"channel_name":{"type":"string","description":"See `NotificationLog.channel_name`."},"channel_type":{"type":"string"},"error":{"type":["string","null"]},"event":{"type":"string","description":"Event name, e.g. `orders.paid`."},"id":{"type":"string","format":"uuid"},"message":{"type":"string"},"read_at":{"type":["string","null"],"format":"date-time","description":"When I marked it read; null while unread."},"sent_at":{"type":"string","format":"date-time"},"status":{"type":"string","description":"`sent`, `failed`, `skipped` or `pending`."},"store_id":{"type":"string","format":"uuid"}}},"InstallationStatus":{"type":"object","description":"The store's GitHub connection.","required":["configured"],"properties":{"account_login":{"type":["string","null"]},"account_type":{"type":["string","null"],"description":"`User` or `Organization`."},"configured":{"type":"boolean","description":"Whether the server has GitHub App credentials at all."},"default_branch":{"type":["string","null"]},"installation_id":{"type":["integer","null"],"format":"int64"},"platform_url":{"type":["string","null"],"description":"Public URL the storefront is reachable at, or None if\n`PRODUCTION_DOMAIN_SUFFIX` isn't configured."},"repo_full_name":{"type":["string","null"]},"repo_id":{"type":["integer","null"],"format":"int64"}}},"InventoryLocation":{"type":"object","description":"A place stock is kept: a warehouse, a shop's back room, a supplier's\nconsignment shelf.","required":["id","store_id","name","is_active","created_at","updated_at"],"properties":{"address":{"type":["string","null"],"description":"Address as free text."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean","description":"Inactive locations take no new stock."},"location_type":{"type":["string","null"],"description":"Free-form kind, `warehouse` by default (e.g. `store`, `dropship`)."},"name":{"type":"string"},"priority":{"type":["integer","null"],"format":"int32","description":"Lower comes first. The active location with the lowest priority is\nthe store's default: stock writes that name no location go there."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"InventoryLocationCreateRequest":{"type":"object","required":["name"],"properties":{"address":{"type":["string","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"location_type":{"type":["string","null"],"description":"Defaults to `warehouse`."},"name":{"type":"string"},"priority":{"type":["integer","null"],"format":"int32","description":"Defaults to 100."}}},"InventoryLocationUpdateRequest":{"type":"object","description":"Fields to change; omitted ones stay.","properties":{"address":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"location_type":{"type":["string","null"]},"name":{"type":["string","null"]},"priority":{"type":["integer","null"],"format":"int32"}}},"InventoryModeResponse":{"type":"object","required":["inventory_mode"],"properties":{"inventory_mode":{"type":"string","description":"The module now active."}}},"InviteStatus":{"type":"string","description":"Where an invite stands.","enum":["pending","accepted","cancelled","expired"]},"Invoice":{"type":"object","description":"An invoice for a period of the Mobiari subscription.","required":["id","tenant_id","plan_code","billing_cycle","amount_cents","period_start","period_end","due_at","status","provider","created_at"],"properties":{"amount_cents":{"type":"integer","format":"int64","description":"BRL cents."},"billing_cycle":{"$ref":"#/components/schemas/BillingCycle"},"created_at":{"type":"string","format":"date-time"},"due_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"paid_at":{"type":["string","null"],"format":"date-time"},"payment_url":{"type":["string","null"],"description":"A payment page, when the provider hosts one."},"period_end":{"type":"string","format":"date-time"},"period_start":{"type":"string","format":"date-time"},"pix_copy_paste":{"type":["string","null"],"description":"Pix \"copia e cola\" to pay the invoice from any bank app."},"plan_code":{"type":"string"},"provider":{"type":"string"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"tenant_id":{"type":"string","format":"uuid"}}},"InvoiceStatus":{"type":"string","description":"Where an invoice stands. `void` invoices were replaced (plan change) or\nwithdrawn (subscription ended) and are never charged.","enum":["open","paid","void"]},"KbArticle":{"type":"object","description":"A knowledge base article.","required":["id","title","body_md","status","created_at","updated_at"],"properties":{"body_md":{"type":"string","description":"Markdown."},"collection_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"index_error":{"type":["string","null"]},"indexed_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/KbArticleStatus"},"title":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"KbArticleStatus":{"type":"string","enum":["draft","published"]},"KbArticleSummary":{"type":"object","description":"An article in a list (without its body).","required":["id","title","status","chunk_count","updated_at"],"properties":{"chunk_count":{"type":"integer","format":"int64","description":"Indexed passages."},"collection_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"index_error":{"type":["string","null"]},"indexed_at":{"type":["string","null"],"format":"date-time","description":"When the bot's index last picked it up. Null while (re)indexing."},"status":{"$ref":"#/components/schemas/KbArticleStatus"},"title":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"KbCollection":{"type":"object","description":"A group of knowledge base articles.","required":["id","name","description","position","article_count"],"properties":{"article_count":{"type":"integer","format":"int64"},"description":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"position":{"type":"integer","format":"int32"}}},"KbCollectionRequest":{"type":"object","required":["name"],"properties":{"description":{"type":"string"},"name":{"type":"string"},"position":{"type":["integer","null"],"format":"int32","description":"Defaults to after the last collection."}}},"KbReindexResult":{"type":"object","required":["queued"],"properties":{"queued":{"type":"integer","description":"Published articles queued for indexing.","minimum":0}}},"KbSearchHit":{"type":"object","description":"A knowledge base passage matching a question.","required":["article_id","title","chunk_index","content","score"],"properties":{"article_id":{"type":"string","format":"uuid"},"chunk_index":{"type":"integer","format":"int32","description":"Position of the passage in the article."},"content":{"type":"string","description":"The passage, with its neighbours."},"score":{"type":"number","format":"double","description":"Relevance; higher is better. Only comparable within one search."},"title":{"type":"string","description":"The article's title."}}},"KbSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string"}}},"KbSearchResult":{"type":"object","required":["hits","embeddings_configured"],"properties":{"embeddings_configured":{"type":"boolean","description":"Whether semantic ranking took part (else full-text only)."},"hits":{"type":"array","items":{"$ref":"#/components/schemas/KbSearchHit"},"description":"The passages the bot would read, best first (at most six)."}}},"Kit":{"type":"object","description":"A variant with a bill of materials.","required":["variant_id","product_id","sku","name","product_name","line_count","buildable","open_builds"],"properties":{"buildable":{"type":"integer","format":"int32","description":"Kits buildable right now: the minimum over the lines of\n`available / quantity_required`."},"line_count":{"type":"integer","format":"int32"},"name":{"type":"string"},"open_builds":{"type":"integer","format":"int32","description":"Units on queued or running build jobs."},"product_id":{"type":"string","format":"uuid"},"product_name":{"type":"string"},"sku":{"type":"string"},"variant_id":{"type":"string","format":"uuid"}}},"Level":{"type":"string","description":"Coarse level a code belongs to inside its group. The picker offers\nNone / Read / Write / Manage per group; Read ⊂ Write ⊂ Manage.","enum":["read","write","manage"]},"LinkRepoRequest":{"type":"object","required":["repo_id","repo_full_name","default_branch"],"properties":{"default_branch":{"type":"string"},"repo_full_name":{"type":"string"},"repo_id":{"type":"integer","format":"int64"}}},"Locale":{"type":"string","description":"A language the admin and alerts are available in.","enum":["pt-BR","en-US"]},"LoginRequest":{"type":"object","required":["email","password"],"properties":{"device_name":{"type":["string","null"],"description":"A name for this device, shown in the user's session list\n(`GET /me/sessions`), e.g. \"iPhone de Ana\"."},"email":{"type":"string","example":"ana@example.com"},"password":{"type":"string"}}},"LoginResponse":{"oneOf":[{"$ref":"#/components/schemas/LoginResponseAuthenticated"},{"$ref":"#/components/schemas/LoginResponseTwoFactorRequired"}],"description":"Outcome of a password sign-in, told apart by `status`.","discriminator":{"propertyName":"status","mapping":{"authenticated":"#/components/schemas/LoginResponseAuthenticated","two_factor_required":"#/components/schemas/LoginResponseTwoFactorRequired"}}},"LoginResponseAuthenticated":{"allOf":[{"$ref":"#/components/schemas/Session","description":"Signed in."},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["authenticated"]}}}],"description":"Signed in."},"LoginResponseTwoFactorRequired":{"allOf":[{"$ref":"#/components/schemas/TwoFactorChallenge","description":"A second factor is required."},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["two_factor_required"]}}}],"description":"A second factor is required."},"LogoutRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","description":"The session's current refresh token."}}},"LookupMatch":{"type":"string","description":"What a lookup code matched.","enum":["sku","barcode","product_gtin"]},"ManualPaymentMethod":{"type":"string","description":"How a counter sale is paid.","enum":["cash","pix","bank_transfer","card_terminal","pix_qr"]},"ManualSaleFreight":{"type":"object","description":"Freight picked at the counter. The POS quotes without a cart\n(`/freight/simulate`), so the chosen option travels with the sale; the\nprice is operator-supplied like a line price override.","required":["shipping_cents","destination_postal_code"],"properties":{"carrier_name":{"type":["string","null"]},"delivery_days":{"type":["integer","null"],"format":"int32"},"destination_postal_code":{"type":"string","description":"CEP, 8 digits (formatting ignored)."},"option_id":{"type":["string","null"]},"provider_code":{"type":["string","null"],"description":"`central_do_frete`, `local_delivery`, ... Blank means a hand-typed\nprice the store delivers itself."},"quotation_code":{"type":["string","null"],"description":"Carrier quotation code, when the option came from a carrier quote.\nLets the shipment dialog skip straight to generating a label."},"service_name":{"type":["string","null"]},"shipping_cents":{"type":"integer","format":"int64","description":"0 to 10,000,000."}}},"ManualSaleItem":{"type":"object","description":"A line of a counter sale.","required":["variant_id","quantity"],"properties":{"quantity":{"type":"integer","format":"int32","description":"At least 1."},"unit_price_cents":{"type":["integer","null"],"format":"int64","description":"Price override in cents; the variant's price when omitted."},"variant_id":{"type":"string","format":"uuid"}}},"ManualSalePix":{"type":"object","description":"The PIX charge of a `pix_qr` sale, to show as a QR code.","required":["intent_id"],"properties":{"expires_at":{"type":["string","null"],"format":"date-time"},"intent_id":{"type":"string","format":"uuid"},"qr_code":{"type":["string","null"],"description":"PIX copy-and-paste code."},"qr_code_base64":{"type":["string","null"],"description":"PNG of the QR code, base64."}}},"ManualSaleRequest":{"type":"object","description":"A sale taken at the counter.","required":["items","payment_method"],"properties":{"amount_received_cents":{"type":["integer","null"],"format":"int64","description":"Cents handed over, to compute the change (cash)."},"customer_id":{"type":["string","null"],"format":"uuid"},"discount_code":{"type":["string","null"],"description":"A discount code of the store, valid now."},"freight":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ManualSaleFreight","description":"Freight chosen at the counter for a sale that ships."}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/ManualSaleItem"}},"manual_discount_cents":{"type":["integer","null"],"format":"int64","description":"Negotiated discount in cents, stacked on the discount code and\nrecorded in `discount_cents` (not hidden in line prices)."},"notes":{"type":["string","null"]},"payment_method":{"$ref":"#/components/schemas/ManualPaymentMethod"},"sales_channel_id":{"type":["string","null"],"format":"uuid"}}},"ManualSaleResponse":{"type":"object","description":"The sale just recorded.","required":["order_id","order_number","total_cents","shipping_cents","change_cents"],"properties":{"change_cents":{"type":"integer","format":"int64","description":"`amount_received_cents - total_cents`, never negative."},"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"pix":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ManualSalePix","description":"Only for `pix_qr`: poll `GET .../orders/{order_id}/payments` until\nan intent is `approved`."}]},"shipping_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"}}},"MarketingConfig":{"type":"object","description":"The store's ad-platform tracking setup. Secrets (access tokens, OAuth\ncredentials) are write-only: they show as `*_configured` flags.","required":["meta_capi_configured","meta_ads_token_configured","meta_catalog_configured","google_ads_configured"],"properties":{"google_ads_configured":{"type":"boolean","description":"Google Ads developer token and OAuth refresh token are both stored."},"google_ads_conversion_action_id":{"type":["string","null"]},"google_ads_conversion_id":{"type":["string","null"],"description":"Conversion id for the browser tag (`AW-...`)."},"google_ads_conversion_label":{"type":["string","null"]},"google_ads_customer_id":{"type":["string","null"]},"meta_ad_account_id":{"type":["string","null"]},"meta_ads_token_configured":{"type":"boolean","description":"A token for reading ad spend is stored (the CAPI token counts)."},"meta_capi_configured":{"type":"boolean","description":"A Conversions API access token is stored."},"meta_catalog_configured":{"type":"boolean","description":"Catalog id and catalog access token are both stored."},"meta_catalog_id":{"type":["string","null"]},"meta_pixel_id":{"type":["string","null"],"description":"Meta pixel the storefront loads."},"meta_test_event_code":{"type":["string","null"],"description":"Test event code: CAPI events show under \"Test events\" in Meta."}}},"MarketingInsights":{"type":"object","description":"Revenue by traffic source over a window.","required":["from","to","touch","total_orders","total_revenue_cents","attributed_orders","attributed_revenue_cents","rows"],"properties":{"attributed_orders":{"type":"integer","format":"int64","description":"Orders with attribution recorded."},"attributed_revenue_cents":{"type":"integer","format":"int64"},"from":{"type":"string","format":"date-time"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AttributionRow"},"description":"One row per source / medium / campaign, highest revenue first."},"to":{"type":"string","format":"date-time"},"total_orders":{"type":"integer","format":"int64","description":"Paid or fulfilled orders created in the window, attributed or not."},"total_revenue_cents":{"type":"integer","format":"int64"},"touch":{"$ref":"#/components/schemas/AttributionTouch"}}},"MarketingStats":{"type":"object","description":"Storefront traffic over a window.","required":["from","to","visitors","sessions","pageviews","custom_events","identifies","conversions","conversion_revenue_cents","avg_pages_per_session"],"properties":{"avg_pages_per_session":{"type":"number","format":"double","description":"Pageviews per session."},"conversion_revenue_cents":{"type":"integer","format":"int64"},"conversions":{"type":"integer","format":"int64","description":"Paid or fulfilled orders attributed to a tracked visitor."},"custom_events":{"type":"integer","format":"int64","description":"Events other than pageviews and identifies."},"from":{"type":"string","format":"date-time"},"identifies":{"type":"integer","format":"int64","description":"Visitors identified (e-mail or phone typed on the storefront)."},"pageviews":{"type":"integer","format":"int64"},"sessions":{"type":"integer","format":"int64"},"to":{"type":"string","format":"date-time"},"visitors":{"type":"integer","format":"int64","description":"Distinct visitors (tracker cookie)."}}},"MediaFile":{"type":"object","description":"A file of the library.","required":["id","tenant_id","name","filename","file_path","mime_type","file_size_bytes","is_public","uploaded_by","created_at","updated_at"],"properties":{"alt_text":{"type":["string","null"]},"cdn_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"file_path":{"type":"string"},"file_size_bytes":{"type":"integer","format":"int64"},"filename":{"type":"string","description":"Stored filename; `/images/{size}/{filename}` serves images."},"folder_id":{"type":["string","null"],"format":"uuid","description":"Null for a file at the root."},"height":{"type":["integer","null"],"format":"int32"},"id":{"type":"string","format":"uuid"},"is_public":{"type":"boolean"},"mime_type":{"type":"string"},"name":{"type":"string","description":"Display name."},"original_name":{"type":["string","null"],"description":"The name it was uploaded with."},"store_id":{"type":["string","null"],"format":"uuid"},"tags":{"type":["array","null"],"items":{"type":"string"}},"tenant_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"updated_by":{"type":["string","null"],"format":"uuid"},"uploaded_by":{"type":"string","format":"uuid"},"width":{"type":["integer","null"],"format":"int32"}}},"MediaFileTree":{"type":"object","description":"Every folder of the tenant and, unless `include_files=false`, every\nfile.","required":["folders","files"],"properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/MediaFileWithMeta"},"description":"By name."},"folders":{"type":"array","items":{"$ref":"#/components/schemas/MediaFolder"},"description":"By path."}}},"MediaFileUpdateRequest":{"type":"object","description":"Fields to change. Omitted fields keep their value; `folder_id: null`\nmoves the file to the root.","properties":{"alt_text":{"type":["string","null"]},"folder_id":{"type":["string","null"],"format":"uuid"},"name":{"type":["string","null"]}}},"MediaFileUpload":{"type":"object","description":"The stored file and its public URL.","required":["file","upload_url"],"properties":{"file":{"$ref":"#/components/schemas/MediaFileWithVariants"},"upload_url":{"type":"string"}}},"MediaFileUploadForm":{"type":"object","description":"The multipart form of a file upload.","required":["file"],"properties":{"alt_text":{"type":["string","null"]},"description":{"type":["string","null"]},"file":{"type":"string","format":"binary","description":"The file. Images (JPEG, PNG, WebP) up to 10 MB get resized\nrenditions; anything else is stored as-is, up to 50 MB."},"folder_id":{"type":["string","null"],"format":"uuid"},"is_public":{"type":["boolean","null"]},"name":{"type":["string","null"],"description":"Display name; defaults to the uploaded filename."},"tags":{"type":["string","null"],"description":"Comma-separated."}}},"MediaFileVariant":{"type":"object","description":"A stored rendition of a file (resized image).","required":["id","file_id","variant_name","file_path","mime_type","file_size_bytes","created_at"],"properties":{"cdn_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"file_id":{"type":"string","format":"uuid"},"file_path":{"type":"string"},"file_size_bytes":{"type":"integer","format":"int32"},"height":{"type":["integer","null"],"format":"int32"},"id":{"type":"string","format":"uuid"},"mime_type":{"type":"string"},"quality":{"type":["integer","null"],"format":"int32"},"variant_name":{"type":"string","description":"e.g. `thumbnail_jpeg`, `medium_webp`."},"width":{"type":["integer","null"],"format":"int32"}}},"MediaFileWithMeta":{"allOf":[{"$ref":"#/components/schemas/MediaFile"},{"type":"object","required":["is_starred","usage_count"],"properties":{"is_starred":{"type":"boolean","description":"Starred by the current user."},"usage_count":{"type":"integer","format":"int64","description":"Products whose gallery uses the file."}}}],"description":"A file with what the current user sees about it."},"MediaFileWithVariants":{"allOf":[{"$ref":"#/components/schemas/MediaFile"},{"type":"object","required":["variants"],"properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/MediaFileVariant"}}}}],"description":"A file with its renditions."},"MediaFolder":{"type":"object","description":"A folder of the file library.","required":["id","tenant_id","name","is_system","position","created_by","created_at","updated_at"],"properties":{"color":{"type":["string","null"],"description":"`#RRGGBB`."},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","format":"uuid"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_system":{"type":"boolean","description":"Folders the platform created; not meant to be renamed."},"name":{"type":"string"},"parent_id":{"type":["string","null"],"format":"uuid","description":"Null for a top-level folder."},"path":{"type":["string","null"],"description":"Slash-separated path from the root, kept in sync on rename."},"position":{"type":"integer","format":"int32"},"store_id":{"type":["string","null"],"format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"updated_by":{"type":["string","null"],"format":"uuid"}}},"MediaFolderCreateRequest":{"type":"object","description":"A new folder.","required":["name"],"properties":{"color":{"type":["string","null"],"description":"`#RRGGBB`."},"description":{"type":["string","null"]},"name":{"type":"string"},"parent_id":{"type":["string","null"],"format":"uuid","description":"A folder of the tenant; omit for a top-level folder."}}},"MediaFolderUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value. Renaming updates the\npaths of the folder and everything under it.","properties":{"color":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"position":{"type":["integer","null"],"format":"int32"}}},"MemberRole":{"type":"object","required":["id","name"],"properties":{"color":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"MergeReq":{"type":"object","required":["from_customer_id"],"properties":{"from_customer_id":{"type":"string","format":"uuid","description":"The duplicate to fold into the customer in the path. It is deleted."}}},"MergeResult":{"type":"object","required":["into","removed","tables"],"properties":{"into":{"type":"string","format":"uuid","description":"The customer that remains."},"removed":{"type":"string","format":"uuid","description":"The customer that was merged in and deleted."},"tables":{"type":"integer","description":"How many tables had rows repointed.","minimum":0}}},"MessageDeliveryStatus":{"type":"string","description":"Delivery of an outbound (agent or bot) message. On WhatsApp it follows\nMeta's status callbacks: `sent` (accepted), `delivered` (on the phone),\n`read`, or `failed` with `delivery_error`. On the web widget `read` means\nthe visitor opened the chat. Messages from the contact stay `sent`.\nTolerate unknown values.","enum":["sent","delivered","read","failed"]},"MetaAdsDay":{"type":"object","description":"One day of Meta ad account insights.","required":["day","spend","impressions","clicks","meta_purchases","meta_purchase_value"],"properties":{"clicks":{"type":"integer","format":"int64"},"day":{"type":"string","description":"`YYYY-MM-DD`."},"impressions":{"type":"integer","format":"int64"},"meta_purchase_value":{"type":"number","format":"double"},"meta_purchases":{"type":"number","format":"double"},"spend":{"type":"number","format":"double","description":"In the ad account's currency (reais), as Meta reports it."}}},"MetaAdsInsights":{"type":"object","required":["configured","series","spend"],"properties":{"configured":{"type":"boolean","description":"False when Meta is not connected or the query failed (see `error`)."},"error":{"type":["string","null"]},"series":{"type":"array","items":{"$ref":"#/components/schemas/MetaAdsDay"}},"spend":{"type":"number","format":"double","description":"Total spend over the window."}}},"MetaAttributedOrders":{"type":"object","description":"Orders whose first touch points at Meta (utm_source facebook/instagram/\nmeta, or an fbclid).","required":["orders","revenue_cents","series"],"properties":{"orders":{"type":"integer","format":"int64"},"revenue_cents":{"type":"integer","format":"int64"},"series":{"type":"array","items":{"$ref":"#/components/schemas/AttributedOrdersDay"}}}},"MetaCatalogSyncResult":{"type":"object","description":"What a catalog sync pushed.","required":["pushed"],"properties":{"pushed":{"type":"integer","description":"Variants sent to Meta.","minimum":0},"result":{"type":["object","null"],"description":"Meta's batch response; null when there was nothing to push."}}},"ModuleField":{"type":"object","required":["key","label","type","required","secret"],"properties":{"default":{"type":["string","null"],"description":"Written into `config_json` when the module is first created, so a\nprovider row is never missing a value the driver needs."},"help":{"type":["string","null"]},"key":{"type":"string"},"label":{"type":"string"},"options":{"type":"array","items":{"$ref":"#/components/schemas/FieldOption"}},"options_path":{"type":["string","null"],"description":"For [`FieldType::MultiSelect`]: path (relative to this module's provider\nrow) serving the choices as `[{ id, name }]`. Keeping the lookup in the\nspec means the admin fetches a provider's own vocabulary without\nknowing which provider it is."},"placeholder":{"type":["string","null"]},"required":{"type":"boolean"},"secret":{"type":"boolean","description":"Masked whenever the config is read back — never returned in the clear."},"type":{"$ref":"#/components/schemas/FieldType"}}},"ModuleKind":{"type":"string","enum":["native","integration"]},"MovementKind":{"type":"string","description":"What kind of stock movement a ledger entry records:\n\n- `stock_in` / `stock_out`: goods received (a purchase receipt, an\n  opening balance) or removed outside an order.\n- `reserve` / `release` / `consume`: an order or build job holding units,\n  letting them go, or shipping them.\n- `adjustment`: a manual correction (with a `reason`), or the undo of an\n  earlier movement.\n- `transfer`: units moving between two locations (one entry per side).\n- `count`: the difference a posted stock count wrote.\n- `build_consume` / `build_produce`: parts used and kits made by a build.\n\nMirrors `inventory_events_type_check`. The set may grow; tolerate\nunknown values.","enum":["stock_in","stock_out","reserve","release","consume","adjustment","transfer","count","build_consume","build_produce"]},"MovementReferenceType":{"type":"string","description":"The document a movement came from.","enum":["order","cart","purchase_receipt","stock_count","transfer","erp_sync","reversal"]},"MyAccess":{"type":"object","description":"Every store the signed-in user can reach.","required":["user_id","stores"],"properties":{"stores":{"type":"array","items":{"$ref":"#/components/schemas/StoreAccess"},"description":"By store name. Group by `tenant_id` for a tenant/store switcher."},"user_id":{"type":"string","format":"uuid"}}},"NotificationChannel":{"type":"object","description":"A store notification channel (customer-facing automations).","required":["id","store_id","name","channel_type","config_json","enabled_events","is_enabled","locale","created_at","updated_at"],"properties":{"channel_type":{"$ref":"#/components/schemas/NotificationChannelType"},"config_json":{"type":"object","description":"Channel settings, keys per `channel_type`. Secrets read as\n`__stored__`; send that value back to keep them."},"created_at":{"type":"string","format":"date-time"},"enabled_events":{"type":"array","items":{"type":"string"},"description":"Events this channel handles: `cart.abandoned`, `order.review_request`."},"id":{"type":"string","format":"uuid"},"is_enabled":{"type":"boolean"},"locale":{"type":"string","description":"Language of the messages (`pt-BR`, `en-US`)."},"name":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"NotificationChannelType":{"type":"string","description":"How a channel delivers.","enum":["email","whatsapp","telegram","webhook","sms"]},"NotificationLog":{"type":"object","description":"One message sent (or attempted) through a store channel, a team alert\nor a member's own alert channel.","required":["id","store_id","channel_name","channel_type","event","message","status","sent_at"],"properties":{"channel_id":{"type":["string","null"],"format":"uuid","description":"The store channel it went through; null for team and member alerts."},"channel_name":{"type":"string","description":"The channel's name, or `team:<user id>` / `platform:<channel type>`\nfor alerts."},"channel_type":{"type":"string","description":"`email`, `whatsapp`, `telegram`, `webhook`, `sms`."},"error":{"type":["string","null"]},"event":{"type":"string","description":"Event name, e.g. `orders.paid`, `cart.abandoned`, `channel.test`."},"id":{"type":"string","format":"uuid"},"message":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"status":{"type":"string","description":"`sent`, `failed`, `skipped` or `pending`."},"store_id":{"type":"string","format":"uuid"}}},"NotificationUnreadCount":{"type":"object","required":["unread"],"properties":{"unread":{"type":"integer","format":"int64","description":"Inbox entries I have not marked read."}}},"OnboardingChecklist":{"type":"object","description":"The store's setup checklist.","required":["steps","completed","total"],"properties":{"completed":{"type":"integer","format":"int64"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/OnboardingStep"}},"total":{"type":"integer","format":"int64"}}},"OnboardingStep":{"type":"object","required":["key","done"],"properties":{"done":{"type":"boolean"},"key":{"$ref":"#/components/schemas/OnboardingStepKey"}}},"OnboardingStepKey":{"type":"string","description":"A setup step, in the order the checklist suggests.","enum":["products","payments","freight","brand","whatsapp","team","domain","first_order"]},"OptionGroup":{"type":"object","description":"A product option such as Color or Size.","required":["id","product_id","name","position","group_type"],"properties":{"group_type":{"$ref":"#/components/schemas/OptionGroupType"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"position":{"type":"integer","format":"int32"},"product_id":{"type":"string","format":"uuid"}}},"OptionGroupCreateRequest":{"type":"object","description":"A new option group.","required":["name"],"properties":{"group_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OptionGroupType","description":"Defaults to `text`."}]},"name":{"type":"string"},"position":{"type":["integer","null"],"format":"int32","description":"Defaults to 0."}}},"OptionGroupType":{"type":"string","description":"How an option group's values render: plain text or color swatches.","enum":["text","color"]},"OptionGroupUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value.","properties":{"group_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OptionGroupType"}]},"name":{"type":["string","null"]},"position":{"type":["integer","null"],"format":"int32"}}},"OptionGroupWithValues":{"allOf":[{"$ref":"#/components/schemas/OptionGroup"},{"type":"object","required":["values"],"properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}}}],"description":"An option group with its values, in display order."},"OptionValue":{"type":"object","description":"One value of an option group, e.g. Blue.","required":["id","option_group_id","value","position","color_is_custom"],"properties":{"color_base_name":{"type":["string","null"],"description":"For `color` groups: the base color name used for filtering and for\nthe swatch when there is no custom hex."},"color_hex":{"type":["string","null"],"description":"For `color` groups with `color_is_custom`: `#RRGGBB`, or up to\nseveral joined by `/` for multi-color swatches. Null otherwise."},"color_is_custom":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"option_group_id":{"type":"string","format":"uuid"},"position":{"type":"integer","format":"int32"},"value":{"type":"string"}}},"OptionValueCreateRequest":{"type":"object","description":"A new option value. The color fields only apply to `color` groups.","required":["value"],"properties":{"color_base_name":{"type":["string","null"],"description":"Defaults to `value`."},"color_hex":{"type":["string","null"],"description":"Required when `color_is_custom` is true: `#RRGGBB` or `RRGGBB`,\nseveral separated by `/`, `,`, `&` or `|`."},"color_is_custom":{"type":["boolean","null"]},"position":{"type":["integer","null"],"format":"int32"},"value":{"type":"string"}}},"OptionValueUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value.","properties":{"color_base_name":{"type":["string","null"],"description":"An empty string resets it to the value's name."},"color_hex":{"type":["string","null"]},"color_is_custom":{"type":["boolean","null"]},"position":{"type":["integer","null"],"format":"int32"},"value":{"type":["string","null"]}}},"Order":{"type":"object","description":"An order with everything its screen shows: items with images, customer\nand address, money, payment, fulfillment, shipments with tracking and\nrefunds.","required":["id","store_id","status","allowed_status_transitions","is_test","currency","subtotal_cents","discount_cents","shipping_cents","tax_cents","total_cents","refunded_cents","refundable_cents","fulfillment_method","has_nfe","has_pending_builds","items","shipments","refunds","created_at","updated_at"],"properties":{"allowed_status_transitions":{"type":"array","items":{"$ref":"#/components/schemas/OrderStatus"},"description":"What `PATCH .../status` accepts from the current status. Empty on\nterminal orders."},"cancelled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string","description":"ISO 4217 currency of every `*_cents` amount."},"customer_document":{"type":["string","null"],"description":"CPF/CNPJ on the customer profile (digits)."},"customer_email":{"type":["string","null"]},"customer_id":{"type":["string","null"],"format":"uuid"},"customer_name":{"type":["string","null"],"description":"Customer name, or the checkout contact's for guests."},"customer_phone":{"type":["string","null"]},"danfe_url":{"type":["string","null"]},"discount_cents":{"type":"integer","format":"int64"},"freight_external_order_code":{"type":["string","null"]},"freight_provider_code":{"type":["string","null"]},"freight_quote_id":{"type":["string","null"],"format":"uuid"},"freight_snapshot_json":{"type":["object","null"],"description":"The freight quote as selected at checkout (provider-specific)."},"freight_status":{"type":["string","null"]},"fulfillment_method":{"type":"string","description":"`shipping` or `pickup`."},"fulfillment_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OrderFulfillmentStatus"}]},"has_nfe":{"type":"boolean","description":"The NFe XML is attached (the XML itself is never returned)."},"has_pending_builds":{"type":"boolean","description":"Some line is still being made."},"id":{"type":"string","format":"uuid"},"is_test":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"next_build_ready_at":{"type":["string","null"],"format":"date-time","description":"Earliest promised production date among the lines."},"nf_value_cents":{"type":["integer","null"],"format":"int64"},"nfe_key":{"type":["string","null"],"description":"Nota fiscal access key (44 digits)."},"nfe_number":{"type":["string","null"]},"notes":{"type":["string","null"],"description":"Free text from the counter sale."},"number":{"type":["string","null"],"description":"Per-store sequential number (`#1234`). Null on legacy orders."},"payer_document":{"type":["string","null"],"description":"CPF/CNPJ the payer used (e.g. `CPF 12345678901`), from the latest\npayment. Use it for the nota fiscal; guests only have this one."},"payment_expires_at":{"type":["string","null"],"format":"date-time","description":"When the latest payment attempt stops being payable (PIX codes)."},"payment_intent_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaymentIntentStatus","description":"Status of the latest payment attempt."}]},"payment_method":{"type":["string","null"],"description":"Method of the latest payment attempt: `pix`, `card`, `cash`,\n`bank_transfer` or `card_terminal`."},"payment_provider_code":{"type":["string","null"],"description":"Gateway of the latest payment attempt (`mercado_pago`, `manual`)."},"payment_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OrderPaymentStatus"}]},"pickup_location_id":{"type":["string","null"],"format":"uuid"},"pickup_location_snapshot_json":{"type":["object","null"],"description":"The pickup point as it was when the order was placed."},"placed_at":{"type":["string","null"],"format":"date-time"},"refundable_cents":{"type":"integer","format":"int64","description":"What `POST .../refund` can still return: the latest approved payment\nminus its refunds. 0 when nothing can be refunded online."},"refunded_cents":{"type":"integer","format":"int64","description":"Refunded so far through the payment provider."},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"},"description":"Refunds, newest first."},"sales_channel_id":{"type":["string","null"],"format":"uuid"},"shipments":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"},"description":"Shipments, oldest first, with their contents and tracking."},"shipping_cents":{"type":"integer","format":"int64"},"shipping_contact":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ShippingContact","description":"Delivery contact and address typed at checkout."}]},"shipping_option":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OrderShippingOption","description":"The chosen shipping option, when the order ships."}]},"status":{"$ref":"#/components/schemas/OrderStatus"},"store_id":{"type":"string","format":"uuid"},"subtotal_cents":{"type":"integer","format":"int64"},"tax_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"},"updated_at":{"type":"string","format":"date-time"}}},"OrderFulfillmentStatus":{"type":"string","description":"Where the goods are, derived from the order's shipments: `unfulfilled`\n(nothing out), `partially_fulfilled` (some units out, or all out and\nnot all delivered), `fulfilled` (every unit delivered), `cancelled`.","enum":["unfulfilled","partially_fulfilled","fulfilled","cancelled"]},"OrderHit":{"type":"object","required":["id","status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"customer_email":{"type":["string","null"]},"customer_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"number":{"type":["string","null"]},"status":{"type":"string"},"total_cents":{"type":["integer","null"],"format":"int64"}}},"OrderItem":{"type":"object","description":"One line of an order.","required":["id","order_id","product_id","variant_id","title","quantity","unit_price_cents","total_cents"],"properties":{"build_quantity":{"type":["integer","null"],"format":"int32","description":"Units being made to order."},"build_status":{"type":["string","null"],"description":"Production state of the most advanced open batch: `queued`,\n`in_progress`, `ready` or `cancelled`. Null when nothing is built."},"expected_ready_at":{"type":["string","null"],"format":"date-time","description":"Latest promised production date."},"id":{"type":"string","format":"uuid"},"image_url":{"type":["string","null"],"description":"Variant image, falling back to the product's primary image: an\nabsolute URL, or a path on the API host."},"order_id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","format":"int32"},"reserved_quantity":{"type":["integer","null"],"format":"int32","description":"Units held from stock."},"shipped_quantity":{"type":["integer","null"],"format":"int32","description":"Units already out in a shipment."},"sku":{"type":["string","null"]},"title":{"type":"string"},"total_cents":{"type":"integer","format":"int64","description":"`unit_price_cents * quantity`."},"unit_price_cents":{"type":"integer","format":"int64"},"variant_id":{"type":"string","format":"uuid"}}},"OrderItemAdjustment":{"type":"object","description":"A note of money added to or taken off one order line (a repair, a\ncourtesy discount). Recorded for the team; it does not change the\norder's totals.","required":["id","order_item_id","adjustment_type","created_at"],"properties":{"adjustment_type":{"type":"string","description":"Free-form kind, e.g. `discount` or `surcharge`."},"amount_cents":{"type":["integer","null"],"format":"int64","description":"Signed amount in cents."},"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"order_item_id":{"type":"string","format":"uuid"}}},"OrderListStatus":{"type":"string","description":"The `status` filter of the order list: a superset of `OrderStatus`.\n\nEvery `OrderStatus` value filters on the order's status; the two extra\nvalues are the fulfillment tabs `processing` (paid, nothing shipped)\nand `shipped` (some or all units out). They never appear as an order's\n`status`.","enum":["draft","pending","paid","fulfilled","cancelled","refunded","processing","shipped"]},"OrderNfe":{"type":"object","description":"The order's nota fiscal. The XML itself is never returned (it can be\nlarge and is only needed server-side for freight orders); `has_nfe`\nsays whether it is present.","required":["has_nfe"],"properties":{"danfe_url":{"type":["string","null"]},"has_nfe":{"type":"boolean"},"nf_value_cents":{"type":["integer","null"],"format":"int64","description":"Invoice total from the XML."},"nfe_key":{"type":["string","null"],"description":"44-digit access key."},"nfe_number":{"type":["string","null"]}}},"OrderPaymentStatus":{"type":"string","description":"Where the money is. Follows the payment provider; `PATCH .../status`\ndoes not change it.\n\n`pending` (not paid yet), `authorized` (held, not captured), `captured`\n(paid), `partially_refunded`, `refunded`, `failed`.","enum":["pending","authorized","captured","partially_refunded","refunded","failed"]},"OrderPayments":{"type":"object","description":"An order's payment attempts, gateway events and refunds.","required":["order_id","intents","events","refunds"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/PaymentEvent"},"description":"Newest first, at most 100."},"intents":{"type":"array","items":{"$ref":"#/components/schemas/PaymentIntent"},"description":"Newest first."},"order_id":{"type":"string","format":"uuid"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"},"description":"Newest first."}}},"OrderShipmentLine":{"type":"object","description":"One line of an order, with ordered vs shipped units: the shipments board\nshows which products left without fetching each order.","required":["title","quantity","shipped"],"properties":{"quantity":{"type":"integer","format":"int32","description":"Units ordered."},"shipped":{"type":"integer","format":"int32","description":"Units in shipments that have left (`ordered` through `delivered`)."},"sku":{"type":["string","null"]},"title":{"type":"string"}}},"OrderShippingOption":{"type":"object","description":"The shipping option the customer (or the counter) chose, read from the\nfreight snapshot.","properties":{"carrier_name":{"type":["string","null"]},"delivery_days":{"type":["integer","null"],"format":"int32"},"destination_postal_code":{"type":["string","null"]},"service_name":{"type":["string","null"]},"shipping_cents":{"type":["integer","null"],"format":"int64"}}},"OrderStatus":{"type":"string","description":"Where an order is in its lifecycle.\n\n| Status | Meaning |\n| --- | --- |\n| `draft` | Being put together (quotes); not yet placed. |\n| `pending` | Placed, waiting for payment. |\n| `paid` | Paid; goods not all delivered yet. |\n| `fulfilled` | Every unit delivered (set by the shipments) or closed by hand. |\n| `cancelled` | Cancelled; reservations released. Terminal. |\n| `refunded` | Money returned. Terminal. |\n\nShipping progress is not an order status: read `fulfillment_status` and\nthe order's shipments.","enum":["draft","pending","paid","fulfilled","cancelled","refunded"]},"OrderSummary":{"type":"object","description":"An order as a list row: status, customer, totals, a thumbnail and unit\ncounts. Fetch the order for items, addresses, payments and shipments.","required":["id","store_id","status","currency","subtotal_cents","discount_cents","shipping_cents","tax_cents","total_cents","item_count","ordered_units","shipped_units","shipment_items","fulfillment_method","is_test","has_nfe","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string","description":"ISO 4217 currency of every `*_cents` amount."},"customer_email":{"type":["string","null"],"description":"Customer e-mail, or the e-mail typed at checkout for guests."},"customer_id":{"type":["string","null"],"format":"uuid"},"customer_name":{"type":["string","null"],"description":"Customer name, or the name typed at checkout for guests."},"discount_cents":{"type":"integer","format":"int64"},"first_item_image":{"type":["string","null"],"description":"Image of the first line: an absolute URL, or a path on the API host."},"first_item_title":{"type":["string","null"],"description":"Title of the first line, for a one-line description."},"freight_provider_code":{"type":["string","null"]},"freight_status":{"type":["string","null"]},"fulfillment_method":{"type":"string","description":"`shipping` or `pickup`."},"fulfillment_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OrderFulfillmentStatus"}]},"has_nfe":{"type":"boolean","description":"A nota fiscal XML is attached."},"id":{"type":"string","format":"uuid"},"is_test":{"type":"boolean","description":"Test orders are hidden from the list unless `include_test=true`."},"item_count":{"type":"integer","format":"int64","description":"Order lines."},"number":{"type":["string","null"],"description":"Per-store sequential number, shown as `#1234`. Null on orders that\npredate numbering; fall back to the id."},"ordered_units":{"type":"integer","format":"int64","description":"Units ordered across all lines."},"payment_expires_at":{"type":["string","null"],"format":"date-time","description":"When the latest payment attempt stops being payable (PIX codes)."},"payment_intent_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaymentIntentStatus","description":"Status of the latest payment attempt. A `pending` order whose\nlatest attempt is `expired` will not be paid without a new charge."}]},"payment_status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OrderPaymentStatus"}]},"shipment_items":{"type":"array","items":{"$ref":"#/components/schemas/OrderShipmentLine"},"description":"Per-line ordered vs shipped units."},"shipped_units":{"type":"integer","format":"int64","description":"Units that have left in a shipment, capped per line at the ordered\nquantity."},"shipping_cents":{"type":"integer","format":"int64"},"status":{"$ref":"#/components/schemas/OrderStatus"},"store_id":{"type":"string","format":"uuid"},"subtotal_cents":{"type":"integer","format":"int64"},"tax_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"},"updated_at":{"type":"string","format":"date-time"}}},"OrdersTotal":{"type":"object","required":["orders","revenue_cents"],"properties":{"orders":{"type":"integer","format":"int64"},"revenue_cents":{"type":"integer","format":"int64"}}},"OtpSendRequest":{"type":"object","required":["challenge"],"properties":{"challenge":{"type":"string","description":"`challenge` from `POST /auth/login`."}}},"OtpSendResponse":{"type":"object","required":["delivered_to","expires_in_seconds"],"properties":{"delivered_to":{"type":"string","description":"The masked destination, e.g. `***4321`."},"expires_in_seconds":{"type":"integer","format":"int64","example":300}}},"Page_AdAudience":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdAudience"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_AlertSubscription":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertSubscription"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ApiTokenSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiTokenSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_AssignedShippingBox":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssignedShippingBox"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_AssistantAction":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssistantAction"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_AssistantConversation":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssistantConversation"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_AssistantLinkedPhone":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssistantLinkedPhone"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_AuditEvent":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_AutomaticDiscount":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomaticDiscount"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_BomLine":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BomLine"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_BuildJob":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BuildJob"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_CannedReply":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CannedReply"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_CartSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CartSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Category":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_CmsCollection":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CmsCollection"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_CmsDocument":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CmsDocument"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Collection":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_CollectionProductEntry":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CollectionProductEntry"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Component":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Component"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ComponentCandidate":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComponentCandidate"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ComponentUsage":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComponentUsage"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ConnectedProduct":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedProduct"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ConversationChannel":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationChannel"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ConversationListItem":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationListItem"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ConversationMessage":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ConversationVariantHit":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationVariantHit"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ConversionDelivery":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversionDelivery"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Customer":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_CustomerAddress":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerAddress"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_CustomerInteraction":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerInteraction"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_DeliveryZone":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZone"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_DeviceSession":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeviceSession"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_DiscountCode":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DiscountCode"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_DomainOut":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DomainOut"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_DuplicateGroup":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DuplicateGroup"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailBroadcast":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailBroadcast"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailDomain":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailDomain"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailForm":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailForm"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailProductCard":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailProductCard"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailRecipient":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailRecipient"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailSegment":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailSegment"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailSegmentMember":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailSegmentMember"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailSuppression":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailSuppression"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EmailTemplate":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailTemplate"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ErpProvider":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ErpProvider"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ErpSyncLog":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ErpSyncLog"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_EventRow":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventRow"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_FreightCancelReason":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FreightCancelReason"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_FreightProvider":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FreightProvider"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_InboxNotification":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxNotification"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_InventoryLocation":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLocation"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Invoice":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_KbArticleSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KbArticleSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_KbCollection":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KbCollection"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Kit":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Kit"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_MediaFile":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MediaFile"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_NotificationChannel":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationChannel"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_NotificationLog":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationLog"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_OptionGroupWithValues":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionGroupWithValues"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_OptionValue":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_OrderItemAdjustment":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemAdjustment"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_OrderSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_PaymentProvider":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentProvider"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Prediction":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Prediction"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ProductFeed":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductFeed"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ProductFeedOverride":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductFeedOverride"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ProductImageWithVariants":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductImageWithVariants"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ProductListItem":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductListItem"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ProductSlugRedirect":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductSlugRedirect"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ProductSubscription":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductSubscription"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ProductVariant":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_PurchaseOrder":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_PushDevice":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PushDevice"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_QuoteSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/QuoteSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Refund":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_RepoSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RepoSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Reservation":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reservation"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ReviewWithProduct":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReviewWithProduct"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_RoleAuditEntry":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleAuditEntry"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_SalesChannel":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SalesChannel"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Shipment":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_ShippingBox":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingBox"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StockCount":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockCount"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StockListItem":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockListItem"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StockMovement":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Store":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Store"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StoreInvite":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreInvite"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StoreLocation":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreLocation"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StoreMember":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreMember"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StoreRole":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreRole"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StoreWorkflowRun":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreWorkflowRun"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StorefrontDeployment":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontDeployment"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_StorefrontPage":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontPage"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_String":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"type":"string"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_SuggestedProduct":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SuggestedProduct"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Supplier":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_TaxonomyCategory":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyCategory"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Tenant":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tenant"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_TimelineEvent":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_TopEvent":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopEvent"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_TopPage":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopPage"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_TopReferrer":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopReferrer"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_TrackedEvent":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrackedEvent"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_TransactionalEmailSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransactionalEmailSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_UnshippedItem":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UnshippedItem"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_User":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_VisitorSummary":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VisitorSummary"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_Webhook":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_WebhookDelivery":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_WebhookEventRow":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventRow"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_WorkflowListItem":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowListItem"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_WorkflowRun":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRun"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_WorkflowSecret":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowSecret"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"Page_WorkflowVersion":{"type":"object","description":"A page of results.","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowVersion"},"description":"The rows on this page, in the endpoint's documented order."},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."},"total":{"type":["integer","null"],"format":"int64","description":"Count of every matching row. Only present with `include_total=true`."}}},"ParsedAddress":{"type":"object","description":"Normalized address, shape-agnostic so every admin form can map from it.","required":["street","number","neighborhood","city","state","postal_code","country","line1","formatted_address"],"properties":{"city":{"type":"string"},"country":{"type":"string"},"formatted_address":{"type":"string"},"line1":{"type":"string","description":"`\"{street}, {number}\"` for forms with a single address line."},"neighborhood":{"type":"string"},"number":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street":{"type":"string"}}},"PaymentEvent":{"type":"object","description":"A webhook the gateway sent about one of the order's payments.","required":["id","provider_code","event_type","external_event_id","payload_json","success","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"error_message":{"type":["string","null"]},"event_type":{"type":"string"},"external_event_id":{"type":"string"},"id":{"type":"string","format":"uuid"},"payload_json":{"type":"object"},"processed_at":{"type":["string","null"],"format":"date-time"},"provider_code":{"type":"string"},"success":{"type":"boolean"}}},"PaymentIntent":{"type":"object","description":"One attempt to pay for an order.","required":["id","order_id","provider_code","method","status","amount_cents","currency","provider_snapshot_json","created_at","updated_at"],"properties":{"amount_cents":{"type":"integer","format":"int64"},"cart_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"expires_at":{"type":["string","null"],"format":"date-time"},"external_id":{"type":["string","null"],"description":"The gateway's payment id."},"id":{"type":"string","format":"uuid"},"installments":{"type":["integer","null"],"format":"int32","description":"Card installments from the provider snapshot (1 = à vista)."},"method":{"$ref":"#/components/schemas/PaymentIntentMethod"},"order_id":{"type":"string","format":"uuid"},"payer_document":{"type":["string","null"],"description":"Payer document (CPF/CNPJ) extracted from the provider snapshot.\nThe merchant needs it to emit the nota fiscal."},"provider_code":{"type":"string","description":"`mercado_pago`, or `manual` for payments recorded at the counter."},"provider_snapshot_json":{"type":"object","description":"The gateway's payment, sanitized (no card data or secrets). For PIX,\n`point_of_interaction.transaction_data` holds the QR code."},"status":{"$ref":"#/components/schemas/PaymentIntentStatus"},"updated_at":{"type":"string","format":"date-time"}}},"PaymentIntentMethod":{"type":"string","description":"How a payment attempt is paid.","enum":["pix","card","cash","bank_transfer","card_terminal"]},"PaymentIntentStatus":{"type":"string","description":"State of a payment attempt: `pending` (waiting for the customer),\n`processing` (the gateway is settling), `requires_action`, `approved`\n(paid), `failed`, `cancelled`, `expired` (e.g. an unpaid PIX code) or\n`refunded`.","enum":["pending","processing","requires_action","approved","failed","cancelled","expired","refunded"]},"PaymentMethod":{"type":"string","description":"A payment method a gateway can offer at checkout.","enum":["pix","card"]},"PaymentProvider":{"type":"object","description":"A payment gateway connected to the store.","required":["id","store_id","name","code","config_json","is_active","is_default","created_at","updated_at"],"properties":{"code":{"type":"string","description":"Gateway code from the catalog, e.g. `mercado_pago`."},"config_json":{"type":"object","description":"Settings; secret ones come back masked."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_default":{"type":"boolean"},"name":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"PaymentProviderHealth":{"type":"object","description":"Whether a provider has every setting it needs.","required":["provider_code","healthy","checks"],"properties":{"checks":{"type":"object","description":"Per-setting presence, e.g. `{\"has_access_token\": true}`."},"healthy":{"type":"boolean","description":"Every required setting is present."},"provider_code":{"type":"string"}}},"PaymentProviderMeta":{"type":"object","description":"A payment gateway the platform supports.","required":["code","name","description","methods","connect","available","fields"],"properties":{"available":{"type":"boolean","description":"True once the gateway's backend implementation is wired. Gateways can be\nlisted as \"coming soon\" in the catalog before the impl lands."},"code":{"type":"string"},"connect":{"$ref":"#/components/schemas/ConnectKind"},"description":{"type":"string"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/ModuleField"}},"methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"},"description":"Payment methods this gateway can offer (pix / card)."},"name":{"type":"string"}}},"PermissionCatalog":{"type":"object","required":["groups"],"properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/PermissionCatalogGroup"}}}},"PermissionCatalogGroup":{"type":"object","required":["key","label","permissions"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionDef"}}}},"PermissionDef":{"type":"object","required":["code","group","level","label","description"],"properties":{"code":{"type":"string"},"description":{"type":"string"},"group":{"type":"string"},"label":{"type":"string","description":"pt-BR label shown in the picker."},"level":{"$ref":"#/components/schemas/Level"}}},"Plan":{"type":"object","description":"A plan in the catalog.","required":["code","name","monthly_price_cents","annual_price_cents","public","limits"],"properties":{"annual_price_cents":{"type":"integer","format":"int64","description":"Annual price in BRL cents, for the whole year."},"code":{"type":"string","description":"Stable id: `essencial`, `profissional`, `escala` or `parceiro`."},"limits":{"$ref":"#/components/schemas/PlanLimits"},"monthly_price_cents":{"type":"integer","format":"int64","description":"Monthly price in BRL cents."},"name":{"type":"string","description":"Display name. A proper noun, the same in every language."},"public":{"type":"boolean","description":"Sold to new customers. Unlisted plans (`parceiro`) are assigned by\nMobiari only."}}},"PlanCatalog":{"type":"object","description":"Every plan on sale, in BRL.","required":["currency","trial_days","plans"],"properties":{"currency":{"type":"string","description":"Always `BRL`.","example":"BRL"},"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"},"description":"Plans on sale, cheapest first."},"trial_days":{"type":"integer","format":"int64","description":"Length of the free trial a new organization gets."}}},"PlanLimits":{"type":"object","description":"A plan's size. `None` is unlimited.","required":["assistant_messages_per_store","storage_gb"],"properties":{"assistant_messages_per_store":{"type":"integer","format":"int64","description":"Assistant messages per store per calendar month, every channel."},"emails_per_month":{"type":["integer","null"],"format":"int64","description":"Marketing and transactional e-mails per month across the\norganization. Informative: sending is paced by the daily\ndeliverability caps, not cut at this number."},"seats":{"type":["integer","null"],"format":"int64","description":"People with access to any of the organization's stores, pending\ninvites included."},"storage_gb":{"type":"integer","format":"int64","description":"File library size, in GB, across the organization."},"stores":{"type":["integer","null"],"format":"int64","description":"Stores in the organization."}}},"PlatformAlertChannelType":{"type":"string","description":"A channel of my own alerts.","enum":["whatsapp","email"]},"PlatformNotificationPreference":{"type":"object","description":"Where and which of a store's admin events reach me, per channel. Push\nto the mobile apps is set under `/stores/{store_id}/me/push-preferences`.","required":["user_id","store_id","channel_type","destination","enabled_events","is_enabled","locale"],"properties":{"channel_type":{"type":"string","description":"`whatsapp` or `email`."},"destination":{"type":"string","description":"Phone (E.164) or e-mail address."},"enabled_events":{"type":"array","items":{"type":"string"},"description":"Admin events: `orders.created`, `orders.updated`, `orders.fulfilled`,\n`orders.cancelled`, `inventory.low_stock`, `customers.created`,\n`products.created`, `products.updated`."},"is_enabled":{"type":"boolean"},"locale":{"type":"string","description":"`pt-BR` or `en-US`."},"store_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"}}},"PlatformPrefInput":{"type":"object","required":["channel_type","destination","enabled_events"],"properties":{"channel_type":{"$ref":"#/components/schemas/PlatformAlertChannelType"},"destination":{"type":"string","description":"Phone (E.164) for WhatsApp, address for e-mail."},"enabled_events":{"type":"array","items":{"type":"string"}},"is_enabled":{"type":["boolean","null"],"description":"Defaults to true."},"locale":{"type":["string","null"],"description":"`pt-BR` (default) or `en-US`."}}},"Prediction":{"type":"object","description":"An address suggestion.","required":["place_id","description"],"properties":{"description":{"type":"string"},"place_id":{"type":"string","description":"Pass to `GET /places/details/{place_id}`."}}},"PreviewEmailSegmentRequest":{"type":"object","required":["conditions"],"properties":{"conditions":{"$ref":"#/components/schemas/EmailSegmentConditions"}}},"PreviewGrant":{"type":"object","description":"A preview-session token for one store.","required":["token","expires_at"],"properties":{"expires_at":{"type":"string","format":"date-time"},"preview_suffix":{"type":["string","null"],"description":"The trusted host suffix `return_url` was validated against. The UI\nchecks the destination again before navigating so the grant is never\nsent to an untrusted origin."},"token":{"type":"string","description":"POST it as the `token` form field to `/__preview/grant` on the\npreview host (never in a URL); the host turns it into a session\ncookie and redirects to the same-origin `return_url` path."}}},"PreviewGrantRequest":{"type":"object","description":"Which store to preview: `store_id` or `store_slug`.","properties":{"return_url":{"type":["string","null"],"description":"The destination the admin UI will append the grant to. Keep the\nalias so clients can use the query-parameter name `return`."},"store_id":{"type":["string","null"],"format":"uuid","description":"The store's id. Wins over `store_slug` when both are sent."},"store_slug":{"type":["string","null"],"description":"The store's slug, which is what the preview hostname carries."}}},"PreviewTransactionalEmailRequest":{"type":"object","description":"A template to render, as it is on screen (unsaved edits included).","required":["subject","mode"],"properties":{"blocks":{"type":["object","null"]},"design":{"type":["object","null"]},"html":{"type":["string","null"]},"mode":{"$ref":"#/components/schemas/TransactionalEmailMode"},"preview_text":{"type":["string","null"]},"subject":{"type":"string"}}},"Product":{"type":"object","description":"A product with its merchandising and feed fields.","required":["id","store_id","title","slug","status","product_type","highlights","priority","assembly_cost_cents","is_launch","allow_backorder","created_at","updated_at"],"properties":{"additional_image_links":{"type":["string","null"]},"allow_backorder":{"type":"boolean","description":"Whether the product itself may be backordered (sold without stock on\nhand). Does not gate its components: missing parts that carry their\nown flag are still backordered and ordered."},"assembly_cost_cents":{"type":"integer","format":"int64"},"availability":{"type":["string","null"],"description":"Resolved from the variants' stock: `in_stock`, `preorder` or\n`out_of_stock`."},"brand":{"type":["string","null"]},"category":{"type":["string","null"]},"condition":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"custom_label_0":{"type":["string","null"]},"custom_label_1":{"type":["string","null"]},"custom_label_2":{"type":["string","null"]},"custom_label_3":{"type":["string","null"]},"custom_label_4":{"type":["string","null"]},"custom_number_0":{"type":["integer","null"],"format":"int32"},"custom_number_1":{"type":["integer","null"],"format":"int32"},"custom_number_2":{"type":["integer","null"],"format":"int32"},"custom_number_3":{"type":["integer","null"],"format":"int32"},"custom_number_4":{"type":["integer","null"],"format":"int32"},"description":{"type":["string","null"]},"ean":{"type":["string","null"]},"expected_availability_at":{"type":["string","null"],"format":"date-time","description":"For `preorder`: when the earliest variant is expected."},"google_age_group":{"type":["string","null"]},"google_availability":{"type":["string","null"]},"google_brand":{"type":["string","null"]},"google_category":{"type":["string","null"]},"google_color":{"type":["string","null"]},"google_condition":{"type":["string","null"]},"google_custom_label_0":{"type":["string","null"]},"google_custom_label_1":{"type":["string","null"]},"google_custom_label_2":{"type":["string","null"]},"google_custom_label_3":{"type":["string","null"]},"google_custom_label_4":{"type":["string","null"]},"google_gender":{"type":["string","null"]},"google_gtin":{"type":["string","null"]},"google_material":{"type":["string","null"]},"google_mpn":{"type":["string","null"]},"google_pattern":{"type":["string","null"]},"google_size":{"type":["string","null"]},"highlight_video_poster_url":{"type":["string","null"]},"highlight_video_provider":{"type":["string","null"]},"highlight_video_url":{"type":["string","null"]},"highlights":{"type":"array","items":{"type":"string"}},"id":{"type":"string","format":"uuid"},"internal_label":{"type":["string","null"],"description":"Staff-only note, never shown to shoppers."},"is_launch":{"type":"boolean"},"is_physical":{"type":["boolean","null"]},"isbn":{"type":["string","null"]},"item_group_id":{"type":["string","null"]},"meta_age_group":{"type":["string","null"]},"meta_availability":{"type":["string","null"]},"meta_brand":{"type":["string","null"]},"meta_category":{"type":["string","null"]},"meta_color":{"type":["string","null"]},"meta_condition":{"type":["string","null"]},"meta_description":{"type":["string","null"]},"meta_gender":{"type":["string","null"]},"meta_material":{"type":["string","null"]},"meta_pattern":{"type":["string","null"]},"meta_size":{"type":["string","null"]},"meta_title":{"type":["string","null"]},"model_placement":{"type":["string","null"]},"model_url":{"type":["string","null"],"description":"3D model (glb/gltf/usdz) URL for the storefront viewer."},"price":{"type":["string","null"]},"priority":{"type":"integer","format":"int32","description":"Sort weight; lower first."},"product_type":{"$ref":"#/components/schemas/ProductType"},"quantity_to_sell_on_facebook":{"type":["integer","null"],"format":"int32"},"rich_text_description":{"type":["string","null"],"description":"HTML description the storefront renders."},"sale_price":{"type":["string","null"]},"sale_price_effective_date":{"type":["string","null"]},"shipping":{"type":["string","null"]},"shipping_weight":{"type":["string","null"]},"short_description":{"type":["string","null"]},"sku_prefix":{"type":["string","null"]},"slug":{"type":"string","description":"The storefront URL segment. Change it with `PATCH .../slug`, which\nkeeps the old URL as a redirect."},"status":{"$ref":"#/components/schemas/ProductStatus"},"store_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"upc":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"},"video_urls":{"type":["string","null"]},"weight_grams":{"type":["integer","null"],"format":"int32"}}},"ProductAvailability":{"type":"string","description":"Whether a product can be bought now: from stock (`in_stock`), sold\nahead of stock with an expected date (`preorder`), or not at all\n(`out_of_stock`).","enum":["in_stock","preorder","out_of_stock"]},"ProductCategoryRequest":{"type":"object","description":"A product and a category of the same store.","required":["product_id","category_id"],"properties":{"category_id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"}}},"ProductCreateRequest":{"allOf":[{"$ref":"#/components/schemas/ProductFields"},{"type":"object","required":["title"],"properties":{"default_price_cents":{"type":["integer","null"],"format":"int64","description":"For a `single` product: also create its one variant at this price."},"title":{"type":"string"}}}],"description":"A new product."},"ProductDetail":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","required":["variants","option_groups","images"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImageWithVariants"},"description":"The active gallery (images and videos), as `GET .../images` lists it."},"option_groups":{"type":"array","items":{"$ref":"#/components/schemas/OptionGroupWithValues"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariantDetail"},"description":"Every variant, active or not, in display order."}}}],"description":"A product with everything a detail screen needs: its variants (with\noptions and stock per location), its option groups and its gallery."},"ProductFeed":{"type":"object","description":"A product feed.","required":["id","store_id","channel","name","feed_type","is_active","created_at","updated_at"],"properties":{"channel":{"$ref":"#/components/schemas/ProductFeedChannel"},"config_json":{"type":["object","null"]},"content":{"type":["string","null"],"description":"The last generated content, for `generated` feeds."},"created_at":{"type":"string","format":"date-time"},"endpoint_url":{"type":["string","null"],"description":"The public URL to give the marketplace."},"feed_type":{"type":"string","description":"`generated` (serves the content stored by the last generate) or\n`realtime` (built on every fetch)."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean","description":"Inactive feeds answer 404 at their public URL."},"last_generated_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"ProductFeedChannel":{"type":"string","description":"Where a feed goes, which also fixes its format.","enum":["meta","google","custom","omnifeed"]},"ProductFeedCreateRequest":{"type":"object","description":"A new feed.","required":["channel","name"],"properties":{"channel":{"$ref":"#/components/schemas/ProductFeedChannel"},"config_json":{"type":["object","null"]},"feed_type":{"type":["string","null"],"description":"`generated` (default) or `realtime`."},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"name":{"type":"string"}}},"ProductFeedOverride":{"type":"object","description":"Per-product data a feed uses instead of the product's own fields.","required":["id","product_feed_id","product_id","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"metadata_json":{"type":["object","null"],"description":"Feed field names to values, e.g. `{\"title\": \"...\"}`."},"product_feed_id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"}}},"ProductFeedOverrideCreateRequest":{"type":"object","description":"A new override.","required":["product_id"],"properties":{"metadata_json":{"type":["object","null"]},"product_id":{"type":"string","format":"uuid","description":"A product of the same store."}}},"ProductFeedOverrideUpdateRequest":{"type":"object","description":"The new override data.","properties":{"metadata_json":{"type":["object","null"]}}},"ProductFeedUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value.","properties":{"config_json":{"type":["object","null"]},"endpoint_url":{"type":["string","null"],"description":"Overrides the public URL; `null` resets it to the default."},"feed_type":{"type":["string","null"],"description":"`generated` or `realtime`."},"is_active":{"type":["boolean","null"]},"name":{"type":["string","null"]}}},"ProductFields":{"type":"object","description":"Product fields shared by create and update. Omitted fields are left\nalone (on create, they take their defaults).","properties":{"additional_image_links":{"type":["string","null"]},"allow_backorder":{"type":["boolean","null"]},"assembly_cost_cents":{"type":["integer","null"],"format":"int64","description":"Negative values are stored as 0."},"availability":{"type":["string","null"],"description":"Sets `google_availability` (the shopper-facing availability is\ncomputed from stock)."},"brand":{"type":["string","null"],"description":"An empty string clears it."},"category":{"type":["string","null"],"description":"Sets `google_category` (unless `google_category` is also sent)."},"condition":{"type":["string","null"],"description":"Sets `condition` and `google_condition`."},"custom_label_0":{"type":["string","null"]},"custom_label_1":{"type":["string","null"]},"custom_label_2":{"type":["string","null"]},"custom_label_3":{"type":["string","null"]},"custom_label_4":{"type":["string","null"]},"custom_number_0":{"type":["integer","null"],"format":"int32"},"custom_number_1":{"type":["integer","null"],"format":"int32"},"custom_number_2":{"type":["integer","null"],"format":"int32"},"custom_number_3":{"type":["integer","null"],"format":"int32"},"custom_number_4":{"type":["integer","null"],"format":"int32"},"description":{"type":["string","null"]},"ean":{"type":["string","null"]},"google_age_group":{"type":["string","null"]},"google_availability":{"type":["string","null"]},"google_brand":{"type":["string","null"],"description":"An empty string clears it."},"google_category":{"type":["string","null"]},"google_color":{"type":["string","null"]},"google_condition":{"type":["string","null"]},"google_custom_label_0":{"type":["string","null"]},"google_custom_label_1":{"type":["string","null"]},"google_custom_label_2":{"type":["string","null"]},"google_custom_label_3":{"type":["string","null"]},"google_custom_label_4":{"type":["string","null"]},"google_gender":{"type":["string","null"]},"google_gtin":{"type":["string","null"]},"google_material":{"type":["string","null"]},"google_mpn":{"type":["string","null"]},"google_pattern":{"type":["string","null"]},"google_size":{"type":["string","null"]},"highlight_video_poster_url":{"type":["string","null"]},"highlight_video_provider":{"type":["string","null"]},"highlight_video_url":{"type":["string","null"]},"highlights":{"type":["array","null"],"items":{"type":"string"}},"internal_label":{"type":["string","null"]},"is_launch":{"type":["boolean","null"]},"is_physical":{"type":["boolean","null"]},"isbn":{"type":["string","null"]},"item_group_id":{"type":["string","null"]},"meta_age_group":{"type":["string","null"]},"meta_availability":{"type":["string","null"]},"meta_brand":{"type":["string","null"],"description":"An empty string clears it."},"meta_category":{"type":["string","null"]},"meta_color":{"type":["string","null"]},"meta_condition":{"type":["string","null"]},"meta_description":{"type":["string","null"]},"meta_gender":{"type":["string","null"]},"meta_material":{"type":["string","null"]},"meta_pattern":{"type":["string","null"]},"meta_size":{"type":["string","null"]},"meta_title":{"type":["string","null"]},"model_placement":{"type":["string","null"]},"model_url":{"type":["string","null"]},"price":{"type":["string","null"]},"priority":{"type":["integer","null"],"format":"int32"},"product_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ProductType"}]},"quantity_to_sell_on_facebook":{"type":["integer","null"],"format":"int32"},"rich_text_description":{"type":["string","null"],"description":"HTML description the storefront renders."},"sale_price":{"type":["string","null"]},"sale_price_effective_date":{"type":["string","null"]},"shipping":{"type":["string","null"]},"shipping_weight":{"type":["string","null"]},"short_description":{"type":["string","null"]},"sku_prefix":{"type":["string","null"]},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ProductStatus"}]},"upc":{"type":["string","null"],"description":"Sets `upc` and `google_gtin` (unless `google_gtin` is also sent)."},"video_urls":{"type":["string","null"]},"weight_grams":{"type":["integer","null"],"format":"int32"}}},"ProductHit":{"type":"object","required":["id","title","slug","status"],"properties":{"id":{"type":"string","format":"uuid"},"image_url":{"type":["string","null"]},"sku":{"type":["string","null"],"description":"The matching variant SKU, when the match was on a SKU."},"slug":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}}},"ProductImage":{"type":"object","description":"A product gallery entry: an uploaded image (with resized renditions in\n`variants`) or a video (`media_type = video`, `cdn_url` is the playable\nURL and there are no renditions).","required":["id","product_id","filename","file_path","image_size","mime_type","file_size_bytes","image_kind","position","is_primary","is_active","media_type","created_at","updated_at"],"properties":{"alt_text":{"type":["string","null"]},"cdn_url":{"type":["string","null"],"description":"Public URL of the original."},"created_at":{"type":"string","format":"date-time"},"extra_variant_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Extra variants this image is shared with (besides\n`product_variant_id`)."},"file_path":{"type":"string"},"file_size_bytes":{"type":"integer","format":"int32"},"filename":{"type":"string","description":"Stored filename. `/images/{size}/{filename}` serves it, with `size`\none of `original`, `thumbnail`, `small`, `medium`, `large`."},"height":{"type":["integer","null"],"format":"int32"},"id":{"type":"string","format":"uuid"},"image_kind":{"type":"string","description":"`gallery` (default) or `measurement` (size charts, kept out of the\nstorefront gallery)."},"image_size":{"type":"string"},"is_active":{"type":"boolean"},"is_primary":{"type":"boolean"},"media_type":{"type":"string","description":"`image` (default) or `video`."},"mime_type":{"type":"string"},"original_filename":{"type":["string","null"]},"position":{"type":"integer","format":"int32"},"poster_url":{"type":["string","null"],"description":"Poster image URL for video rows."},"product_id":{"type":"string","format":"uuid"},"product_variant_id":{"type":["string","null"],"format":"uuid","description":"The variant this image belongs to; null for product-wide images."},"provider":{"type":["string","null"],"description":"For videos: `upload`, `youtube`, `vimeo` or `external`. Null for\nimages."},"updated_at":{"type":"string","format":"date-time"},"width":{"type":["integer","null"],"format":"int32"}}},"ProductImageUploadForm":{"type":"object","description":"The multipart form of an image upload.","required":["image"],"properties":{"alt_text":{"type":["string","null"]},"image":{"type":"string","format":"binary","description":"The image file: JPEG, PNG or WebP, up to 10 MB."},"image_kind":{"type":["string","null"],"description":"`gallery` (default) or `measurement`."},"is_primary":{"type":["boolean","null"]},"position":{"type":["integer","null"],"format":"int32"},"product_variant_id":{"type":["string","null"],"format":"uuid","description":"Attach the image to one variant of the product."}}},"ProductImageWithVariants":{"allOf":[{"$ref":"#/components/schemas/ProductImage"},{"type":"object","required":["variants"],"properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/ImageVariant"}}}}],"description":"A gallery entry with its resized renditions."},"ProductListItem":{"type":"object","description":"One row of the product list.","required":["id","store_id","title","slug","status","product_type","priority","is_launch","availability","variant_count","total_stock","available_stock","variants","created_at","updated_at"],"properties":{"availability":{"$ref":"#/components/schemas/ProductAvailability"},"available_stock":{"type":"integer","format":"int32","description":"`total_stock` minus units reserved by open orders."},"created_at":{"type":"string","format":"date-time"},"expected_availability_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"is_launch":{"type":"boolean"},"price_max_cents":{"type":["integer","null"],"format":"int64","description":"Highest price over the active variants; null without any."},"price_min_cents":{"type":["integer","null"],"format":"int64","description":"Lowest price over the active variants; null without any."},"primary_image_filename":{"type":["string","null"],"description":"Stored filename of the primary image (`/images/{size}/{filename}`)."},"primary_image_thumbnail_url":{"type":["string","null"],"description":"URL of the primary image resized for lists (medium, about 600px)."},"primary_image_url":{"type":["string","null"],"description":"URL of the primary image's original; null when the product has no\nimage."},"priority":{"type":"integer","format":"int32"},"product_type":{"$ref":"#/components/schemas/ProductType"},"short_description":{"type":["string","null"]},"sku_prefix":{"type":["string","null"]},"slug":{"type":"string"},"status":{"$ref":"#/components/schemas/ProductStatus"},"store_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"total_stock":{"type":"integer","format":"int32","description":"Units on hand over the active variants and every location."},"updated_at":{"type":"string","format":"date-time"},"variant_count":{"type":"integer","format":"int32","description":"Active variants."},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"},"description":"The active variants, in display order, with their stock."}}},"ProductSlugRedirect":{"type":"object","description":"An old slug that redirects to the product.","required":["id","old_slug","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"old_slug":{"type":"string"}}},"ProductSlugUpdate":{"type":"object","description":"The slug after the change.","required":["slug","redirect_created"],"properties":{"redirect_created":{"type":"boolean","description":"Whether the previous slug now redirects here."},"slug":{"type":"string"}}},"ProductSlugUpdateRequest":{"type":"object","description":"The new slug.","required":["slug"],"properties":{"slug":{"type":"string","description":"Normalized to lowercase letters, digits and single dashes."}}},"ProductSpecValue":{"type":"object","required":["field_id","term_ids","value_texts","collection_ids"],"properties":{"collection_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"References into the store's `collections` table — populated for\n`kind = 'collection_ref'` fields. Sourced from `collection_products`,\nnot stored on `product_specs`, so the spec sheet stays in sync with\nwhatever wrote the product↔collection relationship (importer,\nproduct form, this endpoint)."},"field_id":{"type":"string","format":"uuid"},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"value_text":{"type":["string","null"]},"value_texts":{"type":"array","items":{"type":"string"},"description":"Multiple freeform string values — used by `taxonomy` fields whose\n`allow_freeform` is true and the user types custom values\nalongside picked terms."}}},"ProductSpecsResponse":{"type":"object","description":"A product's spec sheet: the global schema, the values set and the\nstore's collections for `collection_ref` fields.","required":["groups","taxonomies","values","collections"],"properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRef"}},"groups":{"type":"array","items":{"$ref":"#/components/schemas/GroupWithFields"}},"taxonomies":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyWithTerms"}},"values":{"type":"array","items":{"$ref":"#/components/schemas/ProductSpecValue"}}}},"ProductStatus":{"type":"string","description":"Lifecycle of a product. Only `active` products are sold. Requests also\naccept the capitalized forms (`Active`) older clients send.","enum":["draft","active","archived"]},"ProductStockComponentLine":{"type":"object","description":"Component stock behind one kit component line.","required":["component_id","component","sku","stock","on_hand","reserved","required"],"properties":{"component":{"type":"string"},"component_id":{"type":"string","format":"uuid","description":"The component variant."},"on_hand":{"type":"integer","format":"int32"},"required":{"type":"integer","format":"int32","description":"Units needed per kit."},"reserved":{"type":"integer","format":"int32"},"sku":{"type":"string"},"stock":{"type":"integer","format":"int32","description":"Units available (on hand minus reserved)."}}},"ProductStockResponse":{"type":"object","description":"How many kits the components allow.","required":["product_id","available","components"],"properties":{"available":{"type":"integer","format":"int32","description":"Kits that can be built from the components available now, summed\nover the product's active kit variants."},"components":{"type":"array","items":{"$ref":"#/components/schemas/ProductStockComponentLine"}},"product_id":{"type":"string","format":"uuid"}}},"ProductSubscription":{"type":"object","description":"A shopper's \"let me know\" on a product.","required":["id","email","kind","status","product_id","product_title","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"customer_id":{"type":["string","null"],"format":"uuid"},"email":{"type":"string"},"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/ProductSubscriptionKind"},"notified_at":{"type":["string","null"],"format":"date-time"},"price_at_subscription":{"type":["integer","null"],"format":"int32","description":"Lowest active price when they signed up."},"product_id":{"type":"string","format":"uuid"},"product_title":{"type":"string"},"status":{"type":"string","description":"`active` (waiting) or `notified`."}}},"ProductSubscriptionKind":{"type":"string","description":"What a shopper wants to hear about.","enum":["back_in_stock","price_drop"]},"ProductSubscriptionSummary":{"type":"object","description":"Counts of product subscriptions.","required":["back_in_stock","price_drop","notified"],"properties":{"back_in_stock":{"type":"integer","format":"int64","description":"Active back-in-stock sign-ups."},"notified":{"type":"integer","format":"int64","description":"Sign-ups already notified."},"price_drop":{"type":"integer","format":"int64","description":"Active price-drop sign-ups."}}},"ProductType":{"type":"string","description":"`single` (one variant), `variable` (options such as size and color) or\n`kit` (built from other products' variants).","enum":["single","variable","kit"]},"ProductUpdateRequest":{"allOf":[{"$ref":"#/components/schemas/ProductFields"},{"type":"object","properties":{"title":{"type":["string","null"]}}}],"description":"Fields to change; omitted fields keep their value."},"ProductVariant":{"type":"object","description":"A sellable variant of a product, with its stock summed over every\nlocation. For a kit (a variant built from components) the stock figures\nare derived from its parts.","required":["id","product_id","sku","title","price_cents","fulfillment_mode","is_active","position","stock_quantity","available_quantity","reserved_quantity","backorderable","uses_components","created_at","updated_at"],"properties":{"available_quantity":{"type":"integer","format":"int32","description":"Units on hand minus units reserved by open orders."},"backorderable":{"type":"boolean","description":"Whether one more unit may sell without stock on hand: an on-demand\nfulfillment mode, or a kit whose missing parts can be purchased."},"barcode":{"type":["string","null"],"description":"GTIN/EAN/UPC printed on the item, when it has one."},"compare_at_cents":{"type":["integer","null"],"format":"int64","description":"The \"was\" price shown struck through, when higher than the price."},"cost_cents":{"type":["integer","null"],"format":"int64"},"created_at":{"type":"string","format":"date-time"},"expected_availability_at":{"type":["string","null"],"format":"date-time","description":"When a unit ordered now is expected to be available, for variants\nsold without stock on hand. Null when it ships from stock."},"fulfillment_mode":{"$ref":"#/components/schemas/FulfillmentMode"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean","description":"Inactive variants are hidden from the storefront and the POS."},"lead_time_days":{"type":["integer","null"],"format":"int32","description":"Days to make or source the item when it is sold without stock."},"position":{"type":"integer","format":"int32","description":"Display order within the product."},"price_cents":{"type":"integer","format":"int64"},"product_id":{"type":"string","format":"uuid"},"reserved_quantity":{"type":"integer","format":"int32","description":"Units reserved by open orders."},"sku":{"type":"string","description":"Unique across the platform."},"stock_quantity":{"type":"integer","format":"int32","description":"Units on hand over every location."},"title":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"uses_components":{"type":"boolean","description":"Whether the variant is a kit whose stock comes from its components."}}},"ProductVariantDetail":{"allOf":[{"$ref":"#/components/schemas/ProductVariant"},{"type":"object","required":["options","stock_by_location"],"properties":{"options":{"type":"array","items":{"$ref":"#/components/schemas/VariantOptionValue"}},"stock_by_location":{"type":"array","items":{"$ref":"#/components/schemas/VariantLocationStock"}}}}],"description":"A variant with its options and its stock per location. Kits hold no\nstock of their own, so their `stock_by_location` is empty and the totals\ncome from their components."},"PublishWorkflowRequest":{"type":"object","properties":{"note":{"type":["string","null"],"description":"What changed, kept with the version."}}},"PurchaseOrder":{"type":"object","description":"A purchase order with its totals.","required":["id","number","status","currency","shipping_cents","other_cents","created_at","line_count","total_ordered","total_received","goods_cents"],"properties":{"closed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"expected_at":{"type":["string","null"],"format":"date"},"goods_cents":{"type":"integer","format":"int64","description":"Line totals only; shipping and other costs are separate."},"id":{"type":"string","format":"uuid"},"line_count":{"type":"integer","format":"int64"},"location_id":{"type":["string","null"],"format":"uuid","description":"Where received goods go by default."},"notes":{"type":["string","null"]},"number":{"type":"string","description":"Sequential per store, e.g. `PO-0042`."},"ordered_at":{"type":["string","null"],"format":"date-time"},"other_cents":{"type":"integer","format":"int64"},"shipping_cents":{"type":"integer","format":"int64"},"status":{"$ref":"#/components/schemas/PurchaseOrderStatus"},"supplier_id":{"type":["string","null"],"format":"uuid"},"supplier_name":{"type":["string","null"]},"total_ordered":{"type":"integer","format":"int64"},"total_received":{"type":"integer","format":"int64"}}},"PurchaseOrderCreateRequest":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"Defaults to `BRL`."},"expected_at":{"type":["string","null"],"format":"date"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderLineInput"}},"location_id":{"type":["string","null"],"format":"uuid","description":"Where received goods go by default."},"notes":{"type":["string","null"]},"supplier_id":{"type":["string","null"],"format":"uuid"}}},"PurchaseOrderDetail":{"allOf":[{"$ref":"#/components/schemas/PurchaseOrder"},{"type":"object","required":["lines","receipts"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderLine"}},"receipts":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseReceipt"},"description":"Newest first."}}}],"description":"A purchase order with its lines and receipts."},"PurchaseOrderLine":{"type":"object","description":"One line of a purchase order.","required":["id","quantity_ordered","quantity_received","unit_cost_cents"],"properties":{"current_name":{"type":["string","null"],"description":"The variant's name today."},"description":{"type":["string","null"],"description":"Name when the line was added."},"id":{"type":"string","format":"uuid"},"item_id":{"type":["string","null"],"format":"uuid","description":"The variant ordered; null when it was deleted since."},"quantity_ordered":{"type":"integer","format":"int32"},"quantity_received":{"type":"integer","format":"int32"},"sku":{"type":["string","null"],"description":"SKU when the line was added."},"unit_cost_cents":{"type":"integer","format":"int64"}}},"PurchaseOrderLineInput":{"type":"object","description":"One line to order.","required":["variant_id","quantity_ordered"],"properties":{"quantity_ordered":{"type":"integer","format":"int32","minimum":1},"unit_cost_cents":{"type":["integer","null"],"format":"int64","description":"Defaults to 0."},"variant_id":{"type":"string","format":"uuid","description":"The variant to order."}}},"PurchaseOrderStatus":{"type":"string","description":"Where a purchase order stands (see the tag description).","enum":["draft","ordered","partial","received","cancelled"]},"PurchaseOrderUpdateRequest":{"type":"object","properties":{"expected_at":{"type":["string","null"],"format":"date"},"lines":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PurchaseOrderLineInput"},"description":"Replaces every line. Only while the order is a draft."},"location_id":{"type":["string","null"],"format":"uuid"},"notes":{"type":["string","null"]},"other_cents":{"type":["integer","null"],"format":"int64"},"shipping_cents":{"type":["integer","null"],"format":"int64"},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PurchaseOrderStatus","description":"`ordered` (from `draft`: sends it, its lines become incoming) or\n`cancelled` (from `draft`, `ordered` or `partial`)."}]},"supplier_id":{"type":["string","null"],"format":"uuid"}}},"PurchaseReceipt":{"type":"object","description":"One delivery booked against an order.","required":["id","created_at","quantity","items"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseReceiptItem"}},"location_name":{"type":["string","null"]},"note":{"type":["string","null"]},"quantity":{"type":"integer","format":"int64","description":"Units received in this drop."},"received_by":{"type":["string","null"],"description":"Name of who booked it."}}},"PurchaseReceiptItem":{"type":"object","description":"One line of a receipt.","required":["quantity","unit_cost_cents"],"properties":{"description":{"type":["string","null"]},"quantity":{"type":"integer","format":"int32"},"sku":{"type":["string","null"]},"unit_cost_cents":{"type":"integer","format":"int64","description":"Landed unit cost: the line cost plus shipping and other costs spread\nover every unit ordered."}}},"PurchaseReceiptResult":{"type":"object","required":["receipt_id","received","status","unlocks","levels"],"properties":{"levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevelChange"},"description":"The new level of every variant received, at the receiving location."},"receipt_id":{"type":"string","format":"uuid"},"received":{"type":"integer","format":"int64","description":"Units received in this drop."},"status":{"$ref":"#/components/schemas/PurchaseOrderStatus","description":"The order's status after the receipt: `partial` or `received`."},"unlocks":{"type":"array","items":{"$ref":"#/components/schemas/ReceiptUnlock"},"description":"Kits fed by the received components, with what they can now ship."}}},"PurchaseReceiveLine":{"type":"object","required":["purchase_order_item_id","quantity"],"properties":{"purchase_order_item_id":{"type":"string","format":"uuid","description":"`PurchaseOrderLine.id`."},"quantity":{"type":"integer","format":"int32","description":"Units that arrived. Lines with 0 are skipped; more than ordered is\nallowed and recorded as is."}}},"PurchaseReceiveRequest":{"type":"object","required":["lines"],"properties":{"force":{"type":"boolean","description":"Receive even though an ERP owns this store's stock."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseReceiveLine"}},"location_id":{"type":["string","null"],"format":"uuid","description":"Where this drop goes; defaults to the order's location, then the\nstore's default location."},"note":{"type":["string","null"]}}},"PurgeResult":{"type":"object","description":"What a purge did (or would do, for a dry run).","required":["dry_run","examined","deleted","skipped_due_to_orders"],"properties":{"deleted":{"type":"integer","format":"int64","description":"Products deleted (or that would be)."},"dry_run":{"type":"boolean"},"examined":{"type":"integer","format":"int64","description":"Products considered."},"skipped_due_to_orders":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Products kept because orders reference them."}}},"PushDevice":{"type":"object","description":"A phone or tablet registered for push.","required":["id","platform","token","environment","current","active","created_at","updated_at"],"properties":{"active":{"type":"boolean","description":"Its session is still signed in. Devices of ended sessions get no\npushes (sign-out and revoking a session delete them outright)."},"app_version":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"current":{"type":"boolean","description":"Registered by the session making this request."},"device_name":{"type":["string","null"]},"environment":{"$ref":"#/components/schemas/PushEnvironment"},"id":{"type":"string","format":"uuid"},"last_push_at":{"type":["string","null"],"format":"date-time","description":"Last push the provider accepted for it."},"locale":{"type":["string","null"],"description":"The device's language (BCP 47), which pushes are written in."},"platform":{"$ref":"#/components/schemas/PushPlatform"},"token":{"type":"string","description":"The APNs device token (hex) or FCM registration token."},"updated_at":{"type":"string","format":"date-time"}}},"PushEnvironment":{"type":"string","description":"Which APNs gateway an iOS token belongs to. Debug builds from Xcode get\nsandbox tokens; TestFlight and App Store builds get production ones.\nIgnored for Android.","enum":["production","sandbox"]},"PushEvent":{"type":"string","description":"A team alert that can go to the mobile apps as a push. Also the key of\nthe per-store push preferences. The set will grow; clients must ignore\nkinds they do not know.","enum":["orders.created","orders.paid","orders.cancelled","inventory.low_stock","conversations.started","conversations.message_received","conversations.handed_over","conversations.assigned"]},"PushPlatform":{"type":"string","description":"A registered device's OS.","enum":["ios","android"]},"PushPreferences":{"type":"object","description":"Which alerts of one store push to my devices.","required":["store_id","is_enabled","enabled_events","available_events","is_default"],"properties":{"available_events":{"type":"array","items":{"$ref":"#/components/schemas/PushEvent"},"description":"Every alert I can receive in this store (my permissions decide), in\ndisplay order."},"enabled_events":{"type":"array","items":{"$ref":"#/components/schemas/PushEvent"},"description":"Alerts that push. Conversation alerts only cover conversations\nassigned to me or to nobody."},"is_default":{"type":"boolean","description":"Nothing saved yet: the defaults (orders and conversations on, low\nstock off) apply."},"is_enabled":{"type":"boolean","description":"Off: no pushes from this store at all."},"store_id":{"type":"string","format":"uuid"}}},"PushProvider":{"type":"string","description":"Which provider took a push.","enum":["apns","fcm"]},"PushTestResult":{"type":"object","description":"A test push the provider accepted.","required":["device_id","provider"],"properties":{"device_id":{"type":"string","format":"uuid"},"provider":{"$ref":"#/components/schemas/PushProvider"},"provider_message_id":{"type":["string","null"],"description":"`apns-id` (APNs) or the message name (FCM)."}}},"QuoteContactInput":{"type":"object","description":"The customer's contact and delivery details, pre-filled at checkout.","properties":{"additional_info":{"type":["string","null"]},"city":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF/CNPJ. The checkout validates it and will not advance without one,\nso a quote that omits it can never be a link the customer just pays."},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"zip_code":{"type":["string","null"]}}},"QuoteCreateRequest":{"type":"object","description":"A new quote.","required":["items"],"properties":{"contact":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/QuoteContactInput"}]},"customer_id":{"type":["string","null"],"format":"uuid","description":"Attaches the quote to a known customer, so the resulting order lands\non their record instead of creating a stranger."},"discount_cents":{"type":["integer","null"],"format":"int64","description":"Fixed negotiated discount in cents. Mutually exclusive with\ndiscount_pct_bp (basis points win when both are sent)."},"discount_pct_bp":{"type":["integer","null"],"format":"int32"},"expires_in_days":{"type":["integer","null"],"format":"int64","description":"Days until the link stops working, 1 to 90. Defaults to 7."},"freight":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/QuoteFreightInput","description":"The freight the seller quoted at the counter. Applied to the cart here\nrather than by the POS, because it has to actually stick: the price the\ncounter saw and the price the link charges must be the same number."}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/QuoteItemInput"},"description":"At least one line with a positive quantity."},"lock_address":{"type":["boolean","null"]},"lock_freight":{"type":["boolean","null"]},"lock_price":{"type":["boolean","null"],"description":"Per-quote locks: what the seller froze so the customer just pays."},"max_installments":{"type":["integer","null"],"format":"int32","description":"Payment-link config: cap the installment count the customer may\npick on the /q link. NULL → the storefront default (6). Validated\nto 1..=12."},"note":{"type":["string","null"]},"sales_channel_id":{"type":["string","null"],"format":"uuid"}}},"QuoteCreated":{"type":"object","description":"The quote just created.","required":["cart_id","share_token","quote_url","total_cents","shipping_cents","freight_applied","freight_price_changed"],"properties":{"cart_id":{"type":"string","format":"uuid","description":"The quote is a cart; this is its id."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the link stops working. Returned so the seller can tell the\ncustomer a date instead of guessing at the default."},"freight_applied":{"type":"boolean","description":"False when the seller picked a freight and it could not be reapplied to\nthe cart. The quote is still valid — the customer picks on the link —\nbut the seller has to be told, because the total just moved."},"freight_price_changed":{"type":"boolean","description":"Set when the carrier re-quoted at a different price than the counter\nsaw, so the seller learns the real number before sending the link."},"quote_url":{"type":"string","description":"The link to send the customer."},"share_token":{"type":"string"},"shipping_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"}}},"QuoteFreightInput":{"type":"object","description":"The freight the seller picked at the counter.","required":["destination_postal_code"],"properties":{"carrier_name":{"type":["string","null"]},"destination_postal_code":{"type":"string"},"option_id":{"type":["string","null"],"description":"The option the seller picked in the cart-less simulation. Central do\nFrete mints a fresh id per quotation, so this rarely matches and the\ncarrier name is what actually identifies the choice."},"service_name":{"type":["string","null"]},"shipping_cents":{"type":["integer","null"],"format":"int64","description":"What the counter was quoted, kept only to report the drift."}}},"QuoteItemInput":{"type":"object","description":"One line of a new quote.","required":["variant_id","quantity"],"properties":{"quantity":{"type":"integer","format":"int32"},"variant_id":{"type":"string"}}},"QuoteShipmentRequest":{"type":"object","description":"What to quote.","required":["destination_postal_code","volumes"],"properties":{"destination_postal_code":{"type":"string","description":"CEP, 8 digits (formatting ignored)."},"invoice_amount":{"type":["number","null"],"format":"double","description":"Deprecated: the declared value in currency units (e.g. `150.5`).\nSend `invoice_amount_cents`.","deprecated":true},"invoice_amount_cents":{"type":["integer","null"],"format":"int64","description":"Declared value of the goods, in cents. Required unless the\ndeprecated `invoice_amount` is sent."},"recipient_document":{"type":["string","null"]},"recipient_name":{"type":["string","null"]},"volumes":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentVolume"}}}},"QuoteStatus":{"type":"string","description":"`open` (the link works), `expired` (past its date or expired by hand)\nor `converted` (the customer checked out; see `order_id`).","enum":["open","expired","converted"]},"QuoteSummary":{"type":"object","description":"A quote in the list.","required":["cart_id","share_token","quote_url","item_count","subtotal_cents","discount_cents","total_cents","status","created_at"],"properties":{"cart_id":{"type":"string","format":"uuid","description":"The quote is a cart; this is its id."},"contact_name":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"discount_cents":{"type":"integer","format":"int64"},"expires_at":{"type":["string","null"],"format":"date-time"},"item_count":{"type":"integer","format":"int32"},"note":{"type":["string","null"]},"order_id":{"type":["string","null"],"format":"uuid","description":"The order the customer's checkout created."},"order_number":{"type":["string","null"]},"quote_url":{"type":"string","description":"The link sent to the customer."},"share_token":{"type":"string"},"status":{"$ref":"#/components/schemas/QuoteStatus"},"subtotal_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"}}},"ReceiptUnlock":{"type":"object","description":"A kit this receipt made more buildable.","required":["variant_id","product_id","sku","name","max_shippable"],"properties":{"limiting_sku":{"type":["string","null"]},"max_shippable":{"type":"integer","format":"int32","description":"Whole kits shippable after the receipt."},"name":{"type":"string"},"product_id":{"type":"string","format":"uuid"},"sku":{"type":"string"},"variant_id":{"type":"string","format":"uuid"}}},"RefreshRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","description":"The refresh token from the last sign-in or refresh."}}},"Refund":{"type":"object","description":"Money returned to the customer through the payment provider.","required":["id","order_id","payment_intent_id","provider_code","amount_cents","currency","created_at"],"properties":{"amount_cents":{"type":"integer","format":"int64"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"format":"uuid","description":"Who issued it; null when the user was removed."},"currency":{"type":"string"},"external_id":{"type":["string","null"],"description":"The provider's refund id."},"id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"payment_intent_id":{"type":"string","format":"uuid","description":"The payment attempt refunded."},"provider_code":{"type":"string"},"reason":{"type":["string","null"]}}},"RegisterPushDeviceRequest":{"type":"object","description":"Register this device for push.","required":["platform","token"],"properties":{"app_version":{"type":["string","null"],"description":"App version, e.g. `1.4.0 (52)`. Up to 64 characters."},"device_name":{"type":["string","null"],"description":"A name the user recognizes, e.g. `iPhone de Ana`. Up to 255 characters."},"environment":{"$ref":"#/components/schemas/PushEnvironment","description":"iOS only: `sandbox` for debug builds run from Xcode. Defaults to\n`production` (TestFlight, App Store)."},"locale":{"type":["string","null"],"description":"The device's language (BCP 47, e.g. `pt-BR`). Pushes are written in\nPortuguese or English; without it, the user's profile language."},"platform":{"$ref":"#/components/schemas/PushPlatform"},"token":{"type":"string","description":"iOS: the APNs device token as hex (from\n`didRegisterForRemoteNotificationsWithDeviceToken`). Android: the FCM\nregistration token."}}},"RegisterRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","example":"ana@example.com"},"full_name":{"type":["string","null"]},"password":{"type":"string","description":"At least 8 characters."}}},"RenameAssistantConversationRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"1 to 120 characters."}}},"RenderEmailDesignRequest":{"type":"object","required":["design"],"properties":{"design":{"type":"object"},"kit":{"type":["object","null"],"description":"Render with this kit instead of the saved one (brand page preview)."},"preview_text":{"type":["string","null"]},"subject":{"type":["string","null"]}}},"RenderedEmailPreview":{"type":"object","description":"A rendered e-mail.","required":["subject","html"],"properties":{"html":{"type":"string"},"subject":{"type":"string"}}},"ReorderDraftRequest":{"type":"object","properties":{"location_id":{"type":["string","null"],"format":"uuid","description":"Destination for the order."},"supplier_id":{"type":["string","null"],"format":"uuid"},"variant_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Restrict to these variants; omitted means every variant at or below\nits reorder point."}}},"ReorderRequest":{"type":"object","required":["document_ids"],"properties":{"document_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Document ids in their new order; positions become 0, 1, 2, ..."}}},"ReorderSettings":{"type":"object","description":"A variant's reorder settings. Both fields are replaced; null clears.","properties":{"reorder_point":{"type":["integer","null"],"format":"int32","description":"At or below this available quantity the variant counts as low stock.\nNull removes it from low-stock views.","minimum":0},"reorder_quantity":{"type":["integer","null"],"format":"int32","description":"Quantity a reorder draft proposes. Null lets the draft fill up to the\nreorder point.","minimum":1}}},"ReplaceUserRolesRequest":{"type":"object","required":["role_ids"],"properties":{"role_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Full set of role ids the user should hold after this call. Anything\nnot in the list is removed; an empty list removes the user from the\nstore."}}},"RepoSummary":{"type":"object","description":"A repository the GitHub App can see.","required":["id","full_name","private"],"properties":{"default_branch":{"type":["string","null"]},"full_name":{"type":"string","description":"`owner/name`."},"id":{"type":"integer","format":"int64"},"private":{"type":"boolean"}}},"ResendUnopenedRequest":{"type":"object","description":"Who a follow-up goes to, and with what subject.","required":["subject"],"properties":{"name":{"type":["string","null"],"description":"Campaign name. Defaults to \"Reenvio para quem não abriu\"."},"send_now":{"type":["boolean","null"],"description":"Send right away (default) or leave as a draft."},"subject":{"type":"string","description":"Subject of the follow-up."}}},"Reservation":{"type":"object","description":"Units of a variant held for an order line (or its build job).","required":["id","variant_id","sku","variant_name","quantity","status","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"location_id":{"type":["string","null"],"format":"uuid"},"location_name":{"type":["string","null"]},"order_id":{"type":["string","null"],"format":"uuid"},"order_item_id":{"type":["string","null"],"format":"uuid"},"order_number":{"type":["string","null"]},"quantity":{"type":"integer","format":"int32"},"sku":{"type":"string"},"status":{"$ref":"#/components/schemas/ReservationStatus"},"updated_at":{"type":"string","format":"date-time"},"variant_id":{"type":"string","format":"uuid"},"variant_name":{"type":"string"}}},"ReservationCloseResult":{"type":"object","description":"A closed reservation and the stock it touched.","required":["reservation","stock"],"properties":{"reservation":{"$ref":"#/components/schemas/Reservation"},"stock":{"$ref":"#/components/schemas/VariantStock","description":"The variant's stock after closing."}}},"ReservationStatus":{"type":"string","description":"Where a reservation stands. `active` holds units; the others are closed.","enum":["active","released","consumed","expired","cancelled"]},"Review":{"type":"object","description":"A product review.","required":["id","store_id","product_id","author_name","author_email","rating","body","status","is_verified_purchase","created_at","updated_at"],"properties":{"author_email":{"type":"string"},"author_name":{"type":"string"},"body":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"customer_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"is_verified_purchase":{"type":"boolean","description":"The author's e-mail bought the product in this store."},"order_id":{"type":["string","null"],"format":"uuid"},"product_id":{"type":"string","format":"uuid"},"rating":{"type":"integer","format":"int32","description":"1 to 5."},"status":{"$ref":"#/components/schemas/ReviewStatus"},"store_id":{"type":"string","format":"uuid"},"title":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}},"ReviewSettings":{"type":"object","description":"The store's review settings.","required":["reviews_enabled","reviews_require_approval"],"properties":{"reviews_enabled":{"type":"boolean","description":"Shoppers can submit reviews."},"reviews_require_approval":{"type":"boolean","description":"New reviews wait as `pending` until approved; otherwise they are\n`approved` on submission."}}},"ReviewSettingsUpdateRequest":{"type":"object","description":"Settings to change; omitted fields keep their value.","properties":{"reviews_enabled":{"type":["boolean","null"]},"reviews_require_approval":{"type":["boolean","null"]}}},"ReviewStatus":{"type":"string","description":"`pending` (waiting for moderation), `approved` (shown on the storefront)\nor `rejected`.","enum":["pending","approved","rejected"]},"ReviewUpdateRequest":{"type":"object","description":"A moderation decision.","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ReviewStatus"}}},"ReviewWithProduct":{"allOf":[{"$ref":"#/components/schemas/Review"},{"type":"object","required":["product_title","product_slug"],"properties":{"product_slug":{"type":"string"},"product_title":{"type":"string"}}}],"description":"A review with the product it is about."},"ReviseBrandSystemRequest":{"type":"object","description":"An instruction for the assistant.","required":["prompt"],"properties":{"prompt":{"type":"string","description":"What to change, in plain words."},"system":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BrandSystem","description":"Unsaved edits to revise on top of; defaults to the saved system."}]}}},"ReviseEmailBrandKitRequest":{"type":"object","required":["prompt"],"properties":{"kit":{"type":["object","null"],"description":"Kit being edited (unsaved changes included); defaults to the saved one."},"prompt":{"type":"string","description":"The change wanted, in the merchant's words."}}},"RoleAuditEntry":{"type":"object","description":"A change to roles or membership.","required":["id","action","created_at"],"properties":{"action":{"type":"string","description":"`role.created`, `role.updated`, `role.deleted`, `assignment.replaced`,\n`invite.created`, `invite.accepted`, `member.removed`,\n`owner.transferred`. More may be added."},"actor_id":{"type":["string","null"],"format":"uuid"},"actor_name":{"type":["string","null"]},"after":{"type":["object","null"]},"before":{"type":["object","null"]},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"role_id":{"type":["string","null"],"format":"uuid"},"subject_name":{"type":["string","null"]},"subject_user":{"type":["string","null"],"format":"uuid"}}},"RoleSummary":{"type":"object","required":["id","name","is_system"],"properties":{"color":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_system":{"type":"boolean"},"name":{"type":"string"}}},"RunWithSteps":{"allOf":[{"$ref":"#/components/schemas/WorkflowRun"},{"type":"object","required":["steps"],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunStep"}}}}],"description":"A run with its steps, oldest step first."},"SalesChannel":{"type":"object","description":"A sales channel.","required":["id","store_id","name","channel_type","is_active","api_key_prefix","created_at","updated_at"],"properties":{"api_key_prefix":{"type":"string","description":"First characters of the channel's API key (`msc_live_…`), empty when\nnone was generated. The key itself is shown once, at generation."},"channel_type":{"$ref":"#/components/schemas/SalesChannelType"},"config_json":{"type":["object","null"],"description":"Channel-specific settings."},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"name":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"url":{"type":["string","null"]}}},"SalesChannelApiKey":{"type":"object","description":"A freshly generated channel API key.","required":["key","prefix"],"properties":{"key":{"type":"string","description":"The key. Shown only here; store it now."},"prefix":{"type":"string","description":"What `api_key_prefix` will show from now on."}}},"SalesChannelAssignment":{"type":"object","description":"Which sales channels show a product or a collection.","required":["all","sales_channel_ids"],"properties":{"all":{"type":"boolean","description":"Every channel, present and future. `sales_channel_ids` is then empty."},"sales_channel_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The channels, when `all` is false."}}},"SalesChannelCreateRequest":{"type":"object","description":"A new sales channel.","required":["name","channel_type"],"properties":{"channel_type":{"$ref":"#/components/schemas/SalesChannelType"},"config_json":{"type":["object","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"name":{"type":"string"},"url":{"type":["string","null"]}}},"SalesChannelType":{"type":"string","description":"The kind of channel. A store has at most one `web` channel: its\nstorefront.","enum":["web","instagram","marketplace","whatsapp","pos"]},"SalesChannelUpdateRequest":{"type":"object","description":"Fields to change; omitted fields keep their value.","properties":{"channel_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SalesChannelType"}]},"config_json":{"type":["object","null"]},"is_active":{"type":["boolean","null"]},"name":{"type":["string","null"]},"url":{"type":["string","null"]}}},"SaveBrandSystemRequest":{"type":"object","description":"A brand system to save.","required":["system"],"properties":{"summary":{"type":["string","null"],"description":"What changed, for the version list. Defaults to \"Edição manual\"."},"system":{"$ref":"#/components/schemas/BrandSystem","description":"The whole system. Lenient: missing fields take defaults, numbers\nmay come as strings (`\"16px\"`), unknown fields are dropped."}}},"SaveTransactionalEmailRequest":{"type":"object","description":"A transactional e-mail's content.","required":["subject","mode"],"properties":{"blocks":{"type":["object","null"]},"design":{"type":["object","null"],"description":"Block document; wins over `blocks`."},"html":{"type":["string","null"],"description":"Required (not blank) in `html` mode."},"is_enabled":{"type":["boolean","null"],"description":"Defaults to true."},"mode":{"$ref":"#/components/schemas/TransactionalEmailMode"},"preview_text":{"type":["string","null"]},"subject":{"type":"string","description":"Not empty."}}},"SearchResults":{"type":"object","description":"Hits per kind of record. A group the caller may not read is empty.","required":["orders","customers","products","campaigns","conversations"],"properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/CampaignHit"}},"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationHit"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/CustomerHit"}},"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderHit"}},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductHit"}}}},"SelectionMode":{"type":"string","enum":["single","multiple"]},"SendTestEmailRequest":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"Inbox to send the test to."}}},"SesAccountQuota":{"type":"object","description":"The platform's SES sending quota (shared by every store).","required":["max_24h","max_rate","sent_24h","production"],"properties":{"max_24h":{"type":"number","format":"double"},"max_rate":{"type":"number","format":"double"},"production":{"type":"boolean"},"sent_24h":{"type":"number","format":"double"}}},"Session":{"type":"object","description":"A signed-in session: an access token, the refresh token that renews it,\nand the user.","required":["token","token_type","expires_in","refresh_token","refresh_token_expires_in","session_id","user"],"properties":{"expires_in":{"type":"integer","format":"int64","description":"Seconds until `token` expires.","example":86400},"refresh_token":{"type":"string","description":"Opaque refresh token (`mobi_rt_…`). Store it securely and trade it at\n`POST /auth/refresh` for a new pair before or after `token` expires.\nEach refresh token works once."},"refresh_token_expires_in":{"type":"integer","format":"int64","description":"Seconds until `refresh_token` expires if it is not used.","example":2592000},"session_id":{"type":"string","format":"uuid","description":"The session id, as listed by `GET /me/sessions`."},"token":{"type":"string","description":"Access token (a JWT). Send it as `Authorization: Bearer <token>`."},"token_type":{"$ref":"#/components/schemas/TokenType","description":"Always `Bearer`."},"user":{"$ref":"#/components/schemas/User"}}},"SetInventoryModeRequest":{"type":"object","required":["module"],"properties":{"module":{"type":"string","description":"An inventory module code from the registry: `mobi` (native) or\n`tiny` (the ERP owns stock).","example":"mobi"}}},"SetOrderTestRequest":{"type":"object","required":["is_test"],"properties":{"is_test":{"type":"boolean","description":"`true` to archive the order as test data, `false` to restore it."}}},"SetShipmentItemsRequest":{"type":"object","description":"A shipment's new contents.","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentItemInput"}}}},"Shipment":{"type":"object","description":"A box on its way: what is in it, who carries it and where it is.","required":["id","order_id","store_id","status","tracking_events","created_at","updated_at","items"],"properties":{"carrier_name":{"type":["string","null"]},"cdf_price_id":{"type":["integer","null"],"format":"int64"},"cdf_quotation_code":{"type":["string","null"]},"cost_cents":{"type":["integer","null"],"format":"int64","description":"What the freight cost the store."},"created_at":{"type":"string","format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"freight_external_order_code":{"type":["string","null"],"description":"The carrier's order code."},"freight_payer":{"type":["string","null"],"description":"`CIF` (store pays) or `FOB` (recipient pays)."},"freight_provider_code":{"type":["string","null"],"description":"`central_do_frete` (lifecycle driven through the carrier API),\n`local_delivery`, `other_carrier` or `pickup` (managed by hand)."},"id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentItem"},"description":"What is in the box. Empty only for a shipment created outside the\nnormal flow; creation fills it with whatever is still unshipped."},"notes":{"type":["string","null"]},"order_id":{"type":"string","format":"uuid"},"shipped_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"store_id":{"type":"string","format":"uuid"},"tracking_code":{"type":["string","null"]},"tracking_events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"},"description":"Tracking events from the carrier, oldest first."},"tracking_json":{"type":["object","null"],"description":"The carrier's last order detail, as received."},"updated_at":{"type":"string","format":"date-time"}}},"ShipmentItem":{"type":"object","description":"Units of one order line in a shipment.","required":["order_item_id","quantity","title","ordered_quantity"],"properties":{"order_item_id":{"type":"string","format":"uuid"},"ordered_quantity":{"type":"integer","format":"int32","description":"Units of the line on the order."},"quantity":{"type":"integer","format":"int32","description":"Units of the line in this box."},"sku":{"type":["string","null"]},"title":{"type":"string"}}},"ShipmentItemInput":{"type":"object","description":"Units of one order line.","required":["order_item_id","quantity"],"properties":{"order_item_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","format":"int32","description":"Units of the line; lines with 0 are dropped."}}},"ShipmentQuote":{"type":"object","description":"Carrier options for a shipment.","required":["options"],"properties":{"expires_at":{"type":["string","null"],"format":"date-time"},"options":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentQuoteOption"}},"quotation_code":{"type":["string","null"],"description":"Pass to `generate` with the chosen option."}}},"ShipmentQuoteOption":{"type":"object","description":"One carrier option of a quote.","required":["option_id","service_name","shipping_cents"],"properties":{"carrier_name":{"type":["string","null"]},"delivery_days":{"type":["integer","null"],"format":"int32"},"option_id":{"type":"string","description":"For Central do Frete, the `price_id` to generate with."},"provider_code":{"type":"string"},"quotation_code":{"type":["string","null"]},"raw":{"type":"object","description":"The carrier's option as received."},"service_name":{"type":"string"},"shipping_cents":{"type":"integer","format":"int64"}}},"ShipmentStatus":{"type":"string","description":"Where a shipment is.\n\n`draft` (being prepared), `ordered` (freight order created at the\ncarrier), `collected` (picked up), `in_transit`, `shipped` (left, for\nshipments the store delivers itself), `delivered`, `cancelled`.\n`ordered` through `delivered` count as out the door.","enum":["draft","ordered","collected","in_transit","shipped","delivered","cancelled"]},"ShipmentVolume":{"type":"object","description":"One package.","required":["quantity","width","height","length","weight"],"properties":{"height":{"type":"number","format":"double","description":"Centimetres."},"length":{"type":"number","format":"double","description":"Centimetres."},"quantity":{"type":"integer","format":"int32"},"weight":{"type":"number","format":"double","description":"Kilograms."},"width":{"type":"number","format":"double","description":"Centimetres."}}},"ShippingBox":{"type":"object","description":"A box size the store ships in.","required":["id","store_id","name","cost_cents","is_active","created_at","updated_at"],"properties":{"cost_cents":{"type":"integer","format":"int64"},"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"height_cm":{"type":["number","null"],"format":"double"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"length_cm":{"type":["number","null"],"format":"double","description":"Outer dimensions in centimetres."},"max_weight_grams":{"type":["integer","null"],"format":"int32"},"name":{"type":"string"},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"weight_grams":{"type":["integer","null"],"format":"int32","description":"Weight of the empty box."},"width_cm":{"type":["number","null"],"format":"double"}}},"ShippingBoxCreateRequest":{"type":"object","required":["name"],"properties":{"cost_cents":{"type":["integer","null"],"format":"int64","description":"Defaults to 0."},"description":{"type":["string","null"]},"height_cm":{"type":["number","null"],"format":"double"},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"length_cm":{"type":["number","null"],"format":"double"},"max_weight_grams":{"type":["integer","null"],"format":"int32"},"name":{"type":"string"},"weight_grams":{"type":["integer","null"],"format":"int32"},"width_cm":{"type":["number","null"],"format":"double"}}},"ShippingBoxUpdateRequest":{"type":"object","description":"Fields to change; omitted ones stay.","properties":{"cost_cents":{"type":["integer","null"],"format":"int64"},"description":{"type":["string","null"]},"height_cm":{"type":["number","null"],"format":"double"},"is_active":{"type":["boolean","null"]},"length_cm":{"type":["number","null"],"format":"double"},"max_weight_grams":{"type":["integer","null"],"format":"int32"},"name":{"type":["string","null"]},"weight_grams":{"type":["integer","null"],"format":"int32"},"width_cm":{"type":["number","null"],"format":"double"}}},"ShippingContact":{"type":"object","description":"Contact and delivery address typed at checkout.","properties":{"additional_info":{"type":["string","null"]},"city":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF/CNPJ typed at checkout."},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"state":{"type":["string","null"],"description":"Two-letter state (UF)."},"street":{"type":["string","null"]},"zip_code":{"type":["string","null"]}}},"SpecField":{"type":"object","required":["id","group_id","name","name_translations","slug","kind","multiple","display_as_link","external_mapping","sort_order","allow_freeform"],"properties":{"allow_freeform":{"type":"boolean"},"display_as_link":{"type":"boolean"},"external_mapping":{"type":"object","description":"How the field maps to marketplace attributes."},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"`text`, `longtext`, `number`, `dimension`, `weight`, `boolean`,\n`taxonomy`, `collection_ref`, ... More may be added."},"multiple":{"type":"boolean"},"name":{"type":"string"},"name_translations":{"type":"object"},"slug":{"type":"string"},"sort_order":{"type":"integer","format":"int32"},"taxonomy_id":{"type":["string","null"],"format":"uuid"},"unit":{"type":["string","null"]}}},"SpecGroup":{"type":"object","required":["id","name","name_translations","slug","sort_order"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"name_translations":{"type":"object","description":"`{ \"en-US\": \"...\", ... }`"},"slug":{"type":"string"},"sort_order":{"type":"integer","format":"int32"}}},"StartAssistantPhoneVerificationRequest":{"type":"object","description":"A phone to link to the assistant on WhatsApp.","required":["phone_e164"],"properties":{"phone_e164":{"type":"string","description":"With country code (`+55 11 98765-4321`); spaces, dashes and `+` are\nignored."}}},"StartWhatsappSetupRequest":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Phone with country and area code; formatting is ignored.","example":"+55 11 91234-5678"}}},"StockAdjustRequest":{"type":"object","description":"A manual stock adjustment: exactly one of `delta` and `set_to`.","properties":{"delta":{"type":["integer","null"],"format":"int32","description":"Signed change to the units on hand, e.g. `-2` for two broken units.\nNot idempotent: send an `Idempotency-Key` so a retry cannot apply it\ntwice. May not take on-hand below zero."},"force":{"type":"boolean","description":"Write even though an ERP owns this store's stock (see\n`VariantStock.stock_owner`). Use for a variant the ERP does not know."},"location_id":{"type":["string","null"],"format":"uuid","description":"Location to adjust. Defaults to the store's default location. Required\nwith `set_to` when the variant holds stock at more than one location."},"note":{"type":["string","null"],"description":"Free text shown next to the reason in the history."},"reason":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdjustReason","description":"Why. Defaults to `correction`."}]},"set_to":{"type":["integer","null"],"format":"int32","description":"Absolute count of units on hand at the location, e.g. what a shelf\ncount found. Idempotent by nature. The ledger records the difference.","minimum":0}}},"StockAdjustResult":{"type":"object","description":"The outcome of a stock write.","required":["location_id","stock"],"properties":{"location_id":{"type":"string","format":"uuid","description":"The location that was adjusted."},"movement_id":{"type":["string","null"],"format":"uuid","description":"The ledger entry written; null when nothing changed (`delta` 0, or\n`set_to` equal to the current count). Undo it with\n`reverseStockMovement`."},"stock":{"$ref":"#/components/schemas/VariantStock","description":"The variant's stock after the write."}}},"StockCount":{"type":"object","description":"A count sheet for one location.","required":["id","store_id","location_id","status","created_at","item_count","counted_count","variance_count"],"properties":{"counted_count":{"type":"integer","format":"int64","description":"Lines somebody has entered a number for."},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"format":"uuid"},"created_by_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"item_count":{"type":"integer","format":"int64","description":"Lines on the sheet."},"location_id":{"type":"string","format":"uuid"},"location_name":{"type":["string","null"]},"name":{"type":["string","null"]},"note":{"type":["string","null"]},"posted_at":{"type":["string","null"],"format":"date-time"},"posted_by":{"type":["string","null"],"format":"uuid"},"status":{"$ref":"#/components/schemas/StockCountStatus"},"store_id":{"type":"string","format":"uuid"},"variance_count":{"type":"integer","format":"int64","description":"Counted lines that disagree with the book."}}},"StockCountCreateRequest":{"type":"object","properties":{"location_id":{"type":["string","null"],"format":"uuid","description":"Defaults to the store's default location."},"name":{"type":["string","null"]},"note":{"type":["string","null"]},"search":{"type":["string","null"],"description":"Restrict the sheet to variants matching a SKU or name fragment.\nOmitted draws every active variant, which a full inventory needs."}}},"StockCountDetail":{"allOf":[{"$ref":"#/components/schemas/StockCount"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StockCountItem"},"description":"Up to 2000 lines matching the filters, by name."}}}],"description":"A count sheet with its lines."},"StockCountImportResult":{"type":"object","required":["applied","unmatched","invalid"],"properties":{"applied":{"type":"integer","description":"Lines filled from the file.","minimum":0},"invalid":{"type":"array","items":{"type":"string"},"description":"SKUs whose quantity could not be read (or was negative)."},"unmatched":{"type":"array","items":{"type":"string"},"description":"SKUs in the file that are not on the sheet."}}},"StockCountItem":{"type":"object","description":"One line of a count sheet.","required":["id","item_id","sku","name","expected_qty","current_qty"],"properties":{"barcode":{"type":["string","null"]},"counted_qty":{"type":["integer","null"],"format":"int32","description":"What was counted; null until entered (\"not counted\" is not 0)."},"current_qty":{"type":"integer","format":"int32","description":"On hand at the location right now, to warn when stock moved since\nthe sheet was drawn."},"expected_qty":{"type":"integer","format":"int32","description":"On hand at the location when the sheet was drawn."},"id":{"type":"string","format":"uuid","description":"The line id."},"item_id":{"type":"string","format":"uuid","description":"The variant id."},"name":{"type":"string"},"sku":{"type":"string"}}},"StockCountLineUpdate":{"type":"object","properties":{"counted_qty":{"type":["integer","null"],"format":"int32","description":"Units counted. Null clears the entry back to \"not counted\", which is\nnot the same as 0.","minimum":0}}},"StockCountPostRequest":{"type":"object","properties":{"force":{"type":"boolean","description":"Post even though an ERP owns this store's stock."},"treat_uncounted_as_zero":{"type":"boolean","description":"Treat lines nobody counted as zero. Off by default because \"I did not\nget to that shelf\" and \"there are none\" are different statements, and\nconflating them silently writes stock off."}}},"StockCountPostResult":{"type":"object","required":["count","applied","skipped_uncounted","net_delta","levels"],"properties":{"applied":{"type":"integer","format":"int64","description":"Lines whose difference was written to the ledger."},"count":{"$ref":"#/components/schemas/StockCount","description":"The count, now `posted`."},"levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevelChange"},"description":"The new level of every variant the count changed."},"net_delta":{"type":"integer","format":"int64","description":"Sum of counted minus expected over the applied lines."},"skipped_uncounted":{"type":"integer","format":"int64","description":"Uncounted lines left alone."}}},"StockCountStatus":{"type":"string","description":"Where a count stands. `draft` and `counting` accept entries; `posted`\nand `cancelled` are closed.","enum":["draft","counting","posted","cancelled"]},"StockLevel":{"type":"object","description":"A variant's stock at one inventory location. Same shape as the\n`stock_by_location` rows on product and variant reads, plus `is_default`\nand `is_active` (and `available` here never goes below zero).","required":["location_id","location_name","is_default","is_active","on_hand","reserved","available"],"properties":{"available":{"type":"integer","format":"int32","description":"`on_hand - reserved`, floored at zero: what can still be promised."},"is_active":{"type":"boolean","description":"Inactive locations only appear while they still hold stock."},"is_default":{"type":"boolean","description":"Where a write goes when it names no location: the store's active\nlocation with the lowest priority."},"location_id":{"type":"string","format":"uuid"},"location_name":{"type":"string"},"on_hand":{"type":"integer","format":"int32","description":"Units physically at the location."},"reserved":{"type":"integer","format":"int32","description":"Units held for open orders and build jobs."}}},"StockLevelChange":{"type":"object","description":"A variant's stock at one location after a write.","required":["variant_id","location_id","on_hand","reserved","available"],"properties":{"available":{"type":"integer","format":"int32","description":"`on_hand - reserved`, floored at zero."},"location_id":{"type":"string","format":"uuid"},"movement_id":{"type":["string","null"],"format":"uuid","description":"The ledger entry written; null when the line changed nothing."},"on_hand":{"type":"integer","format":"int32"},"reserved":{"type":"integer","format":"int32"},"variant_id":{"type":"string","format":"uuid"}}},"StockListItem":{"type":"object","description":"One stocked item (a variant) in the store-wide list.","required":["item_id","sku","name","on_hand","reserved","available","physical","logical","uses_bom","incoming","is_active","is_component"],"properties":{"available":{"type":"integer","format":"int32","description":"`on_hand - reserved`, floored at zero."},"buildable":{"type":["integer","null"],"format":"int32","description":"For kits: whole kits the components can still build. Null otherwise."},"cost_cents":{"type":["integer","null"],"format":"int64"},"incoming":{"type":"integer","format":"int32","description":"Outstanding units on ordered, not yet received purchase orders."},"is_active":{"type":"boolean"},"is_component":{"type":"boolean","description":"True when some kit is built from this item."},"item_id":{"type":"string","format":"uuid","description":"The variant id."},"limiting_sku":{"type":["string","null"],"description":"For kits: SKU of the component that caps `buildable`."},"logical":{"type":"integer","format":"int32","description":"Logical stock: what can still be promised (same as `available`)."},"name":{"type":"string"},"on_hand":{"type":"integer","format":"int32"},"parent_name":{"type":["string","null"],"description":"Product title."},"physical":{"type":"integer","format":"int32","description":"Physical stock: what is on the shelves, ignoring reservations\n(same as `on_hand`)."},"product_id":{"type":["string","null"],"format":"uuid"},"reorder_point":{"type":["integer","null"],"format":"int32"},"reorder_quantity":{"type":["integer","null"],"format":"int32"},"reserved":{"type":"integer","format":"int32"},"sku":{"type":"string"},"uses_bom":{"type":"boolean","description":"True for kits (the item has a bill of materials)."}}},"StockMovement":{"type":"object","description":"One entry of the stock ledger: a quantity that moved, and why.","required":["id","event_type","quantity_delta","created_at"],"properties":{"actor_name":{"type":["string","null"]},"actor_user_id":{"type":["string","null"],"format":"uuid","description":"Who made a manual movement; null for automatic ones."},"balance_after":{"type":["integer","null"],"format":"int32","description":"Units on hand at the location right after this movement."},"created_at":{"type":"string","format":"date-time"},"event_type":{"$ref":"#/components/schemas/MovementKind"},"id":{"type":"string","format":"uuid"},"location_id":{"type":["string","null"],"format":"uuid"},"location_name":{"type":["string","null"]},"name":{"type":["string","null"]},"note":{"type":["string","null"]},"order_id":{"type":["string","null"],"format":"uuid"},"order_number":{"type":["string","null"]},"product_id":{"type":["string","null"],"format":"uuid"},"quantity_delta":{"type":"integer","format":"int32","description":"Signed change to on-hand units (for `reserve`/`release`, the change\nto reserved units)."},"reason":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdjustReason","description":"Set on manual adjustments."}]},"reference_id":{"type":["string","null"],"format":"uuid"},"reference_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/MovementReferenceType"}]},"reversal_of":{"type":["string","null"],"format":"uuid","description":"The movement this one undoes."},"reversed_by":{"type":["string","null"],"format":"uuid","description":"The movement that undid this one."},"sku":{"type":["string","null"]},"unit_cost_cents":{"type":["integer","null"],"format":"int64","description":"Landed unit cost, on purchase receipts."},"variant_id":{"type":["string","null"],"format":"uuid"}}},"StockOverview":{"type":"object","description":"The numbers the stock landing page leads with.","required":["out_of_stock","low_stock","tracked_items","total_on_hand","total_reserved","total_logical","active_reservations","stock_value_cents","open_purchase_orders","overdue_purchase_orders","counts_in_progress"],"properties":{"active_reservations":{"type":"integer","format":"int64"},"counts_in_progress":{"type":"integer","format":"int64"},"low_stock":{"type":"integer","format":"int64","description":"Active variants with something available but at or below their\nreorder point."},"open_purchase_orders":{"type":"integer","format":"int64"},"out_of_stock":{"type":"integer","format":"int64","description":"Active variants with nothing available."},"overdue_purchase_orders":{"type":"integer","format":"int64","description":"Open purchase orders past their expected date."},"stock_owner":{"type":["string","null"],"description":"Code of the ERP that owns the store's stock, null when Mobiari does."},"stock_owner_name":{"type":["string","null"]},"stock_value_cents":{"type":"integer","format":"int64","description":"On-hand units valued at cost."},"total_logical":{"type":"integer","format":"int64","description":"Sum of available units."},"total_on_hand":{"type":"integer","format":"int64"},"total_reserved":{"type":"integer","format":"int64"},"tracked_items":{"type":"integer","format":"int64"}}},"StockReversalResult":{"type":"object","required":["reversal_id","stock"],"properties":{"reversal_id":{"type":"string","format":"uuid","description":"The new `adjustment` movement that undoes the original."},"stock":{"$ref":"#/components/schemas/VariantStock","description":"The variant's stock after the reversal."}}},"StockReverseRequest":{"type":"object","properties":{"force":{"type":"boolean","description":"Write even though an ERP owns this store's stock."},"note":{"type":["string","null"],"description":"Shown on the reversal in the history. Defaults to \"Estorno\"."}}},"StockTransferRequest":{"type":"object","description":"Move units between two of the store's locations.","required":["from_location_id","to_location_id","quantity"],"properties":{"force":{"type":"boolean","description":"Write even though an ERP owns this store's stock."},"from_location_id":{"type":"string","format":"uuid"},"note":{"type":["string","null"]},"quantity":{"type":"integer","format":"int32","description":"Units to move; at most what is available (on hand minus reserved) at\nthe source.","minimum":1},"to_location_id":{"type":"string","format":"uuid"}}},"StockTransferResult":{"type":"object","required":["transfer_id","stock"],"properties":{"stock":{"$ref":"#/components/schemas/VariantStock","description":"The variant's stock after the transfer."},"transfer_id":{"type":"string","format":"uuid","description":"Links the two `transfer` ledger entries (their `reference_id`)."}}},"StorageSummary":{"type":"object","description":"Storage use of the tenant.","required":["used_bytes","limit_bytes","file_count","folder_count"],"properties":{"file_count":{"type":"integer","format":"int64"},"folder_count":{"type":"integer","format":"int64"},"limit_bytes":{"type":"integer","format":"int64"},"used_bytes":{"type":"integer","format":"int64"}}},"Store":{"type":"object","description":"A store: one catalog, storefront and order book inside a tenant.","required":["id","tenant_id","owner_id","name","slug","is_active","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"name":{"type":"string"},"owner_id":{"type":"string","format":"uuid"},"slug":{"type":"string","description":"URL-safe name, used in storefront URLs."},"tenant_id":{"type":"string","format":"uuid"}}},"StoreAccess":{"type":"object","description":"One store the user can reach, and what they may do there.","required":["store_id","tenant_id","store_name","store_slug","tenant_name","is_owner","permissions","roles"],"properties":{"currency":{"type":["string","null"],"description":"ISO 4217 currency the store sells in (the store's setting, else its\ntenant's).","example":"BRL"},"is_owner":{"type":"boolean","description":"Owner of the store or of its tenant: may do everything."},"logo_url":{"type":["string","null"],"description":"The store's logo from its brand system, if it has one. Absolute URL\nas uploaded."},"permissions":{"type":"array","items":{"type":"string"},"description":"Effective permission codes; `[\"*\"]` for owners. Codes are listed in\n`GET /permissions/catalog`."},"roles":{"type":"array","items":{"$ref":"#/components/schemas/RoleSummary"}},"store_id":{"type":"string","format":"uuid"},"store_name":{"type":"string"},"store_slug":{"type":"string","description":"The store's URL-safe name."},"tenant_id":{"type":"string","format":"uuid"},"tenant_name":{"type":"string","description":"Name of the tenant (organization) the store belongs to."},"timezone":{"type":["string","null"],"description":"IANA time zone the store reports in (the store's setting, else its\ntenant's). Dashboards count days in this zone.","example":"America/Sao_Paulo"}}},"StoreCapabilities":{"type":"object","description":"The capability registry with the store's current choices.","required":["capabilities","selections"],"properties":{"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/Capability"},"description":"Every capability and its modules. A fixed registry that changes\nonly with releases."},"selections":{"$ref":"#/components/schemas/CapabilitySelections"}}},"StoreFulfillmentSettings":{"type":"object","description":"Operational settings: stock reservation, dispatch time, cart recovery\nand review requests.","required":["id","cart_reservation_minutes","dispatch_days","abandoned_cart_recovery_enabled","abandoned_cart_delay_minutes","review_request_enabled","review_request_delay_days"],"properties":{"abandoned_cart_delay_minutes":{"type":"integer","format":"int32","description":"Minutes after abandonment before the recovery message, 1 to 10080."},"abandoned_cart_recovery_enabled":{"type":"boolean"},"cart_reservation_minutes":{"type":"integer","format":"int32","description":"How long a cart holds stock, 1 to 1440 minutes."},"dispatch_days":{"type":"integer","format":"int32","description":"Business days to dispatch an order, 0 to 365; added to freight quotes."},"id":{"type":"string","format":"uuid","description":"The store id."},"review_request_delay_days":{"type":"integer","format":"int32","description":"Days after delivery before asking for a review, 0 to 90."},"review_request_enabled":{"type":"boolean"}}},"StoreInvite":{"type":"object","description":"An invitation to join a store with a set of roles. Its acceptance token\nis never part of this: it is delivered only to the invited e-mail.","required":["id","store_id","invited_by","email","role_ids","role_names","status","expires_at","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"invited_by":{"type":"string","format":"uuid"},"invited_by_name":{"type":["string","null"]},"role_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Roles the invitee receives on acceptance."},"role_names":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/InviteStatus"},"store_id":{"type":"string","format":"uuid"}}},"StoreLocation":{"type":"object","description":"A physical location of the store.","required":["id","store_id","slug","name","country","timezone","hours_json","photos_json","amenities_json","is_pickup_enabled","pickup_lead_minutes","pickup_fee_cents","is_locator_visible","is_active","position","created_at","updated_at"],"properties":{"amenities_json":{"type":"array","items":{"type":"string"},"description":"Amenity labels, e.g. `estacionamento`."},"city":{"type":["string","null"]},"complement":{"type":["string","null"]},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"email":{"type":["string","null"]},"hours_json":{"type":"object","description":"Opening hours, as the admin editor writes them."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_locator_visible":{"type":"boolean","description":"Listed in the storefront store locator."},"is_pickup_enabled":{"type":"boolean","description":"Shoppers can pick orders up here."},"latitude":{"type":["number","null"],"format":"double"},"longitude":{"type":["number","null"],"format":"double"},"name":{"type":"string"},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"photos_json":{"type":"array","items":{"$ref":"#/components/schemas/StoreLocationPhoto"}},"pickup_fee_cents":{"type":"integer","format":"int64","description":"Charged as shipping when a shopper picks up here."},"pickup_instructions":{"type":["string","null"]},"pickup_lead_minutes":{"type":"integer","format":"int32","description":"How long after the order the pickup is ready."},"position":{"type":"integer","format":"int32","description":"Sort order, ascending."},"postal_code":{"type":["string","null"]},"slug":{"type":"string","description":"Unique within the store."},"state":{"type":["string","null"]},"store_id":{"type":"string","format":"uuid"},"street":{"type":["string","null"]},"timezone":{"type":"string","description":"IANA time zone of `hours_json`."},"updated_at":{"type":"string","format":"date-time"},"whatsapp":{"type":["string","null"]}}},"StoreLocationPhoto":{"type":"object","description":"A photo of a location.","required":["url"],"properties":{"alt":{"type":["string","null"]},"url":{"type":"string"}}},"StoreLocationRequest":{"type":"object","description":"A location to create.","required":["name"],"properties":{"amenities_json":{"type":["array","null"],"items":{"type":"string"}},"city":{"type":["string","null"]},"complement":{"type":["string","null"]},"country":{"type":["string","null"],"description":"Defaults to `BR`."},"description":{"type":["string","null"]},"email":{"type":["string","null"]},"hours_json":{"type":["object","null"]},"is_active":{"type":["boolean","null"]},"is_locator_visible":{"type":["boolean","null"]},"is_pickup_enabled":{"type":["boolean","null"]},"latitude":{"type":["number","null"],"format":"double"},"longitude":{"type":["number","null"],"format":"double"},"name":{"type":"string"},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"photos_json":{"type":["array","null"],"items":{"$ref":"#/components/schemas/StoreLocationPhoto"}},"pickup_fee_cents":{"type":["integer","null"],"format":"int64"},"pickup_instructions":{"type":["string","null"]},"pickup_lead_minutes":{"type":["integer","null"],"format":"int32"},"position":{"type":["integer","null"],"format":"int32"},"postal_code":{"type":["string","null"]},"slug":{"type":["string","null"],"description":"Defaults to one derived from the name."},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"timezone":{"type":["string","null"],"description":"Defaults to `America/Sao_Paulo`."},"whatsapp":{"type":["string","null"]}}},"StoreLocationUpdateRequest":{"type":"object","description":"New values for a location. Omitted fields keep their value; send `null`\nto clear a nullable one.","required":["name"],"properties":{"amenities_json":{"type":["array","null"],"items":{"type":"string"}},"city":{"type":["string","null"]},"complement":{"type":["string","null"]},"country":{"type":["string","null"]},"description":{"type":["string","null"]},"email":{"type":["string","null"]},"hours_json":{"type":["object","null"]},"is_active":{"type":["boolean","null"]},"is_locator_visible":{"type":["boolean","null"]},"is_pickup_enabled":{"type":["boolean","null"]},"latitude":{"type":["number","null"],"format":"double"},"longitude":{"type":["number","null"],"format":"double"},"name":{"type":"string"},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"photos_json":{"type":["array","null"],"items":{"$ref":"#/components/schemas/StoreLocationPhoto"}},"pickup_fee_cents":{"type":["integer","null"],"format":"int64"},"pickup_instructions":{"type":["string","null"]},"pickup_lead_minutes":{"type":["integer","null"],"format":"int32"},"position":{"type":["integer","null"],"format":"int32"},"postal_code":{"type":["string","null"]},"slug":{"type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"timezone":{"type":["string","null"]},"whatsapp":{"type":["string","null"]}}},"StoreMember":{"type":"object","description":"Someone with access to a store: its owner, or a user holding a role.","required":["id","email","is_active","is_owner","roles"],"properties":{"email":{"type":"string"},"full_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid","description":"The user id."},"is_active":{"type":"boolean"},"is_owner":{"type":"boolean"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/MemberRole"},"description":"Roles held in this store (empty for an owner without an explicit role)."}}},"StoreRole":{"type":"object","description":"A named set of permissions in a store.","required":["id","store_id","name","permission_codes","position","is_system","created_at","updated_at"],"properties":{"color":{"type":["string","null"],"description":"Display color token."},"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_system":{"type":"boolean","description":"A built-in preset: cannot be deleted."},"name":{"type":"string"},"permission_codes":{"type":"array","items":{"type":"string"},"description":"Permission codes from `GET /permissions/catalog`; `[\"*\"]` means\neverything."},"position":{"type":"integer","format":"int32","description":"Sort order in lists; lower first."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"}}},"StoreUsage":{"type":"object","description":"Metered usage of the store.","required":["days","series","totals","month","email_caps"],"properties":{"days":{"type":"integer","format":"int64"},"email_caps":{"$ref":"#/components/schemas/EmailSendCap"},"month":{"type":"object","description":"Per metric this calendar month.","additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}},"series":{"type":"array","items":{"$ref":"#/components/schemas/StoreUsagePoint"},"description":"Per day and metric, oldest first."},"totals":{"type":"object","description":"Per metric over `days`.","additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}}}},"StoreUsagePoint":{"type":"object","description":"One metric on one day.","required":["day","metric","value"],"properties":{"day":{"type":"string","format":"date"},"metric":{"type":"string","description":"e.g. `emails_sent`, `assistant_tokens`."},"value":{"type":"integer","format":"int64"}}},"StoreWorkflowRun":{"type":"object","description":"A run with its workflow's name, for the store-wide runs page.","required":["id","workflow_id","workflow_name","status","dry_run","attempt","created_at"],"properties":{"attempt":{"type":"integer","format":"int32"},"created_at":{"type":"string","format":"date-time"},"current_node_id":{"type":["string","null"]},"customer_id":{"type":["string","null"],"format":"uuid"},"dry_run":{"type":"boolean"},"error_message":{"type":["string","null"]},"finished_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"next_run_at":{"type":["string","null"],"format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/WorkflowRunStatus"},"workflow_id":{"type":"string","format":"uuid"},"workflow_name":{"type":"string"}}},"StoredEvent":{"type":"object","description":"An outbox row as the dispatcher and the admin read it.","required":["id","name","entity_type","payload","occurred_at","attempts","completed_subscribers"],"properties":{"attempts":{"type":"integer","format":"int32","description":"Dispatch attempts so far."},"completed_subscribers":{"type":"array","items":{"type":"string"},"description":"Subscribers (workflows, webhooks, alerts) that already handled it."},"customer_id":{"type":["string","null"],"format":"uuid"},"dispatched_at":{"type":["string","null"],"format":"date-time"},"entity_id":{"type":["string","null"],"format":"uuid"},"entity_type":{"type":"string","description":"`order`, `customer`, `product`, ..."},"id":{"type":"string","format":"uuid"},"last_error":{"type":["string","null"]},"name":{"type":"string","description":"Event name, e.g. `orders.paid` (see `GET /events/catalog`)."},"occurred_at":{"type":"string","format":"date-time"},"payload":{"type":"object","description":"The event payload, as delivered to webhooks and workflows."},"store_id":{"type":["string","null"],"format":"uuid"}}},"StorefrontChannel":{"type":"object","required":["account","chats","sessions"],"properties":{"account":{"type":"boolean","description":"Has a storefront login."},"chats":{"type":"integer","format":"int64","description":"Storefront chat conversations."},"last_seen_at":{"type":["string","null"],"format":"date-time"},"sessions":{"type":"integer","format":"int64"}}},"StorefrontDeployment":{"type":"object","description":"One build of the store's theme repository.","required":["id","status","triggered_by","created_at","is_active"],"properties":{"branch_slug":{"type":["string","null"],"description":"Branch, slugified as used in preview hostnames."},"created_at":{"type":"string","format":"date-time"},"error_summary":{"type":["string","null"],"description":"First lines of the build error, when `status` is `failed`."},"git_sha":{"type":["string","null"],"description":"Commit the deployment was built from."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean","description":"Whether this deployment is the one the production storefront serves."},"pr_number":{"type":["integer","null"],"format":"int32"},"promoted_at":{"type":["string","null"],"format":"date-time","description":"When it was last promoted to production."},"ready_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/StorefrontDeploymentStatus"},"triggered_by":{"$ref":"#/components/schemas/StorefrontDeploymentTrigger"}}},"StorefrontDeploymentStatus":{"type":"string","description":"Where a deployment is in its life.","enum":["building","ready","failed","archived"]},"StorefrontDeploymentTrigger":{"type":"string","description":"What started a deployment.","enum":["github","manual","migration"]},"StorefrontPage":{"type":"object","description":"A content page of the storefront.","required":["id","store_id","title","slug","published"],"properties":{"content":{"type":["string","null"],"description":"Page body (HTML)."},"created_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"published":{"type":"boolean","description":"Only published pages render on the storefront."},"slug":{"type":"string","description":"URL segment: the page renders at `/pages/{slug}`. Unique per store."},"store_id":{"type":"string","format":"uuid"},"template":{"type":["string","null"],"description":"Theme template to render with (`page` when unset)."},"title":{"type":"string"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"StorefrontPreviewSettings":{"type":"object","description":"Where the store's preview deployments are served.","properties":{"admin_base_url":{"type":["string","null"],"description":"Base URL of the admin app, where preview visitors sign in."},"preview_suffix":{"type":["string","null"],"description":"Host suffix of preview deployments: a deployment is served at\n`<ref>--<store slug>.<preview_suffix>`, `<ref>` being `pr-<n>`, a\nshort commit sha or a branch slug. Null when previews are off."}}},"Subscribers":{"type":"object","description":"Who listens to an event in a store.","required":["workflows","webhooks","team_alerts"],"properties":{"team_alerts":{"type":"integer","format":"int64","description":"Team alert subscriptions that include it."},"webhooks":{"type":"integer","format":"int64","description":"Active webhooks subscribed to it."},"workflows":{"type":"integer","format":"int64","description":"Active workflows triggered by it."}}},"Subscription":{"type":"object","description":"The organization's subscription.","required":["tenant_id","plan","status","billing_cycle","price_cents","cancel_at_period_end","provider","usage"],"properties":{"billing_cycle":{"$ref":"#/components/schemas/BillingCycle"},"cancel_at_period_end":{"type":"boolean","description":"The subscription ends with the current period (or trial)."},"current_period_end":{"type":["string","null"],"format":"date-time"},"current_period_start":{"type":["string","null"],"format":"date-time","description":"The latest paid period."},"grace_ends_at":{"type":["string","null"],"format":"date-time","description":"When a `past_due` subscription is suspended unless paid."},"open_invoice":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Invoice","description":"The invoice waiting for payment, if any."}]},"pending_plan":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Plan","description":"A downgrade that takes effect at the next renewal."}]},"plan":{"$ref":"#/components/schemas/Plan"},"price_cents":{"type":"integer","format":"int64","description":"What the next period costs, in BRL cents: the catalog price, or the\nprice locked for this organization."},"provider":{"type":"string","description":"Who collects: `manual` (Pix) today."},"status":{"$ref":"#/components/schemas/SubscriptionStatus"},"tenant_id":{"type":"string","format":"uuid"},"trial_days_left":{"type":["integer","null"],"format":"int64","description":"Whole days left in the trial, while `trialing`."},"trial_ends_at":{"type":["string","null"],"format":"date-time"},"usage":{"$ref":"#/components/schemas/SubscriptionUsage"}}},"SubscriptionStatus":{"type":"string","description":"Where a subscription stands.\n\n`trialing` and `active` work normally. `past_due` still works (an\ninvoice is open past its due date, inside the grace period).\n`suspended` (grace period over) and `canceled` keep the data readable\nbut refuse growth: new stores, invites and assistant messages.","enum":["trialing","active","past_due","suspended","canceled"]},"SubscriptionUsage":{"type":"object","description":"What the organization uses against its plan's limits.","required":["stores","seats","storage_bytes","assistant_messages"],"properties":{"assistant_messages":{"type":"integer","format":"int64","description":"Assistant messages this month in the organization's busiest store\n(the limit is per store)."},"seats":{"type":"integer","format":"int64","description":"People with access, pending invites included."},"storage_bytes":{"type":"integer","format":"int64","description":"File library size."},"stores":{"type":"integer","format":"int64"}}},"SuggestedProduct":{"type":"object","description":"A product suggested alongside another (\"you may also like\").","required":["suggested_product_id","title","slug","status","position"],"properties":{"position":{"type":"integer","format":"int32"},"primary_image_url":{"type":["string","null"]},"slug":{"type":"string"},"status":{"$ref":"#/components/schemas/ProductStatus"},"suggested_product_id":{"type":"string","format":"uuid"},"title":{"type":"string"}}},"SuggestedProductsSetRequest":{"type":"object","description":"The suggested products, in order.","required":["suggested_product_ids"],"properties":{"suggested_product_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Products of the same store; others, and the product itself, are\nignored."}}},"Supplier":{"type":"object","required":["id","store_id","name","is_active","created_at","open_orders"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"lead_time_days":{"type":["integer","null"],"format":"int32","description":"Typical days from order to delivery."},"legal_name":{"type":["string","null"]},"name":{"type":"string"},"notes":{"type":["string","null"]},"open_orders":{"type":"integer","format":"int64","description":"Purchase orders ordered and not fully received."},"phone":{"type":["string","null"]},"store_id":{"type":"string","format":"uuid"},"tax_id":{"type":["string","null"],"description":"CNPJ or CPF."}}},"SupplierRequest":{"type":"object","description":"A supplier's fields. On update every field is replaced.","required":["name"],"properties":{"email":{"type":["string","null"]},"is_active":{"type":["boolean","null"],"description":"Defaults to true on create; omitted on update keeps the current value."},"lead_time_days":{"type":["integer","null"],"format":"int32"},"legal_name":{"type":["string","null"]},"name":{"type":"string"},"notes":{"type":["string","null"]},"phone":{"type":["string","null"]},"tax_id":{"type":["string","null"]}}},"Taxonomy":{"type":"object","required":["id","name","name_translations","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"name_translations":{"type":"object"},"slug":{"type":"string"}}},"TaxonomyCategory":{"type":"object","description":"A marketplace category.","required":["value","label"],"properties":{"label":{"type":"string","description":"The full path, levels separated by ` › `."},"value":{"type":"string","description":"The provider's category id (numeric for Google)."}}},"TaxonomyTerm":{"type":"object","required":["id","taxonomy_id","name","name_translations","slug","sort_order","external_values"],"properties":{"external_values":{"type":"object"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"name_translations":{"type":"object"},"parent_id":{"type":["string","null"],"format":"uuid"},"slug":{"type":"string"},"sort_order":{"type":"integer","format":"int32"},"taxonomy_id":{"type":"string","format":"uuid"}}},"TaxonomyWithTerms":{"allOf":[{"$ref":"#/components/schemas/Taxonomy"},{"type":"object","required":["terms"],"properties":{"terms":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyTerm"}}}}]},"TeamAlertEvent":{"type":"string","description":"A sale alert the store team can get on WhatsApp.","enum":["orders.paid","orders.created","orders.cancelled"]},"Tenant":{"type":"object","description":"An organization: owns stores, sets their defaults and holds billing and\nlegal details.","required":["id","owner_id","name","slug","is_active","default_currency","default_locale","timezone","feature_flags","created_at"],"properties":{"contact_email":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"default_currency":{"type":"string","description":"`BRL` or `USD`; new stores start with it.","example":"BRL"},"default_locale":{"type":"string","description":"`pt-BR` or `en-US`.","example":"pt-BR"},"feature_flags":{"type":"object","description":"Feature switches, `{ \"flag.name\": true }`."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"legal_name":{"type":["string","null"]},"name":{"type":"string"},"owner_id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"tax_id":{"type":["string","null"],"description":"CNPJ/CPF or other tax id."},"timezone":{"type":"string","description":"IANA time zone, e.g. `America/Sao_Paulo`."}}},"TestEmailTemplateRequest":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"Inbox to send the test to."}}},"TestTransactionalEmailRequest":{"type":"object","description":"Where `to` is set, the rendered template is sent there.","required":["to","subject","mode"],"properties":{"blocks":{"type":["object","null"]},"design":{"type":["object","null"]},"html":{"type":["string","null"]},"mode":{"$ref":"#/components/schemas/TransactionalEmailMode"},"preview_text":{"type":["string","null"]},"subject":{"type":"string"},"to":{"type":"string","description":"Inbox to send the test to."}}},"TestWorkflowNodeRequest":{"type":"object","description":"A step to try, and the data to try it with.","required":["node"],"properties":{"customer_id":{"type":["string","null"],"format":"uuid","description":"Customer of the store to run it for."},"node":{"$ref":"#/components/schemas/WorkflowNode"},"run_id":{"type":["string","null"],"format":"uuid","description":"Take trigger payload and context from this run of the workflow\n(defaults to its latest run)."},"trigger_payload":{"type":["object","null"],"description":"Or provide the trigger payload directly (e.g. the trigger's sample)."}}},"TimelineEvent":{"type":"object","description":"One thing that happened to a customer, in any module.","required":["module","kind","at"],"properties":{"at":{"type":"string","format":"date-time"},"detail":{"type":["string","null"]},"kind":{"type":"string","description":"Module-specific event kind, e.g. `order_paid`, `email_open`, `visit`."},"meta":{"type":["object","null"],"description":"Ids and figures for linking to the source record."},"module":{"type":"string","description":"`order`, `conversation`, `email`, `storefront`, `consent` or `journey`."},"title":{"type":["string","null"]}}},"TinyAuthorizeUrl":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","description":"Send the merchant here to authorize; Tiny redirects back to the\nprovider's `oauth_redirect_uri` with a `code`."}}},"TinyLinkItem":{"type":"object","description":"One variant in the Tiny link report.","required":["product_id","product_title","sku","linked","fulfillment_mode","is_active","stock_mobi"],"properties":{"fulfillment_mode":{"type":"string"},"is_active":{"type":"boolean"},"linked":{"type":"boolean"},"product_id":{"type":"string","format":"uuid"},"product_status":{"type":["string","null"]},"product_title":{"type":"string"},"sku":{"type":"string"},"stock_mobi":{"type":"integer","format":"int64","description":"Units on hand in Mobiari over every location."},"tiny_product_id":{"type":["string","null"],"description":"Stamped by a sync once the SKU matched a Tiny product."}}},"TinyLinkReport":{"type":"object","description":"Every variant of the store with its Tiny link.","required":["total","linked","unlinked","items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TinyLinkItem"},"description":"Unlinked variants first, then by product and SKU."},"linked":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"unlinked":{"type":"integer","minimum":0}}},"TinyOauthResult":{"type":"object","required":["connected","has_access_token","has_refresh_token"],"properties":{"connected":{"type":"boolean"},"has_access_token":{"type":"boolean"},"has_refresh_token":{"type":"boolean"},"token_expires_at":{"type":["string","null"]}}},"TinyOauthTokenRequest":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The `code` Tiny's redirect carried."},"redirect_uri":{"type":["string","null"],"description":"Defaults to the provider's `oauth_redirect_uri`."}}},"TokenType":{"type":"string","description":"How to present the access token.","enum":["Bearer"]},"TopEvent":{"type":"object","description":"A tracked event name and how often it fired.","required":["event_name","count","unique_visitors"],"properties":{"count":{"type":"integer","format":"int64"},"event_name":{"type":"string"},"unique_visitors":{"type":"integer","format":"int64"}}},"TopPage":{"type":"object","description":"A page and how often it was viewed.","required":["views","unique_visitors"],"properties":{"page_title":{"type":["string","null"],"description":"The most recent title seen for the URL."},"page_url":{"type":["string","null"]},"unique_visitors":{"type":"integer","format":"int64"},"views":{"type":"integer","format":"int64"}}},"TopReferrer":{"type":"object","description":"A referring site and the traffic it sent.","required":["views","unique_visitors"],"properties":{"referrer_host":{"type":["string","null"],"description":"Host of the referrer (`google.com`), without scheme or path."},"unique_visitors":{"type":"integer","format":"int64"},"views":{"type":"integer","format":"int64"}}},"TotpSetupResponse":{"type":"object","required":["secret","qr_code_url"],"properties":{"qr_code_url":{"type":"string","description":"`otpauth://` URL; render it as a QR code."},"secret":{"type":"string","description":"Base32 secret, for typing into the authenticator app."}}},"TrackedEvent":{"type":"object","description":"One event the storefront tracker recorded.","required":["id","visitor_id","session_id","event_name","properties","occurred_at"],"properties":{"cart_id":{"type":["string","null"],"format":"uuid"},"customer_id":{"type":["string","null"],"format":"uuid","description":"The customer, once the visitor was identified."},"event_name":{"type":"string","description":"`pageview`, `identify`, or a custom name the theme sends\n(`add_to_cart`, `begin_checkout`...)."},"fbclid":{"type":["string","null"],"description":"Meta click id."},"gclid":{"type":["string","null"],"description":"Google Ads click id."},"id":{"type":"string","format":"uuid"},"occurred_at":{"type":"string","format":"date-time"},"page_title":{"type":["string","null"]},"page_url":{"type":["string","null"]},"properties":{"type":"object","description":"Free-form properties sent with the event."},"referrer":{"type":["string","null"]},"session_id":{"type":"string","format":"uuid"},"utm_campaign":{"type":["string","null"]},"utm_medium":{"type":["string","null"]},"utm_source":{"type":["string","null"]},"visitor_id":{"type":"string","format":"uuid"}}},"TrackingEvent":{"type":"object","description":"One carrier tracking event, newest last as the carrier reports them.","properties":{"comment":{"type":["string","null"]},"datetime":{"type":["string","null"],"description":"As the carrier sent it: RFC 3339 or `YYYY-MM-DD HH:MM:SS` (local).\nPrefer `occurred_at`."},"event":{"type":["string","null"]},"occurred_at":{"type":["string","null"],"format":"date-time","description":"`datetime` parsed, as RFC 3339 UTC. Times without an offset are\nread as Brasília time (`America/Sao_Paulo`), the carriers' local\ntime. Null when `datetime` is missing or unreadable."}}},"TransactionalEmailDetail":{"type":"object","description":"A transactional e-mail with what the editor needs around it.","required":["event","label","description","trigger","template","default_subject","default_blocks","default_design","blocks_catalog","variables"],"properties":{"blocks_catalog":{"type":"object","description":"Block types the transactional editor offers."},"default_blocks":{"type":"object"},"default_design":{"type":"object"},"default_subject":{"type":"string","description":"What \"reset\" would restore."},"description":{"type":"string"},"event":{"type":"string"},"label":{"type":"string"},"template":{"$ref":"#/components/schemas/TransactionalEmailTemplate"},"trigger":{"type":"string"},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TransactionalEmailVariable"}}}},"TransactionalEmailMode":{"type":"string","description":"How a transactional e-mail's body is written.","enum":["blocks","html"]},"TransactionalEmailSummary":{"type":"object","description":"One transactional e-mail as the store sends it today.","required":["event","label","description","trigger","subject","is_customized","is_enabled"],"properties":{"description":{"type":"string"},"event":{"type":"string","description":"Event that sends it, e.g. `order.paid`."},"is_customized":{"type":"boolean","description":"The store changed it (false: the shipped default)."},"is_enabled":{"type":"boolean","description":"Disabled e-mails are not sent."},"label":{"type":"string"},"subject":{"type":"string"},"trigger":{"type":"string","description":"When it goes out, in words."}}},"TransactionalEmailTemplate":{"type":"object","description":"The effective template: the store's version, or the shipped default.","required":["event","subject","mode","blocks","design","is_enabled","is_customized"],"properties":{"blocks":{"type":"object","description":"Friendly-mode fields (legacy form of `design`)."},"design":{"type":"object","description":"Block document, the same format marketing templates use."},"event":{"type":"string"},"html":{"type":["string","null"],"description":"Body in `html` mode."},"is_customized":{"type":"boolean","description":"False when this is the shipped default rather than a stored version."},"is_enabled":{"type":"boolean"},"mode":{"$ref":"#/components/schemas/TransactionalEmailMode"},"preview_text":{"type":["string","null"]},"subject":{"type":"string"}}},"TransactionalEmailVariable":{"type":"object","description":"A merge variable the editor offers for an event.","required":["token","label","sample"],"properties":{"label":{"type":"string"},"sample":{"type":"string","description":"What it renders to in previews."},"token":{"type":"string","description":"What to type, e.g. `{{order.number}}`."}}},"TransferOwnershipRequest":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","format":"uuid","description":"The member who becomes the store owner."}}},"TwoFactorChallenge":{"type":"object","description":"The password was right; finish signing in with a second factor.","required":["challenge","methods","expires_in"],"properties":{"challenge":{"type":"string","description":"Pass to the verify endpoint of one of `methods`."},"expires_in":{"type":"integer","format":"int64","description":"Seconds the challenge stays valid.","example":300},"methods":{"type":"array","items":{"$ref":"#/components/schemas/TwoFactorMethod"},"description":"Second factors enabled on the account. More may be added; ignore\nunknown values."}}},"TwoFactorMethod":{"type":"string","description":"A second factor the account accepts.","enum":["totp","whatsapp"]},"UnshippedItem":{"type":"object","description":"An order line with how much of it no shipment has claimed.","required":["order_item_id","title","ordered_quantity","remaining_quantity"],"properties":{"order_item_id":{"type":"string","format":"uuid"},"ordered_quantity":{"type":"integer","format":"int32"},"remaining_quantity":{"type":"integer","format":"int32","description":"Units not in any non-cancelled shipment."},"sku":{"type":["string","null"]},"title":{"type":"string"}}},"UpdateAlertSubscription":{"type":"object","required":["enabled_events"],"properties":{"enabled_events":{"type":"array","items":{"$ref":"#/components/schemas/TeamAlertEvent"}},"is_enabled":{"type":["boolean","null"],"description":"Defaults to true."}}},"UpdateAssistantPreferencesRequest":{"type":"object","properties":{"system_prompt_extra":{"type":["string","null"],"description":"Null or absent clears it."}}},"UpdateConversationRequest":{"type":"object","description":"Fields to change; leave out what should stay.","properties":{"assignee_user_id":{"type":["string","null"],"format":"uuid","description":"A team member's user id, or null to unassign. Adds a system message.\nClients that drop null fields can send `unassign: true` instead."},"bot_active":{"type":["boolean","null"],"description":"False stops the bot (and hands the conversation over to the team)."},"contact_email":{"type":["string","null"]},"contact_name":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"customer_id":{"type":["string","null"],"format":"uuid","description":"Link a customer of this store."},"priority":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationPriority"}]},"snoozed_until":{"type":["string","null"],"format":"date-time","description":"With `status` `snoozed`: when it wakes up. Must be in the future."},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationStatus","description":"`resolved` closes it (adds a system message); `snoozed` hides it\nuntil `snoozed_until` (default: 4 hours from now); `open` reopens."}]},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"Replaces the labels. Lowercased and trimmed."},"unassign":{"type":["boolean","null"],"description":"True removes the assignee, the same as `assignee_user_id: null`.\nCannot be combined with a non-null `assignee_user_id`. False or\nabsent changes nothing."}}},"UpdateDocumentRequest":{"type":"object","properties":{"data":{"type":["object","null"],"description":"Replaces the whole `data` object."},"is_active":{"type":["boolean","null"]},"position":{"type":["integer","null"],"format":"int32"},"slug":{"type":["string","null"],"description":"`null` clears the slug; omit to leave it."}}},"UpdateEmailBrandKitRequest":{"type":"object","required":["kit"],"properties":{"kit":{"type":"object","description":"The whole kit; unknown fields are dropped, missing ones take defaults."}}},"UpdateEmailBroadcastRequest":{"type":"object","description":"Fields to change; absent ones stay. Only drafts and scheduled campaigns\ncan change. Setting `scheduled_at` schedules the campaign.","properties":{"ab_test":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EmailAbTest"}]},"audience":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EmailAudienceFilter"}]},"html_override":{"type":["string","null"]},"name":{"type":["string","null"]},"optimize_send_time":{"type":["boolean","null"]},"reply_to":{"type":["string","null"]},"scheduled_at":{"type":["string","null"],"format":"date-time"},"subject_override":{"type":["string","null"]},"template_id":{"type":["string","null"],"format":"uuid"},"text_override":{"type":["string","null"]}}},"UpdateEmailSettingsRequest":{"type":"object","description":"Fields to change; absent ones stay. An empty string clears a text field.","properties":{"from_email":{"type":["string","null"]},"from_name":{"type":["string","null"]},"inbox_mode":{"$ref":"#/components/schemas/EmailInboxMode"},"provider":{"$ref":"#/components/schemas/EmailProvider"},"reply_to":{"type":["string","null"]},"resend_api_key":{"type":["string","null"],"description":"Write-only. An empty string removes the stored key."},"topics":{"type":["array","null"],"items":{"type":"string"},"description":"Replaces the whole list; blank entries are dropped."}}},"UpdateEmailTemplateRequest":{"type":"object","description":"Fields to change; absent ones stay. A `design` recompiles `html`; an\n`html` without a `design` switches the template to raw HTML.","properties":{"design":{"type":["object","null"]},"html":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"name":{"type":["string","null"]},"preview_text":{"type":["string","null"]},"reply_to":{"type":["string","null"]},"subject":{"type":["string","null"]},"text_body":{"type":["string","null"]}}},"UpdateKbArticleRequest":{"type":"object","properties":{"body_md":{"type":["string","null"]},"collection_id":{"type":["string","null"],"format":"uuid","description":"A collection of this store, or null to take it out of its collection."},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/KbArticleStatus"}]},"title":{"type":["string","null"]}}},"UpdateMarketingConfigRequest":{"type":"object","description":"Changes to the tracking configuration. Only fields sent are written:\n`\"\"` clears a field, null or absent leaves it as is.","properties":{"google_ads_conversion_action_id":{"type":["string","null"]},"google_ads_conversion_id":{"type":["string","null"]},"google_ads_conversion_label":{"type":["string","null"]},"google_ads_customer_id":{"type":["string","null"]},"google_ads_developer_token":{"type":["string","null"],"description":"Write-only."},"google_ads_login_customer_id":{"type":["string","null"],"description":"Manager (MCC) account the API calls go through, when there is one."},"google_ads_oauth_client_id":{"type":["string","null"]},"google_ads_oauth_client_secret":{"type":["string","null"],"description":"Write-only."},"google_ads_oauth_refresh_token":{"type":["string","null"],"description":"Write-only."},"meta_ad_account_id":{"type":["string","null"]},"meta_ads_access_token":{"type":["string","null"],"description":"Write-only."},"meta_capi_access_token":{"type":["string","null"],"description":"Write-only."},"meta_catalog_access_token":{"type":["string","null"],"description":"Write-only."},"meta_catalog_id":{"type":["string","null"]},"meta_pixel_id":{"type":["string","null"]},"meta_test_event_code":{"type":["string","null"]}}},"UpdateMeRequest":{"type":"object","properties":{"full_name":{"type":["string","null"],"description":"1 to 255 characters."},"locale":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Locale","description":"Preferred language for the admin and alerts."}]},"phone":{"type":["string","null"],"description":"Profile phone (WhatsApp), reused for 2FA setup and store alerts.\nFormatting is stripped; an empty string clears it. Omit to leave it\nunchanged."}}},"UpdateNotificationChannelRequest":{"type":"object","description":"Fields to change; absent ones stay. `config_json` replaces the whole\nconfig (masked secrets are kept).","properties":{"channel_type":{"$ref":"#/components/schemas/NotificationChannelType"},"config_json":{"type":["object","null"]},"enabled_events":{"type":["array","null"],"items":{"type":"string"}},"is_enabled":{"type":["boolean","null"]},"locale":{"type":["string","null"]},"name":{"type":["string","null"]}}},"UpdateOrderStatusRequest":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/OrderStatus"}}},"UpdatePaymentProviderRequest":{"type":"object","description":"Changes to a gateway. Omitted fields are kept.","properties":{"config_json":{"type":["object","null"],"description":"Merged into the stored settings; masked secrets are ignored."},"is_active":{"type":["boolean","null"]},"is_default":{"type":["boolean","null"]},"name":{"type":["string","null"]}}},"UpdateProductImageRequest":{"type":"object","description":"Fields to change; omitted fields keep their value.","properties":{"alt_text":{"type":["string","null"]},"extra_variant_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"When present, replaces the set of extra variants this image is\nshared with. An empty array clears them."},"image_kind":{"type":["string","null"],"description":"`gallery` or `measurement`."},"is_active":{"type":["boolean","null"]},"is_primary":{"type":["boolean","null"]},"position":{"type":["integer","null"],"format":"int32"},"poster_url":{"type":["string","null"]},"product_variant_id":{"type":["string","null"],"format":"uuid"}}},"UpdatePushPreferencesRequest":{"type":"object","description":"Replace my push preferences for a store.","required":["enabled_events"],"properties":{"enabled_events":{"type":"array","items":{"$ref":"#/components/schemas/PushEvent"},"description":"Alerts that should push. Ones I cannot receive are dropped."},"is_enabled":{"type":["boolean","null"],"description":"Defaults to true."}}},"UpdateShipmentRequest":{"type":"object","description":"Changes to a shipment. Omitted (or null) fields keep their value.","properties":{"carrier_name":{"type":["string","null"]},"cost_cents":{"type":["integer","null"],"format":"int64"},"delivered":{"type":["boolean","null"],"description":"`true` stamps `delivered_at` (once)."},"freight_external_order_code":{"type":["string","null"]},"freight_payer":{"type":["string","null"],"description":"`CIF` or `FOB`."},"freight_provider_code":{"type":["string","null"]},"notes":{"type":["string","null"]},"shipped":{"type":["boolean","null"],"description":"`true` stamps `shipped_at` (once)."},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ShipmentStatus"}]},"tracking_code":{"type":["string","null"]}}},"UpdateStoreFulfillmentSettingsRequest":{"type":"object","properties":{"abandoned_cart_delay_minutes":{"type":["integer","null"],"format":"int32"},"abandoned_cart_recovery_enabled":{"type":["boolean","null"]},"cart_reservation_minutes":{"type":["integer","null"],"format":"int32"},"dispatch_days":{"type":["integer","null"],"format":"int32"},"review_request_delay_days":{"type":["integer","null"],"format":"int32"},"review_request_enabled":{"type":["boolean","null"]}}},"UpdateStoreRoleRequest":{"type":"object","properties":{"color":{"type":["string","null"]},"description":{"type":["string","null"]},"name":{"type":["string","null"]},"permission_codes":{"type":["array","null"],"items":{"type":"string"}},"position":{"type":["integer","null"],"format":"int32"}}},"UpdateStorefrontPageRequest":{"type":"object","description":"Fields to change; absent (or null) fields keep their value.","properties":{"content":{"type":["string","null"]},"published":{"type":["boolean","null"]},"slug":{"type":["string","null"]},"template":{"type":["string","null"]},"title":{"type":["string","null"]}}},"UpdateTenantRequest":{"type":"object","properties":{"contact_email":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"default_currency":{"type":["string","null"],"description":"`BRL` or `USD` (case-insensitive)."},"default_locale":{"type":["string","null"],"description":"`pt-BR` or `en-US`."},"feature_flags":{"type":["object","null"],"description":"Replaces the flags: keys `[a-z0-9_.-]`, boolean values."},"legal_name":{"type":["string","null"]},"name":{"type":["string","null"]},"tax_id":{"type":["string","null"]},"timezone":{"type":["string","null"]}}},"UpdateWebhookRequest":{"type":"object","properties":{"is_active":{"type":["boolean","null"]},"secret":{"type":["string","null"]},"url":{"type":["string","null"]}}},"UpdateWorkflowRequest":{"type":"object","description":"Fields to change; absent ones stay. `graph` and `trigger` change the\ndraft only; publish to make them fire.","properties":{"description":{"type":["string","null"]},"graph":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/WorkflowGraph"}]},"name":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/WorkflowSettableStatus"},"trigger":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/WorkflowTrigger"}]}}},"UploadedBrandAsset":{"type":"object","description":"An uploaded brand asset.","required":["url","name","kind"],"properties":{"kind":{"$ref":"#/components/schemas/BrandAssetKind"},"name":{"type":"string","description":"The uploaded file name."},"url":{"type":"string","description":"Public URL to put in the brand system."}}},"UpsertPlatformPrefsRequest":{"type":"object","description":"The whole set of my WhatsApp/e-mail alert channels for a store.","required":["channels"],"properties":{"channels":{"type":"array","items":{"$ref":"#/components/schemas/PlatformPrefInput"},"description":"At most one per channel type. Channels left out are removed."}}},"UpsertSpecValueRequest":{"type":"object","properties":{"collection_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"}},"term_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"}},"value_text":{"type":["string","null"]},"value_texts":{"type":["array","null"],"items":{"type":"string"}}}},"UpsertWorkflowSecretRequest":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","description":"Letters, digits and underscores, not starting with a digit; stored\nupper-case."},"value":{"type":"string","description":"1 to 8192 bytes. Write-only."}}},"User":{"type":"object","description":"A person with a Mobiari account.","required":["id","email","is_active","totp_enabled","whatsapp_2fa_enabled","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":"string"},"full_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"locale":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Locale","description":"Preferred language: `pt-BR` or `en-US`. Tolerate other values: older\naccounts may hold one."}]},"phone":{"type":["string","null"],"description":"Profile phone (digits only), used for WhatsApp 2FA setup and store\nalerts."},"totp_enabled":{"type":"boolean","description":"An authenticator app is required at sign-in."},"whatsapp_2fa_enabled":{"type":"boolean","description":"A WhatsApp code is accepted at sign-in."}}},"VariantBoxAssignRequest":{"type":"object","required":["box_id"],"properties":{"box_id":{"type":"string","format":"uuid","description":"A box of the same store."},"is_primary":{"type":["boolean","null"],"description":"Makes it the variant's primary box (unsetting the others). Defaults\nto false."},"quantity":{"type":["integer","null"],"format":"int32","description":"Defaults to 1."}}},"VariantBoxUpdateRequest":{"type":"object","properties":{"is_primary":{"type":["boolean","null"]},"quantity":{"type":["integer","null"],"format":"int32"}}},"VariantCreateRequest":{"type":"object","description":"A new variant of the product in the path.","required":["sku","title","price_cents"],"properties":{"barcode":{"type":["string","null"]},"compare_at_cents":{"type":["integer","null"],"format":"int64"},"cost_cents":{"type":["integer","null"],"format":"int64"},"fulfillment_mode":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/FulfillmentMode","description":"Defaults to `stocked`."}]},"is_active":{"type":["boolean","null"],"description":"Defaults to true."},"lead_time_days":{"type":["integer","null"],"format":"int32"},"price_cents":{"type":"integer","format":"int64"},"sku":{"type":"string","description":"Unique across the platform."},"title":{"type":"string"}}},"VariantLocationStock":{"type":"object","description":"Stock of a variant at one inventory location.","required":["location_id","location_name","on_hand","reserved","available"],"properties":{"available":{"type":"integer","format":"int32","description":"`on_hand - reserved`."},"location_id":{"type":"string","format":"uuid"},"location_name":{"type":"string"},"on_hand":{"type":"integer","format":"int32"},"reserved":{"type":"integer","format":"int32"}}},"VariantLookup":{"type":"object","description":"The variant a code identifies, and its product.","required":["matched_on","match_count","variant","product","matches"],"properties":{"match_count":{"type":"integer","format":"int64","description":"How many variants of the store match the code the same way. Above 1\nthe barcode is shared; `variant` is the first active one."},"matched_on":{"$ref":"#/components/schemas/LookupMatch"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/VariantLookupMatch"},"description":"Every match, best first (active variants of active products\nfirst), at most 50; the first is `variant` / `product`. For\n`product_gtin`, one entry per matching product with its preferred\nvariant."},"product":{"$ref":"#/components/schemas/ProductListItem"},"variant":{"$ref":"#/components/schemas/ProductVariantDetail"}}},"VariantLookupMatch":{"type":"object","description":"One variant a code matches, with its product.","required":["variant","product"],"properties":{"product":{"$ref":"#/components/schemas/ProductListItem"},"variant":{"$ref":"#/components/schemas/ProductVariantDetail"}}},"VariantOptionAssignRequest":{"type":"object","description":"An option value to give the variant. It must belong to one of the\nproduct's option groups.","required":["option_value_id"],"properties":{"option_value_id":{"type":"string","format":"uuid"}}},"VariantOptionValue":{"type":"object","description":"One option a variant carries, e.g. Color: Blue.","required":["option_group_id","option_group_name","option_value_id","option_value"],"properties":{"color_hex":{"type":["string","null"],"description":"`#RRGGBB`, or several joined by `/`, for custom colors."},"option_group_id":{"type":"string","format":"uuid"},"option_group_name":{"type":"string"},"option_value":{"type":"string"},"option_value_id":{"type":"string","format":"uuid"}}},"VariantReorderRequest":{"type":"object","description":"The new order of a product's variants.","required":["variant_ids"],"properties":{"variant_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Every variant id of the product, in display order. Ids of other\nproducts are ignored."}}},"VariantShippingBox":{"type":"object","description":"A box assigned to a variant.","properties":{"box_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":["string","null"],"format":"date-time"},"id":{"type":["string","null"],"format":"uuid","description":"The assignment id."},"is_primary":{"type":["boolean","null"],"description":"The box freight quotes use first."},"quantity":{"type":["integer","null"],"format":"int32","description":"Boxes one unit ships in."},"variant_id":{"type":["string","null"],"format":"uuid"}}},"VariantStock":{"type":"object","description":"A variant's stock: totals, per location, and what governs writes to it.","required":["variant_id","product_id","sku","name","product_title","on_hand","reserved","available","uses_components","incoming","stock_by_location"],"properties":{"available":{"type":"integer","format":"int32","description":"Units that can still be promised: the sum of `available` over the\nlocations, or `buildable` for a kit."},"barcode":{"type":["string","null"]},"buildable":{"type":["integer","null"],"format":"int32","description":"For a kit: whole units the components can still build. Null otherwise."},"incoming":{"type":"integer","format":"int32","description":"Units on purchase orders that are ordered and not received yet."},"limiting_sku":{"type":["string","null"],"description":"For a kit: SKU of the component that caps `buildable`."},"name":{"type":"string","description":"The variant's title, or the product's when the variant has none."},"on_hand":{"type":"integer","format":"int32","description":"Units on hand over every location."},"product_id":{"type":"string","format":"uuid"},"product_title":{"type":"string"},"reorder_point":{"type":["integer","null"],"format":"int32","description":"At or below this available quantity the variant counts as low stock."},"reorder_quantity":{"type":["integer","null"],"format":"int32","description":"Quantity a reorder draft proposes."},"reserved":{"type":"integer","format":"int32","description":"Units reserved over every location."},"sku":{"type":"string"},"stock_by_location":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"},"description":"The default location first, then every other active location of the\nstore (zero when nothing is stocked there), then inactive ones that\nstill hold stock. Empty for kits."},"stock_owner":{"type":["string","null"],"description":"The ERP module that owns this store's stock (the store's\n`inventory_mode`, e.g. `tiny`), or null when Mobiari does (`mobi`). While an ERP owns it,\nmanual writes answer 409 `inventory_managed_externally` unless sent\nwith `force: true`, because the next sync would overwrite them."},"stock_owner_name":{"type":["string","null"],"description":"Display name of `stock_owner`."},"uses_components":{"type":"boolean","description":"True for a kit whose stock is computed from its components. Its\n`stock_by_location` is empty and stock writes to it answer 409\n`logical_stock_readonly`: adjust the components instead."},"variant_id":{"type":"string","format":"uuid"}}},"VariantUpdateRequest":{"type":"object","description":"Fields to change. Omitted fields keep their value; for the nullable ones\nan explicit `null` clears them.","properties":{"barcode":{"type":["string","null"]},"clear_compare_at":{"type":["boolean","null"],"description":"True removes the compare-at price, the same as\n`compare_at_cents: null`, for clients that drop null fields. Cannot\nbe combined with a non-null `compare_at_cents`."},"compare_at_cents":{"type":["integer","null"],"format":"int64"},"cost_cents":{"type":["integer","null"],"format":"int64"},"fulfillment_mode":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/FulfillmentMode"}]},"is_active":{"type":["boolean","null"]},"lead_time_days":{"type":["integer","null"],"format":"int32"},"price_cents":{"type":["integer","null"],"format":"int64"},"sku":{"type":["string","null"]},"title":{"type":["string","null"]}}},"VariantWithOptions":{"allOf":[{"$ref":"#/components/schemas/ProductVariant"},{"type":"object","required":["options"],"properties":{"options":{"type":"array","items":{"$ref":"#/components/schemas/VariantOptionValue"}}}}],"description":"A variant and the options it carries."},"VerifyOtpRequest":{"type":"object","required":["challenge","code"],"properties":{"challenge":{"type":"string","description":"`challenge` from `POST /auth/login`."},"code":{"type":"string","description":"The 6-digit code received over WhatsApp.","example":"123456"},"device_name":{"type":["string","null"],"description":"See `LoginRequest.device_name`."}}},"VerifyTotpRequest":{"type":"object","required":["challenge","totp_code"],"properties":{"challenge":{"type":"string","description":"`challenge` from `POST /auth/login`."},"device_name":{"type":["string","null"],"description":"See `LoginRequest.device_name`."},"totp_code":{"type":"string","description":"The 6-digit code from the authenticator app.","example":"123456"}}},"VisitorDetail":{"type":"object","description":"A visitor's identity, visits, events and attributed orders.","required":["visitor_id","sessions","events","orders"],"properties":{"customer_id":{"type":["string","null"],"format":"uuid","description":"The customer, once the visitor was identified."},"email":{"type":["string","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackedEvent"},"description":"The 200 most recent events, newest first."},"first_name":{"type":["string","null"]},"first_seen":{"type":["string","null"],"format":"date-time","description":"Oldest of the events returned."},"last_name":{"type":["string","null"]},"last_seen":{"type":["string","null"],"format":"date-time","description":"Newest event."},"orders":{"type":"array","items":{"$ref":"#/components/schemas/VisitorOrder"},"description":"The 50 most recent attributed orders, newest first."},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/VisitorSession"},"description":"The 200 most recent visits, newest first."},"visitor_id":{"type":"string","format":"uuid"}}},"VisitorOrder":{"type":"object","description":"An order attributed to a visitor.","required":["order_id","status","total_cents","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"last_campaign":{"type":["string","null"]},"last_medium":{"type":["string","null"]},"last_source":{"type":["string","null"]},"order_id":{"type":"string","format":"uuid"},"order_number":{"type":["string","null"]},"status":{"type":"string","description":"Order status (`pending`, `paid`, `fulfilled`, `cancelled`...)."},"total_cents":{"type":"integer","format":"int64"}}},"VisitorSession":{"type":"object","description":"One visit (session) of a visitor.","required":["session_id","started_at","last_event_at","page_count"],"properties":{"landing_referrer":{"type":["string","null"]},"landing_url":{"type":["string","null"]},"last_event_at":{"type":"string","format":"date-time"},"page_count":{"type":"integer","format":"int32"},"session_id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"user_agent":{"type":["string","null"]},"utm_campaign":{"type":["string","null"]},"utm_medium":{"type":["string","null"]},"utm_source":{"type":["string","null"]}}},"VisitorSummary":{"type":"object","description":"A visitor active in the window, with their activity and attributed orders.","required":["visitor_id","first_seen","last_seen","sessions","pageviews","events","orders","revenue_cents"],"properties":{"customer_id":{"type":["string","null"],"format":"uuid","description":"The customer, once the visitor was identified."},"email":{"type":["string","null"]},"events":{"type":"integer","format":"int64"},"first_name":{"type":["string","null"]},"first_seen":{"type":"string","format":"date-time","description":"First event in the window."},"last_name":{"type":["string","null"]},"last_seen":{"type":"string","format":"date-time","description":"Last event in the window."},"orders":{"type":"integer","format":"int64","description":"Paid or fulfilled orders attributed to the visitor in the window."},"pageviews":{"type":"integer","format":"int64"},"revenue_cents":{"type":"integer","format":"int64"},"sessions":{"type":"integer","format":"int64"},"visitor_id":{"type":"string","format":"uuid"}}},"Webhook":{"type":"object","description":"An endpoint that receives the store's events.","required":["id","store_id","url","secret","is_active","events","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"string"},"description":"Subscribed event names (see `GET /events/catalog`)."},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"secret":{"type":"string","description":"Signing secret: deliveries carry an HMAC-SHA256 of the body made\nwith it."},"store_id":{"type":"string","format":"uuid"},"updated_at":{"type":"string","format":"date-time"},"url":{"type":"string"}}},"WebhookDelivery":{"type":"object","description":"One attempt to deliver an event to a webhook.","required":["id","webhook_id","payload_json","attempted_at","success"],"properties":{"attempted_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"payload_json":{"type":"object","description":"The body that was sent."},"response_body":{"type":["string","null"]},"response_status":{"type":["integer","null"],"format":"int32","description":"HTTP status the endpoint answered with; absent when it could not be\nreached."},"success":{"type":"boolean"},"webhook_id":{"type":"string","format":"uuid"}}},"WebhookEventRow":{"type":"object","required":["webhook_id","event"],"properties":{"event":{"type":"string","description":"Event name, e.g. `orders.paid`."},"webhook_id":{"type":"string","format":"uuid"}}},"WhatsappChannel":{"type":"object","required":["reachable","opt_in","conversations"],"properties":{"conversations":{"type":"integer","format":"int64","description":"WhatsApp conversations with this customer."},"opt_in":{"type":"boolean"},"phone":{"type":["string","null"]},"reachable":{"type":"boolean","description":"Has a usable phone number and WhatsApp consent."}}},"WhatsappChannelStatus":{"type":"object","description":"Health of a connected WhatsApp channel.","required":["ok"],"properties":{"error":{"type":["string","null"],"description":"Why it is not ok."},"number":{"type":["object","null"],"description":"The number as Meta reports it: `display_phone_number`,\n`verified_name`, `quality_rating`, `platform_type`, `status`,\n`name_status`."},"ok":{"type":"boolean","description":"The token works and Meta answered."}}},"WhatsappConnectRequest":{"type":"object","description":"What Meta's Embedded Signup dialog returned.","required":["code"],"properties":{"channel_id":{"type":["string","null"],"format":"uuid","description":"Update this channel instead of creating one."},"code":{"type":"string"},"mode":{"type":["string","null"],"description":"`coexistence` (number stays in the Business app, the default) or `cloud`."},"phone_number_id":{"type":["string","null"]},"waba_id":{"type":["string","null"]}}},"WhatsappConnectResult":{"type":"object","description":"The connected channel.","required":["channel_id","display_phone","verified_name","mode","webhook_url","warnings"],"properties":{"channel_id":{"type":"string","format":"uuid"},"display_phone":{"type":"string"},"mode":{"type":"string"},"verified_name":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"},"description":"Steps that did not complete (number registration, webhook\nsubscription), in Portuguese, for the admin to act on."},"webhook_url":{"type":"string","description":"Where Meta now delivers this number's messages."}}},"WhatsappSignupConfig":{"type":"object","description":"What the client needs to open Meta's Embedded Signup dialog.","required":["enabled"],"properties":{"app_id":{"type":["string","null"]},"config_id":{"type":["string","null"]},"enabled":{"type":"boolean","description":"Embedded Signup is set up on this server."},"graph_version":{"type":["string","null"]}}},"Workflow":{"type":"object","description":"An automation: a graph of steps started by a trigger. `graph` and\n`trigger` are the draft being edited; `published_*` is what fires.","required":["id","store_id","kind","name","status","graph","trigger","created_at","updated_at","version"],"properties":{"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"format":"uuid"},"description":{"type":["string","null"]},"graph":{"$ref":"#/components/schemas/WorkflowGraph"},"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/WorkflowKind"},"last_run_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"next_fire_at":{"type":["string","null"],"format":"date-time","description":"Next scheduled fire (schedule triggers)."},"published_at":{"type":["string","null"],"format":"date-time"},"published_graph":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/WorkflowGraph","description":"What actually fires. `graph`/`trigger` are the draft being edited."}]},"published_trigger":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/WorkflowTrigger"}]},"status":{"$ref":"#/components/schemas/WorkflowStatus"},"store_id":{"type":"string","format":"uuid"},"trigger":{"$ref":"#/components/schemas/WorkflowTrigger"},"updated_at":{"type":"string","format":"date-time"},"version":{"type":"integer","format":"int32","description":"Published version number; 0 before the first publish."}}},"WorkflowApprovalRequest":{"type":"object","required":["approve"],"properties":{"approve":{"type":"boolean","description":"True to approve, false to reject."}}},"WorkflowEdge":{"type":"object","description":"A connection from one step's port to the next step.","required":["from","to"],"properties":{"branch":{"type":["string","null"],"description":"For `flow.branch` the same `from` node has two outgoing edges:\n`branch: \"true\"` and `branch: \"false\"`. Other nodes leave it\nblank and we follow whichever single edge exists."},"from":{"type":"string"},"to":{"type":"string"}}},"WorkflowGraph":{"type":"object","description":"Concrete graph deserialised out of `workflows.graph`. We keep it\nloose: nodes carry a free-form `config` because each node type owns\nits own config schema, and we don't want to stamp a Rust struct for\nevery node variant.\nSteps and the connections between them.","properties":{"edges":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowEdge"}},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowNode"}}}},"WorkflowKind":{"type":"string","description":"Which editor a workflow belongs to.","enum":["journey","workflow"]},"WorkflowListItem":{"allOf":[{"$ref":"#/components/schemas/Workflow"},{"type":"object","required":["runs_7d","failed_7d","active_runs"],"properties":{"active_runs":{"type":"integer","format":"int64","description":"Runs pending, running, waiting or awaiting approval now."},"failed_7d":{"type":"integer","format":"int64","description":"Of those, failed."},"last_run_started_at":{"type":["string","null"],"format":"date-time"},"last_run_status":{"type":["string","null"]},"runs_7d":{"type":"integer","format":"int64","description":"Runs started in the last 7 days."}}}],"description":"A workflow with its recent health (test runs left out)."},"WorkflowNode":{"type":"object","description":"A step. Its `type` and `config` keys come from the node catalog.","required":["id","type"],"properties":{"config":{"type":"object"},"id":{"type":"string"},"position":{"$ref":"#/components/schemas/WorkflowNodePosition"},"type":{"type":"string","description":"e.g. \"trigger.manual\", \"action.send_email\", \"flow.branch\"."}}},"WorkflowNodePosition":{"type":"object","description":"Where the step sits on the editor canvas.","properties":{"x":{"type":"number","format":"double"},"y":{"type":"number","format":"double"}}},"WorkflowNodeTestOutcome":{"type":"string","description":"How a tested step would go on.","enum":["continue","wait","await_approval","stop","error"]},"WorkflowNodeTestResult":{"type":"object","description":"What a tested step did, without side effects.","required":["outcome","rendered_config","available"],"properties":{"available":{"type":"object","description":"What expressions could read at this step (secrets masked)."},"branch":{"type":["string","null"]},"context_from_run":{"type":["string","null"],"format":"uuid","description":"The run the data came from."},"error":{"type":["string","null"]},"outcome":{"$ref":"#/components/schemas/WorkflowNodeTestOutcome"},"output":{"type":["object","null"]},"rendered_config":{"type":"object","description":"The step's config with expressions filled in (secrets masked)."}}},"WorkflowProblem":{"type":"object","description":"Something wrong (or worth a look) in a workflow's draft.","required":["level","message"],"properties":{"level":{"$ref":"#/components/schemas/WorkflowProblemLevel","description":"`error` blocks publishing; `warning` does not."},"message":{"type":"string"},"node_id":{"type":["string","null"]}}},"WorkflowProblemLevel":{"type":"string","description":"How serious a problem is.","enum":["error","warning"]},"WorkflowPublishResult":{"type":"object","description":"A published workflow and the warnings its draft had.","required":["workflow","problems"],"properties":{"problems":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowProblem"},"description":"Warnings only (errors block publishing)."},"workflow":{"$ref":"#/components/schemas/Workflow"}}},"WorkflowRun":{"type":"object","description":"One execution of a workflow.","required":["id","workflow_id","store_id","status","trigger_payload","context","created_at","updated_at","attempt","dry_run"],"properties":{"attempt":{"type":"integer","format":"int32","description":"Consecutive failures of the current node (reset when a node succeeds)."},"cancelled_at":{"type":["string","null"],"format":"date-time"},"context":{"type":"object","description":"Step outputs and variables so far."},"created_at":{"type":"string","format":"date-time"},"current_node_id":{"type":["string","null"],"description":"The step it is on (or stopped at)."},"customer_id":{"type":["string","null"],"format":"uuid"},"dry_run":{"type":"boolean","description":"Test run: nodes with side effects only describe what they would do."},"error_message":{"type":["string","null"]},"finished_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"next_run_at":{"type":["string","null"],"format":"date-time","description":"When a waiting run resumes."},"retry_of":{"type":["string","null"],"format":"uuid","description":"The run this one retries."},"started_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/WorkflowRunStatus"},"store_id":{"type":"string","format":"uuid"},"trigger_payload":{"type":"object","description":"What started it: the event, webhook request or manual payload."},"updated_at":{"type":"string","format":"date-time"},"version":{"type":["integer","null"],"format":"int32","description":"Workflow version it runs (null for test runs of the draft)."},"workflow_id":{"type":"string","format":"uuid"}}},"WorkflowRunStatus":{"type":"string","description":"State of a run. Documented set; tolerate new values.","enum":["pending","running","waiting","awaiting_approval","completed","failed","cancelled"]},"WorkflowRunStep":{"type":"object","description":"One executed step of a run.","required":["id","run_id","node_id","node_type","status","started_at","attempt"],"properties":{"attempt":{"type":"integer","format":"int32"},"error_message":{"type":["string","null"]},"finished_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"node_id":{"type":"string"},"node_type":{"type":"string"},"output":{"type":["object","null"]},"run_id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"status":{"type":"string","description":"`running`, `completed`, `failed`, `waiting`, `skipped`..."}}},"WorkflowSecret":{"type":"object","description":"A stored credential. Its value is never returned.","required":["id","name","updated_at"],"properties":{"created_by_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Referenced as `{{secrets.NAME}}`."},"updated_at":{"type":"string","format":"date-time"}}},"WorkflowSettableStatus":{"type":"string","description":"Status a workflow can be set to directly (publishing activates it).","enum":["draft","paused"]},"WorkflowStatus":{"type":"string","description":"Lifecycle of a workflow. Documented set; tolerate new values.","enum":["draft","active","paused"]},"WorkflowTrigger":{"oneOf":[{"type":"object","description":"Manual: only fires when an admin clicks \"Run\".","required":["type"],"properties":{"type":{"type":"string","enum":["manual"]}}},{"type":"object","description":"Customer event from the existing customer_interactions stream\n(or any in-process event we choose to publish). Produces one run\nper matched customer when the source emits that event type.","required":["event","type"],"properties":{"event":{"type":"string"},"filter":{"type":"object"},"one_at_a_time":{"type":"boolean","description":"Skip the event while this customer already has a live run of the\nsame workflow (no duplicate journeys when two orders land close)."},"type":{"type":"string","enum":["customer_event"]}}},{"type":"object","description":"Webhook: external HTTP POST hits a public URL with a token. One\nrun per request.","required":["type"],"properties":{"token":{"type":["string","null"],"description":"Secret part of the URL `/hooks/workflows/{workflow_id}/{token}`."},"type":{"type":"string","enum":["webhook"]}}},{"type":"object","description":"Schedule: every N minutes, or daily at a time on given weekdays\n(1 = Monday … 7 = Sunday). Times are UTC for now.","required":["type"],"properties":{"at_hour":{"type":["integer","null"],"format":"int32"},"at_minute":{"type":["integer","null"],"format":"int32"},"every_minutes":{"type":["integer","null"],"format":"int32"},"type":{"type":"string","enum":["schedule"]},"weekdays":{"type":"array","items":{"type":"integer","format":"int32"}}}}],"description":"What starts a workflow."},"WorkflowValidation":{"type":"object","description":"Problems in a workflow's draft.","required":["problems","ok"],"properties":{"ok":{"type":"boolean","description":"No `error`-level problems: the draft can be published."},"problems":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowProblem"}}}},"WorkflowVersion":{"type":"object","description":"A published version of a workflow.","required":["id","version","graph","trigger","published_at"],"properties":{"graph":{"$ref":"#/components/schemas/WorkflowGraph"},"id":{"type":"string","format":"uuid"},"note":{"type":["string","null"]},"published_at":{"type":"string","format":"date-time"},"published_by_name":{"type":["string","null"]},"trigger":{"$ref":"#/components/schemas/WorkflowTrigger"},"version":{"type":"integer","format":"int32"}}}},"securitySchemes":{"bearer_auth":{"type":"http","scheme":"bearer","bearerFormat":"session token or mobi_st_ store API token","description":"`Authorization: Bearer <token>`. Either a session access token from `POST /auth/login` (refresh it with `POST /auth/refresh`) or a store API token (`mobi_st_…`). A store API token works only for the store it was issued in, and can do at most what its issuing user can there, narrowed to the scopes it was issued with."}}},"security":[{"bearer_auth":[]}],"tags":[{"name":"Auth","description":"Sign-in, sessions, refresh tokens and two-factor authentication"},{"name":"Me","description":"The signed-in user: profile, access, devices and preferences"},{"name":"Tenants","description":"Organizations that own stores"},{"name":"Billing","description":"The organization's Mobiari subscription: plans and prices, the trial, plan changes, cancellation, invoices (paid by Pix) and usage against the plan's limits. Every plan includes every module; plans differ in size"},{"name":"Stores","description":"Stores and their settings"},{"name":"Team","description":"Store members, invites, roles and permissions"},{"name":"API Tokens","description":"Store API tokens for scripts and integrations: each works for one store"},{"name":"Webhooks","description":"Outbound event subscriptions and deliveries"},{"name":"Events","description":"Domain events: the store's outbox and the catalog of event names"},{"name":"Audit","description":"Who changed what, and when"},{"name":"Search","description":"One search across a store's orders, customers, products, campaigns and conversations"},{"name":"Places","description":"Address autocomplete and lookup (Brazil)"},{"name":"Products","description":"Products, variants, options, media, and the SKU/barcode lookup. Stock per location comes with the product and the variant; stock movements are under Inventory"},{"name":"Categories","description":"Product categories and the Google/Meta marketplace taxonomies"},{"name":"Collections","description":"Curated product collections"},{"name":"Product Feeds","description":"Google Merchant Center, Meta catalog and marketplace feeds, with per-product overrides"},{"name":"Files","description":"The organization's file library: folders, uploads, stars and search"},{"name":"Inventory","description":"Stock per variant and location, adjustments, transfers, the movement ledger, reservations, counts and locations. Stock writes refuse kits (`logical_stock_readonly`: adjust the components) and, while an ERP owns the store's stock (`inventory_mode`), answer 409 `inventory_managed_externally` unless sent with `force: true`. Send an `Idempotency-Key` on every stock write"},{"name":"Purchasing","description":"Suppliers, purchase orders and receiving. An order goes draft, ordered, partial, received (or cancelled); receiving writes the stock"},{"name":"Manufacturing","description":"Components, kits and their bills of materials, and build jobs"},{"name":"Shipping Boxes","description":"Box sizes the store packs orders in, and which boxes each variant ships in, for freight quotes"},{"name":"Integrations","description":"ERP connections (Tiny): OAuth, health, the link report, manual syncs and imports, and their logs. The scheduled sync runs on its own"},{"name":"Orders","description":"Orders, status changes and manual sales"},{"name":"Carts","description":"Open and abandoned carts"},{"name":"Quotes","description":"Quotes built at the counter and shared with the customer as a payment link"},{"name":"Shipments","description":"Fulfillment, freight quotes, labels and tracking"},{"name":"Payments","description":"Payments, providers and refunds"},{"name":"Freight","description":"Carrier integrations and the store's own delivery zones"},{"name":"Locations","description":"Physical stores, pickup points and the store locator"},{"name":"Discounts","description":"Discount codes and automatic promotions"},{"name":"Sales Channels","description":"Where orders come from"},{"name":"Reviews","description":"Product reviews and moderation"},{"name":"Customers","description":"Customers, addresses, identities, consent and data rights"},{"name":"Conversations","description":"The shared inbox: WhatsApp, e-mail and storefront chat. Conversations, messages, attachments, notes, assignment and the assisted-sale cart. Live updates come over the agent WebSocket (see the realtime guide)"},{"name":"Conversation Settings","description":"Inbox channels (site chat, WhatsApp, e-mail), WhatsApp signup, the chat bot and canned replies"},{"name":"Knowledge Base","description":"Articles the chat bot answers from"},{"name":"Email","description":"E-mail marketing: templates and the block editor, campaigns (broadcasts) with reports and A/B tests, segments, subscription forms, contact import and product \"let me know\" subscriptions"},{"name":"Transactional Email","description":"The e-mails the store sends on its own (order confirmation, shipping, password reset...) and the sending settings: sender identity, provider, reply routing"},{"name":"Email Deliverability","description":"Sending domains (SES identities and their DNS records), the suppression list and deliverability health"},{"name":"Ads","description":"Segments mirrored to Meta Custom Audiences, and ad spend next to the revenue attributed to Meta"},{"name":"Workflows","description":"Automations and customer journeys: a graph of steps started by a trigger (manual, customer event, webhook or schedule). Edit the draft, publish to make it fire; runs, approvals, step tests and the secrets steps use"},{"name":"Help","description":"Answers from the Mobiari documentation: a public, rate-limited question endpoint the docs site and the admin's help panel use"},{"name":"Assistant","description":"The AI assistant: a chat that reads the store and proposes writes (applied only after approval, recorded as undoable actions), streamed as server-sent events; also over WhatsApp from linked numbers"},{"name":"Notifications","description":"The store's notification log and each member's inbox over it, customer-facing notification channels, members' own WhatsApp/e-mail alert channels and the team's sale-alert roster"},{"name":"Push Notifications","description":"Push to the Mobiari mobile apps: registering a device (`/me/devices`), per-store push preferences and test pushes. Payloads and deep links are described in the push notifications guide"},{"name":"Brand","description":"Brand system: logo, palette, typography and assets"},{"name":"Storefront","description":"Storefront pages, themes, domains and deployments"},{"name":"Content","description":"CMS collections and documents that storefront themes render"},{"name":"Analytics","description":"The store dashboard; storefront traffic from the built-in tracker (visitors, sessions, pages, referrers, events) and revenue attribution by source; and the ad-platform tracking setup: Meta pixel and Conversions API, Google Ads conversions, the per-order conversion delivery log and the Meta catalog sync"}]}