This page describes the REST interfaces the DomiDo platform exposes to the application clients. Together with the OpenAPI specification kept in the project repository, it is the single source of truth for what endpoints exist, what they accept, what they return, and what enums they use. The interfaces serve the current Web/PWA beta surface and remain suitable for later iOS and Android surfaces through the React Native and Expo architecture, so the contract is shaped to outlive the immediate web rollout. The mock design files do not prove backend storage, deployment, stream transport, or hidden infrastructure choices, so this page defines resource contracts, configuration resources, and UI behaviour only — the implementation choices that satisfy them belong in an architecture decision after the requirements are approved.
API resources speak product-domain language. The vocabulary is listings, design drafts, projection faces, model tryouts, model feedback, block kits, BOM, Promo Studio projects and assets, interest reservations, Phase A.5 Stripe checkout and pre-orders, Phase B orders, returns, designer and listing-owner sales and readiness, payout account, payout transfers, reserves, disputes, statements, Docusaurus-published help articles, admin help content, and cookie preferences — never queues, tables, or infrastructure names. API responses are UI-ready snapshots: a successful mutation returns the updated resource or parent aggregate used by the screen, so the frontend does not have to infer derived state from unrelated calls. Validation errors include field path, machine-readable code, and a display message suitable for inline rendering.
Long-running projection, model generation, model voxelisation and block-kit generation, Promo Studio photo and video generation, AI text assistance, text translation, publication, embedding refresh, notification dispatch, and future fulfilment-sync work return 202 Accepted with a Job resource. The public Job includes progress, current step, step list, public status, resource reference, result reference, generated artifact references, cost and config metadata, retry and cancel eligibility, safe error fields, timestamps, and pollAfterMs. Job progress is polling-first in Phase A through GET /jobs/{jobId}; server-sent events or WebSocket streaming are not required unless a later requirement explicitly adds them.
Configuration is a first-class surface. Configuration fields are available for supported jurisdictions, Phase A interest-reservation policy, Phase A.5 Stripe-supported card copy, VAT behaviour, delivery options, AI generation costs, create style presets, Promo Studio options and costs, payout fees, thresholds and schedules, reserve and dispute rules, delivery phase gates, the product-event dictionary, observability consent classes, and Phase A disabled-remix messaging. Configuration fields also include supported content languages, default language, fallback order, translation availability, and glossary or config versions for asynchronous user-generated content translation. The API does not expose physical storage, queue, deployment, unsupported payment provider, or raw card implementation details.
User-visible mutations use named schemas. Interest reservation, saved cart, checkout, pre-order, order action, designer engagement, and Help discussion mutations use named request and response schemas; generic or opaque object payloads are not acceptable for these paths. Docusaurus-rendered public article pages may be served as static routes or static assets outside the REST path catalogue, but REST APIs remain authoritative for runtime Help discussion, support conversation creation, admin content workflow, moderation, publication state, and audit. Interfaces also expose delivery phase state where a visible surface is not yet operationally active — a visible control may be returned as disabled, read-only, waitlisted, or preview-only, but the API does not imply pre-order, payment capture, fulfilment, shipment, payout release, or remix monetisation before the relevant delivery phase is active.
Translation is built into the contract. Interfaces that accept translatable user-generated text accept an optional source language and return the updated source resource immediately; translation completion is represented by textTranslation jobs and by translation status metadata on owner, admin, support, and editor responses. Interfaces that return translatable content resolve display values using explicit language parameters where defined, the authenticated preferred content language, the Accept-Language header, the configured fallback order, and finally the source text — and owner, admin, support, and editor responses may also expose unresolved localised field metadata. API errors use a shared envelope with a stable error code, display-safe message, request id, field path where applicable, retryability, optional retry delay, and phase-gate metadata where applicable.
Several cross-cutting headers and conventions complete the contract. Externally retried mutating operations accept the Idempotency-Key header; body-level idempotencyKey may remain for transitional clients, but if both are supplied they must match. Web and PWA unsafe cookie-authenticated requests support an X-CSRF-Token header or equivalent same-site origin control. Public read endpoints are explicitly unauthenticated in OpenAPI; private endpoints inherit authentication and resource authorisation. API requests enforce bounded query length, page and page-size, non-upload request-body size, text and prompt lengths, upload sizes, job-start parameters, and provider-facing cost and concurrency limits before allocating expensive work. Operational endpoints /health, /livez, and /readyz exist in OpenAPI and are unauthenticated but public-safe — /livez checks only process liveness, /readyz fails when core dependencies prevent safe request handling, and /health returns sanitised dependency status for MongoDB, object storage, workers, Stripe configuration, translation provider configuration, search-index readiness, and build and environment metadata. Dependency outage responses use typed service-unavailable or degraded-state errors with request id, retryability, retry guidance where useful, and safe dependency class; responses never expose raw provider payloads, secrets, private URLs, internal hostnames, connection strings, or queue names.
The complete REST path catalogue is enumerated in the OpenAPI specification. The tables below summarise the surface area by group.
| Path | Methods | Purpose |
|---|---|---|
/health |
GET | Public-safe operational health summary with sanitised dependency status, build version, environment, and readiness state. |
/livez |
GET | Process liveness probe that does not fail because of temporarily unavailable dependencies. |
/readyz |
GET | Readiness probe that returns service-unavailable when core dependencies or configured maintenance prevent safe traffic. |
/app-shell |
GET | Header, navigation, authentication and account, locale, cart, feature, and shell state. |
/footer |
GET | Footer locale and currency, social, legal, VAT display, newsletter, and cookie configuration. |
| Path | Methods | Purpose |
|---|---|---|
/config/jurisdictions |
GET | Supported jurisdictions, coming-soon messages, VAT behaviour, delivery availability, and Stripe supported-card copy. |
/config/generation-costs |
GET | Configured costs for projection, model, block-kit, and Promo Studio AI generation. |
/config/create-style-presets |
GET | Configured Describe-stage style presets, prompt descriptors, thumbnails, swatches, and ordering. |
/config/promo-studio |
GET | Configured Promo Studio environments, styles, lenses, durations, aspects, batch labels, cost copy, and custom environment upload availability. |
/config/payouts |
GET | Configured payout thresholds, fees, labels, and eligibility delay values. |
/config/feature-phases |
GET | Delivery phase gates for Phase A, Phase A.5, Phase B, Phase C, native-deferred, and blocked/read-only capabilities. |
/config/translations |
GET | Supported content languages, default language, fallback order, translation provider availability, glossary version, and asynchronous translation policy. |
/config/product-events |
GET | Supported product-event dictionary, event schema versions, consent classes, retention classes, and sampling guidance. |
| Path | Methods | Purpose |
|---|---|---|
/search |
GET | Header and search modal query across configured discovery scopes with result type metadata and scope counts. |
/newsletter-signups |
POST | Newsletter signup from shared and footer surfaces. |
/analytics/events |
POST | Ingest batched app product events with typed taxonomy, consent class, session, device and surface context, and safe rejection details. |
| Path | Methods | Purpose |
|---|---|---|
/auth/oauth |
POST | OAuth start and complete for Google, Apple, and Facebook only. |
/auth/sign-out |
POST | End the current session. |
/me |
GET | Current user profile, role, preferences, cart, draft, order, admin, and dashboard pointers. |
/me/preferences |
PATCH | Locale, currency, notification, privacy, and preference updates. |
/me/dashboard |
GET | Role-aware dashboard aggregate for buyer, designer, or admin entry state. |
/me/interest-reservations |
GET | User or session interest reservations with listing summaries, cancellation state, and Phase A.5 invitation state. |
/me/trust-restrictions |
GET | Affected-user view of active restriction or blacklist state and challenge routes. |
| Path | Methods | Purpose |
|---|---|---|
/gallery/listings |
GET | Home and gallery listing-card browsing. |
/listings/{listingId} |
GET | Listing detail, product-detail variants, kit summary, owner attribution, disabled-remix state, report state, interest CTA state, and phase-gated commerce panel. |
/listings/{listingId}/related |
GET | Related and similar listings for detail rails. |
/listings/{listingId}/save |
POST, DELETE | Save or unsave a listing. |
/listings/{listingId}/share |
POST | Share metadata for a listing. |
/listings/{listingId}/interest |
POST | Create or refresh a non-binding Phase A interest reservation with explicit no-card and no-charge acknowledgement. |
/interest-reservations/{reservationId} |
GET, DELETE | Reservation detail or cancellation for the owning user or authorised admin. |
/listings/{listingId}/questions |
GET, POST | Listing questions visible on detail surfaces. |
/listings/{listingId}/reviews |
GET, POST | Listing reviews visible on detail surfaces. |
/designers |
GET | Public designer discovery list. |
/designers/{designerId} |
GET | Public designer profile, portfolio, listings, and follow state. |
/designers/{designerId}/follow |
POST, DELETE | Follow or unfollow a designer. |
| Path | Methods | Purpose |
|---|---|---|
/media/uploads |
POST | Validate and register raster, reference, profile, listing, Promo Studio environment, or supported model and source media by upload kind. |
/media/{mediaId}/crop |
PATCH | Save crop, rotation, and zoom state. |
| Path | Methods | Purpose |
|---|---|---|
/design-drafts/current |
GET | Load the saved draft or generation state that should resume when the wizard opens. |
/design-drafts |
POST | Create a draft at the Describe stage. |
/design-drafts/{draftId} |
GET, PATCH | Resume or update draft metadata and active stage. |
/design-drafts/{draftId}/reference-media |
POST | Attach reference media to a draft. |
/design-drafts/{draftId}/projection-faces/{face} |
PUT | Set face asset, source, active state, optionality, or zoom. |
/design-drafts/{draftId}/projection-faces/{face}/generate |
POST | Start generation for one projection face with configured cost. |
/design-drafts/{draftId}/projection-faces/autofill |
POST | Optionally generate missing non-front projection faces. |
/design-drafts/{draftId}/projection-faces/{face}/history/{historyId}/restore |
POST | Restore a projection face from history. |
/design-drafts/{draftId}/model-jobs |
POST | Start configured model generation and create a tryout. |
/design-drafts/{draftId}/model-tryouts/{tryoutId}/select |
POST | Select a generated model tryout. |
/design-drafts/{draftId}/model-tryouts/{tryoutId}/feedback |
POST | Submit user feedback on generated model quality. |
/design-drafts/{draftId}/block-kit-jobs |
POST | Start block-kit generation with configured cost. |
/design-drafts/{draftId}/block-kit/bom |
GET | BOM groups, search and filter data, SKU count, part count, cost, and availability. |
/design-drafts/{draftId}/block-kit/assembly |
GET | Assembly steps and payloads. |
/design-drafts/{draftId}/publish-settings |
PATCH | Visibility, ownership and licence acknowledgement, intended-use and safety gate, disabled-remix state, and future-phase royalty and price controls where active. |
/design-drafts/{draftId}/save |
POST | Save draft without publishing. |
/design-drafts/{draftId}/publish |
POST | Publish a valid draft as a listing. |
| Path | Methods | Purpose |
|---|---|---|
/jobs/{jobId} |
GET | Poll projection, model, block-kit, Promo Studio, text assist, translation, publication, embedding, notification, and fulfilment job progress. |
/jobs/{jobId}/cancel |
POST | Request cancellation for a cancellable owner-visible job. |
/jobs/{jobId}/retry |
POST | Retry a failed or dead-lettered job where the actor is authorised and the job type is retryable. |
/tag-suggestions |
GET | Tag suggestions for create and publish surfaces. |
/assist/text-jobs |
POST | Start an AI text assistance job for allowed create, designer, review, message, or help and support context. |
| Path | Methods | Purpose |
|---|---|---|
/cart |
GET | Phase A.5 and Phase B cart drawer and checkout-bag state; Phase A may return phase-blocked or interest-reservation guidance. |
/cart/items |
POST | Add listing kit to cart only in Phase A.5 and Phase B where eligible. |
/cart/items/{itemId} |
PATCH, DELETE | Update or remove cart item. |
/cart/items/{itemId}/save-for-later |
POST | Move cart item to saved-for-later where supported. |
/saved-carts |
GET | List saved carts and checkout drafts with resume and discard state. |
/saved-carts/{savedCartId}/resume |
POST | Revalidate and resume a saved cart into checkout. |
/saved-carts/{savedCartId} |
DELETE | Discard a saved cart or checkout draft. |
| Path | Methods | Purpose |
|---|---|---|
/checkout |
GET | Checkout state across Bag, Delivery, Payment, Review, and Confirmation. |
/checkout/delivery |
PATCH | Address, jurisdiction, delivery method, and collection-point selection. |
/checkout/payment |
PATCH | Select saved Stripe payment reference or Stripe checkout state. |
/checkout/setup-intent |
POST | Create or refresh the Phase A.5 Stripe SetupIntent for invited reservation conversion to a no-capture physical-kit pre-order. |
/checkout/stripe-session |
POST | Create or refresh the Phase B Stripe checkout or payment session to capture payment when fulfilment is active. |
/checkout/promo-code |
PATCH | Apply or remove promo code state. |
/checkout/review |
POST | Validate checkout review totals, jurisdictional VAT, and Stripe payment readiness. |
/checkout/confirm |
POST | Confirm the active checkout as a Phase A.5 no-capture pre-order or a Phase B charged order. |
/stripe/webhook |
POST | Provider-facing Stripe webhook receiver using raw-body signature verification, duplicate event protection, safe persistence, and domain-event mapping. |
| Path | Methods | Purpose |
|---|---|---|
/pre-orders |
GET | Buyer Phase A.5 no-capture pre-order commitments with SetupIntent verification state, source reservation, cancellation availability, attribution, and Phase B conversion readiness. |
/pre-orders/{preOrderId} |
GET | Phase A.5 pre-order detail without receipt, invoice, shipment, capture, payout, or promised ship date. |
/pre-orders/{preOrderId}/cancel |
POST | Cancel a Phase A.5 no-capture pre-order commitment where cancellation remains available. |
/orders |
GET | Buyer Phase B order list for captured and fulfilment-active orders. |
/orders/{orderId} |
GET | Order detail, timeline, payment, delivery, fulfilment readiness, and action availability. |
/orders/{orderId}/tracking |
GET | Typed shipment, parcel, tracking stop, ETA delta, and delivery tracking detail. |
/orders/{orderId}/cancel |
POST | Cancel where order state permits. |
/orders/{orderId}/payment-retry |
POST | Retry failed payment through Stripe. |
/orders/{orderId}/delivery-address |
PATCH | Request or apply delivery address change. |
/orders/{orderId}/delivery-preferences |
PATCH | Update delivery preference state. |
/orders/{orderId}/returns |
POST | Start return request. |
/orders/{orderId}/return-assessments |
GET, POST | View or create return-fee or deduction assessment for damage, wear, change of mind, or diminished value. |
/orders/{orderId}/replacements |
POST | Start replacement request. |
/orders/{orderId}/reports |
POST | Start an order issue report and linked support workflow. |
/orders/{orderId}/disputes |
POST | Start dispute request, including return-fee or restriction challenges. |
/orders/{orderId}/receipt |
GET | Receipt data with charge, jurisdictional VAT, refund, return fees, and masked Stripe payment reference. |
/orders/{orderId}/invoice |
GET | Invoice data for the order. |
/orders/{orderId}/build-companion |
GET, PATCH | Build companion steps, progress, timers, stuck-help state, and offline-ready payload. |
/orders/{orderId}/build-companion/photos |
POST | Finished-build photos for buyer profile and designer feedback loop when permitted. |
| Path | Methods | Purpose |
|---|---|---|
/designer/profile |
GET, PATCH | Owner designer profile, public profile fields, editable copy, and translation status. |
/designer/dashboard |
GET | Attributed Phase A interest, Phase A.5 pre-orders, projected entitlements, captured sales, messages, actions, payout readiness, disabled-remix state, and listing metrics. |
/designer/listings |
GET | Designer listing management list. |
/designer/listings/{listingId}/editor |
GET | Load owner listing editor aggregate with edit state, moderation, similarity, analytics, and action context. |
/designer/listings/{listingId} |
PATCH | Update designer-owned listing metadata and status. |
/designer/listings/{listingId}/duplicate |
POST | Duplicate an owned listing into a private draft or editor aggregate. |
/designer/listings/{listingId}/artifact-pack/download |
POST | Create an authorised short-lived download for owned listing artifacts. |
/designer/listings/{listingId}/royalty |
PATCH | Update royalty 0–25 and derived listed price only where future monetisation phase is active. |
/designer/listings/{listingId}/ad-boost |
PATCH | Update ad-boost configuration. |
/designer/listings/{listingId}/moderation-jobs |
POST | Start a configured listing moderation rerun where eligible. |
/designer/listings/{listingId}/similarity |
GET | List similarity and uniqueness matches and gating state. |
/designer/listings/{listingId}/analytics |
GET | Load listing performance metrics. |
/designer/listings/{listingId}/copy-change-requests |
POST | Request a change to platform-owned listing copy. |
/designer/listings/{listingId}/promo-studio |
GET | Load listing-scoped Promo Studio project, scene, generated assets, credit summary, and config version. |
/designer/listings/{listingId}/promo-studio/scene |
PATCH | Persist Promo Studio scene state. |
/designer/listings/{listingId}/promo-studio/photo-jobs |
POST | Start a Promo Studio photo-generation job. |
/designer/listings/{listingId}/promo-studio/video-jobs |
POST | Start a Promo Studio video-generation job. |
/designer/listings/{listingId}/promo-studio/assets |
GET | List generated Promo Studio photo and video assets with filters and listing-gallery publication state. |
/designer/listings/{listingId}/promo-studio/assets/download |
POST | Create an authorised download action or reference for selected or filtered Promo Studio assets. |
/designer/listings/{listingId}/promo-studio/assets/{assetId} |
PATCH, DELETE | Update keep, star, or archive metadata or remove a private Promo Studio asset. |
/designer/listings/{listingId}/promo-studio/assets/{assetId}/download |
POST | Authorised download for a single asset. |
/designer/listings/{listingId}/promo-studio/assets/{assetId}/listing-gallery |
POST, DELETE | Add or remove a Promo Studio asset from listing gallery media. |
/designer/sales |
GET | Designer attributed interest, attributed pre-order, sale, and royalty list with lifecycle, dispute, and payout references. |
/designer/sales/{saleId} |
GET | Sale detail. |
/designer/sales/{saleId}/dispute |
GET | Designer-facing sale dispute detail and reserve/royalty impact. |
/designer/action-queue |
GET | Message, payout, disabled-remix, status, and listing actions. |
/designer/messages/{messageId}/reply |
POST | Reply to a designer message or action item. |
/designer/listings/{listingId}/questions/{questionId}/reply |
POST | Draft, post, or update a designer answer to a listing question. |
/designer/listings/{listingId}/questions/{questionId}/faq-candidate |
POST | Create an FAQ candidate without mutating Help content. |
/designer/reviews/{reviewId}/reply |
POST, PATCH, DELETE | Manage owned-listing review reply. |
/designer/message-threads/{threadId}/nodes/{nodeId}/reply |
POST | Reply in a designer message thread. |
/designer/message-threads/{threadId}/nodes/{nodeId}/report |
POST | Report a message-thread node for moderation. |
/designer/claims/{claimId}/actions |
POST | Submit a typed designer claim action such as approve replacement, refund instead, request photos, or escalate. |
/designer/payout-account |
GET, PATCH | Phase A.5 Stripe Connect, KYC, tax, configurable payout options, payout readiness, and local payout settings. |
/designer/payout-account/connect |
POST | Start or refresh Phase A.5 Stripe Connect onboarding. |
/designer/payout-account/schedule |
PATCH | Update configurable payout schedule, pause and resume, minimum payout preference, and payout notifications. |
/designer/payouts |
GET | Designer payout transfer ledger or Phase A.5 payout-readiness preview. |
/designer/payouts/request |
POST | Request payout only where Phase B captured funds, delivery eligibility, and configured payout rules permit release. |
/designer/payouts/{payoutId} |
GET | Payout transfer detail. |
/designer/payouts/{payoutId}/retry |
POST | Start authorised failed-payout remediation. |
/designer/payout-reserves |
GET | Reserve hold and release ledger. |
/designer/payout-events |
GET | Payout, failed-payout, reserve, dispute, and statement activity feed. |
/designer/statements |
GET | Statement archive. |
/designer/statements/{statementId}/export |
GET | Export statement. |
/designer/tax-statements/{taxYear}/export |
GET | Export configured tax statement period and format with redacted tax identifiers. |
| Path | Methods | Purpose |
|---|---|---|
/account/profile |
PATCH | Update own profile fields. |
/account/profile/avatar |
POST, DELETE | Upload or remove own avatar. |
/account/addresses |
GET, POST | List or create saved addresses. |
/account/addresses/{addressId} |
PATCH, DELETE | Update or delete saved address. |
/account/payment-references |
GET | List saved masked Stripe payment references. |
/account/payment-references/setup-intent |
POST | Create an account-level Stripe SetupIntent. |
/account/payment-references/{paymentReferenceId} |
DELETE | Delete a saved masked Stripe payment reference. |
/account/notification-items |
GET | List concrete notification items. |
/account/notification-items/{notificationId}/read |
POST | Mark one notification as read. |
/account/notification-items/read-all |
POST | Mark visible notifications as read. |
/account/privacy |
GET, PATCH | Privacy and account data settings. |
/account/data-export-requests |
GET, POST | View or request account data export status. |
/account/lifecycle-requests |
POST | Request account or shop pause or account deletion. |
/account/security |
GET, PATCH | Security settings visible in account surfaces. |
/account/security/password |
POST | Change password or start password-change flow. |
/account/security/2fa |
PATCH | Update two-factor state. |
/account/security/sessions/{sessionId} |
DELETE | Revoke an account session. |
/account/notifications |
GET, PATCH | Notification categories and channel states. |
| Path | Methods | Purpose |
|---|---|---|
/help/articles |
GET | Published Docusaurus help and workshop article index and runtime metadata. |
/help/topics |
GET | Published topic groups, article kinds, featured slots, popular slots, and navigation metadata. |
/help/articles/{slug} |
GET | Published article metadata and runtime attachment snapshot. |
/help/articles/{slug}/feedback |
POST | Submit lightweight helpful or not-helpful article feedback. |
/help/articles/{slug}/bookmark |
POST, DELETE | Bookmark or unbookmark an article. |
/help/articles/{slug}/comments |
GET, POST | List or create user-generated article discussion comments. |
/help/articles/{slug}/comments/{commentId}/replies |
POST | Reply to a comment. |
/help/articles/{slug}/comments/{commentId}/like |
POST, DELETE | Like or unlike a comment. |
/help/articles/{slug}/comments/{commentId}/report |
POST | Report a comment. |
/beta/feedback |
POST | Submit structured beta feedback with screen context, related resource references, optional attachments, source language, and routing metadata. |
/support/conversations |
GET, POST | List own support conversations or start a support conversation. |
/support/conversations/{conversationId} |
GET, PATCH | Load an own support conversation or update user-allowed state such as close or reopen. |
/support/conversations/{conversationId}/messages |
POST | Add a user-visible message to a support conversation. |
| Path | Methods | Purpose |
|---|---|---|
/admin/beta |
GET | Founder and admin beta dashboard. |
/admin/beta/export |
GET | Export beta dashboard aggregates and feedback summaries. |
/admin/interest-reservations |
GET | Founder and admin demand review with filters. |
/interest-reservations/{reservationId}/invite-preorder |
POST | Phase A.5 admin action to invite a selected eligible reservation to no-capture pre-order conversion after gates pass. |
/admin/support/conversations |
GET | Admin support queue with filters. |
/admin/support/conversations/{conversationId} |
GET, PATCH | Admin read or update support conversation status, priority, assignment, escalation, and internal routing state. |
/admin/support/conversations/{conversationId}/messages |
POST | Admin or staff reply or internal note. |
/admin/reliability/incidents |
GET | Admin reliability incident list. |
/admin/alert-rules |
GET | Admin alert rule list. |
/admin/help/articles |
GET, POST | Admin-only list or create help and workshop content. |
/admin/help/articles/{slug} |
GET, PATCH, DELETE | Admin-only read, update, archive, or delete help and workshop content. |
/admin/help/articles/{slug}/publish |
POST | Admin-only publish or unpublish action and Docusaurus public projection control. |
/admin/help/topics |
GET, POST, PATCH | Admin-only manage help and workshop topic metadata and order. |
/admin/help/publication-artifacts |
GET, POST | Admin-only list or trigger Docusaurus publication artifacts for approved content. |
/legal/cookie-preferences |
GET, PATCH | Cookie preference state from Manage cookies. |
The following enums are closed sets and are enforced on both client and server. The OAuth provider enum is google, apple, facebook. Create draft stages are describe, projections, model, blockKit, savePublish. Projection faces are front, back, right, left, top, bottom, with front required and the others optional. Model and source upload formats are glb, gltf, obj, stl, and the model output format labels are GLB and GLTF. Publish visibility is private, unlisted, or public. Checkout steps are bag, delivery, payment, review, confirmation. The payment provider enum value is Stripe. Fulfilment readiness includes readyToShip, waitingForBlocks, waitingForProductionReadiness. Return assessment reasons include damagedBlocks, wearSigns, changeOfMind, diminishedValue. The remix feature state in Phase A is disabled with a user-facing reason.
Promo Studio enums cover job kind (promoPhoto, promoVideo), asset type (photo, video), and library filter (all, photo, video, starred). Designer sale or demand status includes attributedInterest, invitedToPreorder, attributedPreOrder, reserved, sold, disputed, refunded. Payout transfer status includes paid, inTransit, failed, with additional configured statuses allowed when documented. Reserve ledger kinds are hold and release. The media upload kind enum distinguishes model and source uploads from raster, reference, profile, listing, and Promo Studio environment uploads so model and source formats remain limited to GLB, GLTF, OBJ, and STL. Search scope is backend-configured — the API may return scopes such as listings, designers, help, or journal only when enabled by configuration.
Phase-aware enums cover delivery phase status (phaseAActive, phaseAConditional, phaseA5Active, phaseBActive, phaseCExpansion, nativeDeferred, blockedReadOnly), checkout commitment type (phaseAInterestReservation, phaseA5PreOrder, phaseBOrder), Phase A interest reservation status (active, cancelledByUser, cancelledByDomiDo, blocked, invitedToPreorder, convertedToPreOrder, expired), Phase A.5 pre-order status (draft, cardVerified, committed, cancelled, expired, convertedToOrder, conversionBlocked), and Stripe card verification status (notStarted, setupIntentCreated, requiresAction, verified, failed, expired). Translation job status is pending, queued, running, complete, failed, stale, skipped, and translation source type distinguishes userGenerated, adminAuthored, systemConfig, providerGenerated — the mandatory LLM translation pipeline applies to userGenerated free text. Public job status is queued, running, retrying, complete, failed, cancelled, deadLettered; internal worker states such as leased are not exposed as public status. Job types include projectionFace, projectionAutofill, modelGeneration, blockKitGeneration, promoPhoto, promoVideo, textAssist, textTranslation, docusaurusPublication, embeddingRefresh, notificationDispatch, fulfilmentSync.
Invalid enum values return a field-level validation error. Upload rejection identifies format-not-permitted, size-limit breach, or failed processing, and generation failure leaves the draft recoverable while preserving previous successful face, model, or block-kit data. Checkout validation identifies missing invitation, missing buyer fresh consent, missing address, unsupported jurisdiction, unavailable delivery option, missing Stripe SetupIntent or PaymentIntent state for the active phase, invalid promo code, stale cart, attempted Phase A payment, or attempted Phase B capture while Phase B is not active. Designer and listing-owner validation identifies royalty outside the 0–25 range where active, invalid ad-boost values where active, unauthorised Promo Studio access, missing Promo Studio source photo for video generation, missing Phase A.5 payout readiness, missing tax fields where required, payout release attempted before Phase B eligibility, failed payout retry not available, and Phase A disabled-remix attempts. Return fee, trust restriction, and blacklist disputes preserve the challenged decision and return a support or dispute status, and interest reservation, saved cart, checkout, pre-order, order action, designer engagement, and Help discussion validation failures return field paths that match the typed request schema for the submitted operation.
Translation failures do not fail the original source-text mutation; translation job errors expose safe retry and fallback state without returning raw LLM prompts, provider secrets, or private context not authorised for the viewer. Job failures return safe error codes, retryability, and a user-facing message without raw provider payloads, private storage paths, worker hostnames, queue names, or LLM prompts. Failed generation jobs preserve prior successful draft, model, block-kit, or promo state. Job retry and cancellation requests return field-level or operation-level validation when the job is not owned by the actor, already complete, not cancellable, not retryable, blocked by stale source state, or blocked by a phase gate.
The HTTP error envelope is consistent. Unauthorised requests return 401. Authenticated but disallowed resource, role, or phase access returns 403 or a phase-blocked error when the operation is intentionally visible but inactive. Idempotency replay with the same key and request hash returns the stored response or current resource snapshot; replay with the same key and a different request hash returns a 409 idempotency conflict. Rate-limited or quota-limited requests return 429 with retry guidance and do not enqueue jobs, call providers, or mutate domain state. Requests whose JSON body, upload registration, search query, page size, prompt, comment, support message, or job parameter exceeds configured limits return 413 or 422 before expensive processing. Web/PWA unsafe requests with missing or invalid CSRF state are rejected without mutation; provider webhook CSRF is not used because provider webhooks rely on provider signature verification.
Stripe webhook failures distinguish missing signature, invalid signature, stale or replayed signature, malformed body, unknown event, duplicate event, and processing failure without exposing raw provider payloads. Provider timeout, circuit-breaker, or budget-stop states return retryable safe errors or job failure states without leaking provider secrets, raw prompts, private URLs, or queue internals. MongoDB failover, transaction retry exhaustion, object-storage outage, worker unavailable, provider outage, search-index outage, publication outage, and maintenance readiness blocks return deterministic degraded, retryable, or service-unavailable responses instead of accidental 500 responses. Provider webhooks return success only after the event has been signature-verified and durably stored or safely recognised as duplicate or ignored — if durable storage or enqueue fails, the webhook returns a retryable failure so the provider can redeliver.