Skip to content
SoundSyncAudio software platform

API reference

Evaluate & Test API

Owner-scoped test workspace, guided customer store, private inbox, design copy and explicit production activation.

SoundSync

Environment and billing boundaries

Keep Test & Launch, External website settings and Billing together in your setup flow.

ActionBehavior
EvaluateUse separate test developer/customer accounts, products, private website key, callback origin, payment sandbox credentials and files. Set SOUNDSYNC_EXPECTED_ENVIRONMENT=test and send X-SoundSync-Expected-Environment: test from your platform. Evaluation cannot collect developer service invoices or send payouts.
Try JUCE immediatelyOpen Website Builder → Evaluate & Test → Start guided test. Sample paid/free products and a test customer are prepared without product forms or live billing. Buy or claim with that customer, then use its password, issued serial and matching current JUCE source to test activation, downloads and emails. Samples stay in the isolated Practice catalog; production products and customers are unchanged.
Handle sessionsAccount tokens expire after 30 days; JSON login includes session.expiresAt and refreshSupported:false. No refresh endpoint is available. Starter website sessions default to 24 hours. Store tokens privately and ask for sign-in again after expiry or a 401.
Claim TailFitConfigure the server product at $0 with delivery files and optional serial licensing. A verified customer claims through POST /api/checkout/claim, then reads their scoped library and authorized download. A paid product is rejected without opening checkout.
Activate productionThe live developer account owner reviews pricing on Billing and explicitly activates the selected service. Draft setup and isolated evaluation do not start monthly billing. Publishing a product or generating serials requires activation first; these actions no longer silently activate billing. Existing active service and customer access are preserved.
Keep your websiteRegistration, login, recovery, store and library pages can use your own design. Full Store paid checkout uses SoundSync-managed Stripe/PayPal and server tax quotes. Free claims bypass payment.

SoundSync

Free-only claim

Your platform fixes the storefront, verified website origin and product ID. The action accepts no browser price and creates no paid provider checkout.

SoundSync

One-click developer Practice access

The verified developer owner or an active Administrator / Developer / Engineer with all-product access selects Open Evaluate & Test. Teammates enter the same isolated workspace under their own identity, with live authority rechecked within 30 seconds. No second password, repeated brand setup or completed onboarding is required. A browser-bound one-use handoff opens the stable isolated workspace. Production account tokens never go to Practice.

SoundSync

Shared technical Practice tools

Open the team’s shared sample store and source packages without reading or replacing the owner’s test customer. Selected live-product IDs are not mapped to isolated sample IDs, so shared Practice requires all-product scope.

SoundSync

Guided store and compatibility quick demo

Technical workspace members may use the demo in the isolated evaluation environment. The guided customer and private inbox remain owner-only. Uses the same released JUCE source/generator as normal downloads, the regular licensing API and private test inbox; no demo is inserted into your catalog.

SoundSync

Explicit service activation

Owner-only, all-product billing scope. Confirm current pricing before production; this action activates the agreement rather than sending a payment.

Evaluate a custom website before live commerce

Keep your own frontend and Node, PHP or other platform. Full Store uses SoundSync's managed checkout and tax calculation; external licensing keeps payments and tax with the external provider. Website design and payment ownership are separate choices.

Choose the API environment first

Open Website Builder → Evaluate & Test (the last menu item), then Open Evaluate & Test. Your verified developer owner login opens the isolated workspace automatically. You do not create another password or repeat business/brand onboarding. Existing Practice workspaces are reused. The browser handoff uses a short-lived, single-use ticket tied to a Secure, HttpOnly browser cookie; your production password and account token are never copied. An existing Practice account's separately enabled two-factor authentication is still honored. Billing, Custom API and Product Preview also link to these instructions.

An evaluation deployment has its own database, customer accounts, products, website verification/key, payment credentials, webhook secrets and private files. A verified developer account can use it before completing production onboarding. On first entry, Practice prepares Full Store test features and a basic test storefront using your developer display name (or a default name). This is not acceptance or activation of a paid service. Existing workspace settings are preserved. Choose Start guided test to prepare a connected sample store and two JUCE products automatically. You can also add your own test products later. No production activation is required. Never copy production customers, passwords, payment methods, private website keys or billing agreements into evaluation. Practice includes 2 GB of test delivery files; no storage action starts paid service.

One connected Practice store

For an external FastSpring, Gumroad or WooCommerce journey, create its Test connection in this isolated workspace and map a Practice product. Complete the provider's own test checkout and register the customer using the same purchase email. An authenticated confirmation creates a usable test serial, entitlement and download access for that customer; use the matching Practice JUCE package for email/password or email/serial activation. Full refunds revoke only that purchase's access. Provider Test connections on production remain simulations without plugin access. Only a verified evaluation database may issue these external test licenses; Live connections and developer usage billing remain disabled here. Use a new provider test order for this journey; earlier simulation-only orders are preserved.

Inside Website Builder → Evaluate & Test, the Evaluate & Test card has three actions: Start guided test, Open test store and Test inbox. No further developer signup, brand forms or product fields are required. First preparation enables Full Store test features, publishes the isolated test storefront and adds Practice Plugin ($10 sandbox price) and Practice Free Plugin ($0). These sample products appear in your Practice catalog only, never your production catalog. Existing Practice brand/layout settings and previous customers, orders and licenses are kept. Restart guided test refreshes the packages and instructions; it does not erase customers or reset purchased licenses.

The Your test customer section stays visible throughout the guide. The email defaults to your developer email. You can enter a different test address before Start guided test, but only the developer’s verified address can receive external messages. The guide creates an ordinary unverified customer with a separate generated customer password. Your developer password does not log into this customer, even when the email matches. Account in the plugin uses email + password; Serial uses email + the serial issued after purchase/free claim. Use the copy controls for each field.

Credentials stay until Create replacement customer. Replacement preserves prior logins, purchases, licenses and downloads. Password recovery hides the old generated password; use your new one. Passwords are encrypted at rest, owner-only and never included in plugin binaries or shared ZIPs. Verification, receipts, recovery and activation messages always stay in the private Test inbox. When the isolated Practice mail transport is configured, supported messages addressed to your SSO-verified developer email also go to that mailbox. Other addresses and marketing previews remain capture-only. The guide shows whether external delivery is configured and each message’s submission status; provider acceptance does not prove inbox delivery. Send email check exercises the configured route. Existing fictional customers can be replaced using Use my developer email; prior purchases and logins are preserved. A replacement needs an unused address, since an existing customer’s password is never overwritten.

The four-step guide covers:

1. Customer account: open the store in another tab, verify the generated customer using your mailbox or Test inbox, then try sign-in and password recovery. Practice customer sessions are scoped by storefront and kept separate from your developer session, including sign-out. Or register another fictional customer manually to test the signup form. Keep the developer window signed in. A separate customer session is essential; a developer login is not a test customer.

2. Purchase & library: buy the paid sample using the enabled provider sandbox and test details only, then claim the free product from its product page without checkout. The guide shows the configured test billing location and Stripe's 4242 4242 4242 4242 test card (any future expiry and three-digit CVC); use fictional details, never a real card. Wait for verified payment fulfillment. Both products use the ordinary customer library, their own serial licenses and entitlement-checked private downloads. The guide clearly reports when paid sandbox checkout is not configured; a free claim does not prove provider payment connectivity.

3. Try the plugin: download the matching source ZIP from the library or guide. Build its standalone/plugin example with your existing JUCE installation. Sign in with the same customer account, or use that product's purchased/claimed serial and email activation. Try Store, My Products, validation, offline grace and deactivation. A seeded customer notice exercises Notifications, Store/My Products navigation and Dismiss when the separate Practice notices switch is enabled. Purchase, email activation and notices follow the real application routes; the wizard does not manufacture successful ownership.

4. Your integration: copy the Practice API origin, test environment and storefront configuration, configure a staging website and private test website key through Custom API & starter kits, then repeat the journey on your own frontend/plugin. The sample store demonstrates SoundSync behavior; it cannot prove your custom frontend works. The same API supports Node/Astro and all other documented website kits.

The JUCE packages use the same current released generator and integration sources as regular product packages. You can integrate this source into your own JUCE plugin to test the sample product and its customer journey. To license a different product, generate that product’s matching package through JUCE setup; a sample product’s IDs and licenses do not become another product’s licenses. The configured Practice API, product/app IDs, storefront URLs and independent offline verification keys belong to the specific sample product. Account, serial and email activation are enabled. Their current version is displayed; the source fingerprint is recorded in manifest.json. The guide and customer library deliver the same private object for that product. Source/signing-key changes invalidate the cache; Guide downloads and authorized customer delivery refresh the matching file automatically when the release, signing keys or sample configuration changes. Practice follows the production release branch; developer sign-in waits for a matching release during rollout. These downloads are source code, not precompiled plugins. Normal production packages remain HTTPS-only; local operator packages permit HTTP only to their exact configured loopback origin.

Test inbox is an expandable section within the same card. It holds the latest 100 messages for your workspace: customer verification/recovery, license email activation and purchase messages. Open action links in the customer tab and refresh as needed. Captured HTML is displayed safely as text with allowlisted links. Other developers cannot read these messages. Capture-only installations test content and links; configured Practice mailbox delivery also submits supported messages to the SSO-verified developer address through its dedicated transactional transport. Elastic marketing remains disabled.

Connect your own website or plugin is collapsed by default and links to the existing Custom API hookup instructions. Private website keys stay on the developer's own platform and are not embedded in the plugin or public page.

Advanced testing links to the normal Practice customer/licensing tools for expiry, revocation and sandbox refunds. The guide uses its paid/free samples and the same displayed customer throughout. The separate legacy quick-demo APIs remain compatible for existing tests, but the guided store does not show or fetch their unrelated products, serials or packages. Each result must be observed; navigation does not mark a workflow passed.

Your private website configuration must select both the supplied evaluation origin and SOUNDSYNC_EXPECTED_ENVIRONMENT=test. New kits send X-SoundSync-Expected-Environment: test; an API mismatch stops the request before account, claim or payment actions. A public request field cannot select the payment environment. A staging website connected to https://www.soundsync.dev still uses production.

SoundSync

Private staging configuration

Example
SOUNDSYNC_API_ORIGIN=https://THE-EVALUATION-API-SUPPLIED-BY-SOUNDSYNC
SOUNDSYNC_EXPECTED_ENVIRONMENT=test
SOUNDSYNC_STOREFRONT=YOUR-TEST-STOREFRONT
SOUNDSYNC_WEBSITE_KEY=YOUR-PRIVATE-TEST-WEBSITE-KEY
WEBSITE_ORIGIN=https://YOUR-VERIFIED-STAGING-WEBSITE
SOUNDSYNC_WEBSITE_MODE=full_store
SOUNDSYNC_CHECKOUT_PROVIDER=soundsync

Keep evaluation and production settings separate

Restart your private platform after changing these values. Use separate deployments or environment files for test and live; never overwrite a running live website's callbacks or key to perform a test. Test checkout must use the provider's displayed sandbox/test account or test card, never saved real payment details.

Accounts and session expiry

Register with POST /api/auth/register, verify the one-use email link through POST /api/auth/verify-email, then call POST /api/auth/login. Fix role: customer and storefrontSlug on your platform. Registration does not sign the customer in.

The account token expires after 30 days, with earlier invalidation possible after logout or account-security changes. JSON login now includes session.expiresAt, session.expiresInSeconds and session.refreshSupported: false. There is no refresh-token endpoint. Prompt for sign-in again after expiry or a 401. Never store a customer's password to silently repeat login.

The starter website's private server session defaults to 24 hours, independently of the account token. Node/PHP handlers keep the token off the browser and clear expired/revoked sessions. Use HttpOnly, Secure, SameSite cookies and private session storage. A longer website cookie does not extend an API token's expiry.

TailFit and other free products

Configure a one-time SoundSync product whose server-calculated price is $0. Attach its hosted delivery files, enable downloads and enable serial licensing if the plugin needs it. In evaluation, publish the test copy. Production publication requires explicit service activation first. Marketplace listing is not required for a direct website claim.

The customer selects TailFit in the catalog, opens its product page and chooses Get it free. Guests register or sign in first, verify their email, then return to that product to claim it. Native verification links preserve the product destination. Starter kits preserve the selected product/offer through registration, verification and sign-in in the website's private session, scoped to that customer. The claim adds the product to the library and opens account downloads. There is no free-download button on the checkout page or inside the library's purchase form. This applies to SoundSync storefronts and all custom website starter kits, including Astro, Next.js, Nuxt, SvelteKit, Express, PHP, Laravel and WordPress.

After verified customer sign-in, the product-page action calls your private platform, which calls:

SoundSync

Free-claim request example

Example
POST /api/checkout/claim
Authorization: Bearer CUSTOMER-ACCOUNT-TOKEN
X-SoundSync-Website-Key: PRIVATE-WEBSITE-KEY
X-SoundSync-Client-IP: VERIFIED-VISITOR-IP
X-SoundSync-Expected-Environment: test
Content-Type: application/json

{"productId":123,"storefrontSlug":"YOUR-TEST-STOREFRONT","headlessOrigin":"https://YOUR-VERIFIED-STAGING-WEBSITE"}

Product-page claim results and library access

The server validates the product, website, customer scope and actual price. A positive amount returns PRODUCT_NOT_FREE; the action never starts paid checkout. A successful response has claimed: true, freeClaim: true, checkoutBypassed: true and an order ID. Repeated claims return the existing claim with alreadyClaimed: true. A $0 claim needs no payment method or paid-checkout billing-address form.

Then request GET /api/library?storefront=YOUR-TEST-STOREFRONT with that customer's token. Use the returned delivery references through the private platform. The authorized delivery endpoint issues a short-lived private R2 redirect; never publish a permanent raw file URL or grant access from a success-page query parameter.

The shared Node client exposes client.claim({productId}, token). Kits expose the same authenticated action at their private /api/soundsync/claim route. Starter catalog/product pages live at /products and /products/PRODUCT-SLUG (or /products?slug=PRODUCT-SLUG). WordPress uses [soundsync_products] and [soundsync_product slug="tailfit"]; put [soundsync_account] on /account and [soundsync_checkout] on /checkout. For configured purchase offers, pass the selected offerId, offerVersionId and priceVersionId; the server still calculates the price. External-provider purchases and free claims remain owned by that provider. The older /api/checkout/product free-claim API remains compatible, but new customer interfaces use the product page.

Paid checkout and the full journey

Keep your store, account, recovery and library pages. Paid checkout obtains countries/regions and a fresh server tax quote, then creates the SoundSync-managed Stripe or PayPal checkout. The buyer finishes on the provider's secure page. SoundSync's verified confirmation creates access; returning to your website does not prove payment.

Check registration, verification, login/logout, recovery, TailFit claim, repeated claim, a paid provider test purchase, pending/failed/cancelled return, license/library delivery, unauthorized download denial, duplicate notification, full test refund and revoked access. Simulated local providers test application behavior; only a provider-executed sandbox transaction verifies the hosted provider connection. Keep both types of evidence labeled accurately.

The billing boundary

Selecting a service and preparing drafts do not start monthly service billing. Isolated evaluation does not create collectible SoundSync service invoices or send developer payouts, and it does not activate itself after a period of time.

When ready, return to the live developer account → Billing → Your SoundSync services. The developer account owner reviews the current selected pricing and explicitly chooses Activate live commerce (Full Store) or Activate production service (licensing options). A previously inactive live service needs a verified billing card and no blocking unpaid SoundSync bill before activation can complete. A missing-card or unpaid-bill response (HTTP 402) or temporary funding-verification failure (HTTP 503) is not successful activation: resolve the returned state and review Billing again. Confirming activates the agreement; it does not itself send a payment. The applicable calendar-month service minimum/fixed fee is not prorated. Email/redemption usage and actual provider fees follow the current published pricing separately.

Before activation, production stores remain drafts. Known public storefront/custom-domain/embed pages show a minimal Coming soon page; public catalog APIs do not expose their products. New store-customer registration, checkout (including quotes and new free claims), new serial/license grants, external sales connections and real marketing delivery require an already activated service. Draft editing and local uploads within the draft allowance remain available. Publishing and licensing never activate billing implicitly. Existing customer sign-in and recovery keep using the verified account callbacks even if the storefront is a draft.

Activation is one-way and idempotent. The button confirms the exact agreement shown on Billing; if another tab changes it, refresh and review its pricing again. Service selection is locked while funding and activation are checked. The interface offers no switch to turn a live membership off. A future pause/cancel process is separate. Existing active agreements, previously issued licenses, customer recovery and authorized downloads are preserved.

Resume a test safely

- An expired, used or different-browser handoff needs a fresh Open Evaluate & Test from the verified owner account in the same browser. Do not share its private URL or reuse the ticket in another browser.

- PRACTICE_PACKAGE_UPDATING means the evaluation app needs the matching source release. Reopen from the live dashboard after it becomes available; never substitute a live API/key to bypass it.

- PRACTICE_LOCAL_MFA_REQUIRED preserves a separately enabled test-account two-factor setting. Continue through that account's existing sign-in or recovery flow.

- PRACTICE_CUSTOMER_EMAIL_EXISTS means use the existing customer login or choose an unused address. Omitting customerEmail or sending an empty string uses the developer email for a new customer. Restarting the guide keeps an existing generated customer unless the owner explicitly replaces it; replacement never overwrites another customer's password or acquired access.

- PRACTICE_DESIGN_CHANGED needs a refreshed snapshot/page and another review of the current source and target. A failed copy must not be treated as applied.

- A captured, limited, failed or uncertain mail result is not successful mailbox delivery. Use the private Test inbox, inspect the guide's delivery state and do not blindly repeat an uncertain submission.

Hosted website and custom frontend

Preview SoundSync-hosted test website shows the actual Practice storefront inside the guide. Open Customer website in another tab for accounts and checkout; provider checkout cannot run inside the preview. Edit Practice website opens the normal Website Builder for this isolated site. To reuse the current live appearance, open the preview section, review the design snapshot and check Replace the current Practice appearance, then choose Copy my website design. This is optional and never happens on sign-in. The copy includes colors, public logos/images, templates, text, semantic navigation and page layout. It keeps Practice products, customers, licenses, downloads, domains, website keys, checkout settings and marketing campaigns. Source product IDs, custom/external links, production domains, tracking/configuration metadata and private/signed file URLs are excluded. Public artwork is referenced from its existing public asset host; it is not duplicated into private storage.

The snapshot is read-only and comes through the existing short-lived, browser-bound sign-in handoff. Refresh design from live dashboard obtains a newer snapshot. Copying is blocked if either the snapshot or Practice settings changed after you reviewed them. Very large or unavailable designs are reported without blocking Practice sign-in; use the normal builder in that case. A private recovery copy of the previous Practice visual settings is retained by the application. The live website is never edited by capture or application.

For your own frontend, configure its separate HTTPS staging origin in Practice’s Custom API, verify its TXT record, create a private test website key, and use the test configuration in the guide. The guide displays the configured origin and verification status, with a link to the staging website. The same Node/Astro/PHP and other kits call the same Practice account, checkout, library, delivery and license APIs. Keep keys and customer sessions on your platform. Merely opening the guide does not connect or test your actual website; repeat the journey on the configured staging frontend. Never point that test frontend at the live API or copy its production key.

Local operator setup

Install the repository dependencies, have PostgreSQL binaries available (PG_BIN if needed), then run from this local checkout:

SoundSync

Run a local-only rehearsal

Example
$env:NODE_ENV = 'development'
npm run evaluation:start

Local sandbox credentials and storage

The launcher creates its own loopback PostgreSQL cluster, marked soundsync_evaluation database, local S3-compatible storage, independent authentication/encryption/offline-signing keys and private email capture. It ignores production environment files. Open http://127.0.0.1:4080/signup, create a fictional developer account, then visit /developer/practice. All state stays in .evaluation/local under this checkout; Ctrl+C stops services and keeps practice data. It is a local storage rehearsal, not proof of hosted R2/provider connectivity.

Free claims and private uploads/downloads work without payment credentials. Upload local test files; remote URL imports are disabled in practice. For paid tests only, fill .evaluation/local/sandbox-providers.json with isolated Stripe test and/or PayPal sandbox credentials, then restart. Its allowlist rejects live Stripe keys and unrelated settings; do not paste secrets into chat or commit the file. Fixed test buyer-country evidence is labeled simulated. Live keys, known production origins, unsafe buckets and mismatched database identities prevent evaluation startup. Automatic workers and financial sending stay disabled.

Hosted developers enter through Open Evaluate & Test; they do not provision a database or deploy the evaluation app. For operator-managed hosting, deploy/evaluation/README.md and the separate platform/practice configuration templates describe infrastructure setup. Paid custom-site tax tests also require a separate evaluation location-evidence issuer and secret; follow [Headless tax evidence](./headless-tax-evidence.md). Never expose the private mail directory as static content. The authenticated workspace inbox is the supported developer interface.

SoundSync

Private inbox and reviewed design copy

GET /api/developer/practice/messages

List the latest 100 private test messages

Auth
Account Bearer session token
Scope
Developer workspace owner with practice.view and all-products scope, in the isolated evaluation environment. Teammates cannot read the owner inbox or generated customer credentials.
Returns
HTTP 200: messages.
Notes
Owner-only private no-store response. Test account, message and package data stay scoped to the effective workspace. These operations do not enable production billing, real payments, automatic payouts or live marketing. The limit is a recent-message view, not a fixed calendar deletion deadline for all evaluation records.
Request, response and error reference

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evaluation-[a-f0-9-]{36}$"
          },
          "recipient": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "delivery_status": {
            "type": "string"
          },
          "delivery_error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: PRACTICE_ONLY, PRACTICE_OWNER_REQUIRED, PRACTICE_UNAVAILABLE, developer_team_permission_denied, developer_team_all_products_scope_required.

GET /api/developer/practice/messages/{id}

Read one workspace message as safe text and permitted links

Auth
Account Bearer session token
Scope
Developer workspace owner with practice.view and all-products scope, in the isolated evaluation environment. Teammates cannot read the owner inbox or generated customer credentials.
Request fields
  • path id: string (required). The evaluation message ID returned by the owner inbox, not another workspace ID.
Returns
HTTP 200: message.
Notes
Owner-only private no-store response. Test account, message and package data stay scoped to the effective workspace. These operations do not enable production billing, real payments, automatic payouts or live marketing. Captured HTML is converted to text. Returned links are allowlisted to the evaluation application or its verified staging website; do not execute captured HTML.
Request, response and error reference

Query and header parameters

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^evaluation-[a-f0-9-]{36}$"
    },
    "description": "The evaluation message ID returned by the owner inbox, not another workspace ID."
  }
]

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "message": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^evaluation-[a-f0-9-]{36}$"
        },
        "recipient": {
          "type": "string"
        },
        "subject": {
          "type": "string"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "text": {
          "type": "string"
        },
        "links": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "deliveryStatus": {
          "type": "string"
        },
        "deliveryError": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503, 404.

Operation errors: PRACTICE_ONLY, PRACTICE_OWNER_REQUIRED, PRACTICE_UNAVAILABLE, developer_team_permission_denied, developer_team_all_products_scope_required, TEST_MESSAGE_NOT_FOUND.

POST /api/developer/practice/messages/{id}/send

Request a supported copy to the verified developer mailbox

Auth
Account Bearer session token
Scope
Developer workspace owner with practice.view and all-products scope, in the isolated evaluation environment. Teammates cannot read the owner inbox or generated customer credentials.
Request fields
  • path id: string (required). The evaluation message ID returned by the owner inbox, not another workspace ID.
Returns
HTTP 200: delivery.
Notes
Owner-only private no-store response. Test account, message and package data stay scoped to the effective workspace. These operations do not enable production billing, real payments, automatic payouts or live marketing. Only supported transactional messages addressed to the SSO-verified developer email may be submitted when its dedicated transport is configured. Arbitrary recipients, marketing previews and CC/BCC remain captured. Existing submitted messages are not blindly duplicated. Rate/attempt limits and uncertain outcomes apply. A malformed, unavailable or other-workspace message returns 404 TEST_MESSAGE_NOT_FOUND. HTTP 200 with captured, limited, failed, uncertain, expired or not_found is not successful mailbox delivery; submitted means provider acceptance only.
Request, response and error reference

Query and header parameters

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^evaluation-[a-f0-9-]{36}$"
    },
    "description": "The evaluation message ID returned by the owner inbox, not another workspace ID."
  }
]

Request (application/json)

{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "delivery": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string"
        },
        "mode": {
          "type": "string"
        },
        "providerId": {
          "type": "string"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503, 404.

Operation errors: PRACTICE_ONLY, PRACTICE_OWNER_REQUIRED, PRACTICE_UNAVAILABLE, developer_team_permission_denied, developer_team_all_products_scope_required, TEST_MESSAGE_NOT_FOUND.

POST /api/developer/practice/messages/preview

Capture an email-route check and submit a verified mailbox copy when configured

Auth
Account Bearer session token
Scope
Developer workspace owner with practice.view and all-products scope, in the isolated evaluation environment. Teammates cannot read the owner inbox or generated customer credentials.
Returns
HTTP 201: data, error, practiceDelivery.
Notes
Owner-only private no-store response. Test account, message and package data stay scoped to the effective workspace. These operations do not enable production billing, real payments, automatic payouts or live marketing. Uses the signed-in owner email rather than a body-supplied recipient. Always captures the test message. A configured and verified mailbox route may also submit a supported copy; inspect practiceDelivery. No live marketing send is performed.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^evaluation-[a-f0-9-]{36}$"
        }
      },
      "additionalProperties": true
    },
    "error": {
      "type": "null"
    },
    "practiceDelivery": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string"
        },
        "mode": {
          "type": "string"
        },
        "providerId": {
          "type": "string"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: PRACTICE_ONLY, PRACTICE_OWNER_REQUIRED, PRACTICE_UNAVAILABLE, developer_team_permission_denied, developer_team_all_products_scope_required.

POST /api/developer/practice/store/design

Apply the reviewed visual snapshot only to the isolated test website

Auth
Account Bearer session token
Scope
Developer workspace owner with practice.view and all-products scope, in the isolated evaluation environment. Teammates cannot read the owner inbox or generated customer credentials.
Request fields
  • confirm: true (required)
  • sourceHash: string (required)
  • targetVersion: string (required)
Returns
HTTP 200: design.
Notes
Owner-only private no-store response. Test account, message and package data stay scoped to the effective workspace. These operations do not enable production billing, real payments, automatic payouts or live marketing. Read sourceHash/targetVersion from store.designCopy, review and explicitly confirm replacement. A changed source snapshot or target is rejected. Copies allowed visual settings and takes a private recovery copy of the old test appearance. Production is never written; customer/payment/product/license/domain/key/tracking configuration is not imported.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "confirm": {
      "const": true
    },
    "sourceHash": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "targetVersion": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "confirm",
    "sourceHash",
    "targetVersion"
  ],
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "design": {
      "type": "object",
      "properties": {
        "available": {
          "type": "boolean"
        },
        "state": {
          "type": "string"
        },
        "sourceName": {
          "type": [
            "string",
            "null"
          ]
        },
        "sourceHash": {
          "type": [
            "string",
            "null"
          ]
        },
        "capturedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "appliedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "appliedHash": {
          "type": [
            "string",
            "null"
          ]
        },
        "targetVersion": {
          "type": "string"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 503.

Operation errors: PRACTICE_ONLY, PRACTICE_OWNER_REQUIRED, PRACTICE_UNAVAILABLE, developer_team_permission_denied, developer_team_all_products_scope_required, PRACTICE_DESIGN_CONFIRM_REQUIRED, PRACTICE_DESIGN_UNAVAILABLE, PRACTICE_DESIGN_CHANGED, EVALUATION_DATABASE_MISMATCH.