Custom Storefronts

Storefront rules

The store settings, security rules, and API behaviour that a custom storefront must handle, and the go-live checklist

Read this page before you build. It lists what the API does not do for you.

Security

  • Keep the client secret on your server. Do not put it in browser code, mobile applications, or a repository.
  • Call the Auth API from your server only.
  • Verify an access token (signature, issuer, expiry) before you trust its claims. Refer to Access tokens.
  • Access tokens are valid for 9 hours and cannot be revoked. Store them carefully.

Store settings that you must apply

Your storefront must apply the settings of the store. The API does not apply all of them for you. The settings come from GET /operator.

SettingWhat your storefront must do
loginStageIf it is BEFORE_PRICE, ask for sign-in before uploads and prices.
maximumFileSizeReject larger part files before the upload.
Payment methodsShow only the methods that the store and the customer type permit. Refer to Choose the payment methods.
purchasability.canBePurchasedIf it is false, offer "request a quote", not payment.
termsOfServiceLinkShow the link where customers upload files and sign in.

Differences from what you possibly expect

BehaviourDetails
There is no OAuth redirect and no hosted login page.You build the login screens. Refer to Authentication.
There is no refresh token and no sign-out endpoint.Refer to Lifetime, refresh, and sign-out.
Part files must be compressed with gzip before the upload.Refer to Upload parts.
The analysis result is MessagePack, and you can read it one time only.Refer to Read the analysis result.
A guest cannot read a cart back.Keep the cart ID and the items in your storefront.
A cart contains no prices.Prices come from POST /pre-order. Refer to Get a price.
A quote and an order are one resource.state changes from QUOTE to ORDER.
There are no webhooks or push channels for customers.Poll for status. Refer to Order tracking.

Go-live checklist

Credentials and tokens

  • Separate storefront credentials for each environment.
  • The client secret is in a secret store, not in the code.
  • The client secret is only in server-side environment variables.
  • All Auth API calls come from your server.
  • You verify tokens (signature, issuer, expiry) before you trust claims.
  • Session cookies are HttpOnly and Secure.

Sign-in

  • Sign-up and sign-in handle WAIT_FOR_APPROVAL.
  • Sign-in handles ["PASSWORD", "OTP"] (two factors).
  • You handle 429 responses.
  • The guest cart is claimed after sign-in and after sign-up.
  • An expired token (401) sends the customer to sign-in, or gets a new guest token.
  • You sign the customer out when the token expires.

Store settings and checkout

  • The storefront applies loginStage and maximumFileSize.
  • Checkout handles canBePurchased: false and lines with no instant price.
  • Error handling reads the HTTP status first and accepts an empty body.

Last updated on

Quick start

Create storefront credentials, make your first Auth API and Customer API calls, and run the example storefront

Authentication

Storefront credentials, Auth API conventions, the token response, and guest sessions

On this page

SecurityStore settings that you must applyDifferences from what you possibly expectGo-live checklist