Custom Storefronts

A custom storefront is your own website or application for your Phasio store. Your customers use it to upload parts, get prices, place orders, and follow their orders. You control the design and the user experience. Phasio supplies the data, the prices, and the order processing through two APIs.

How it works

                      ┌──────────────────────────┐
                      │   Your storefront server │
 Customer's browser ─▶│  (holds the credentials) │
                      └──────┬────────────┬──────┘
                             │            │
              client ID + secret          access token
                             ▼            ▼
                      ┌───────────┐  ┌──────────────┐
                      │ Auth API  │  │ Customer API │
                      └───────────┘  └──────────────┘

What you need

1. A Phasio store, and an account that is an owner or admin of the organisation.
2. Your store name: the unique name of your store, as in the URL of your Phasio-hosted storefront.
3. The base URLs of the two APIs for your region. Refer to Base URLs.
4. A server (or serverless functions) for your storefront. A site that has only browser code cannot keep the client secret safe.

Base URLs

Use the region of your Phasio account. The address of your Phasio dashboard shows it: app.eu.phas.io or app.us.phas.io. Use the two URLs of one region together. Credentials and tokens from one region do not work in the other region.

Quick start

1. Create storefront credentials

1. Open <AUTH_SERVER>/account?tab=custom-storefronts and sign in.
2. Type a name for the storefront and select Create credentials.
3. Copy the client ID and the client secret. The secret shows one time only.

2. Check the connection

Read your store settings. This call needs no token:

curl "$API_BASE/api/customer/v1/operator" -H "X-Store-Name: your-store-name"

Get a guest token. This call needs the credentials:

curl -X POST "$AUTH_SERVER/customer/anonymous" \
  -u "$AUTH_CLIENT_ID:$AUTH_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "store": "your-store-name" }'

The response contains an access_token. Use it to call an endpoint that needs a token:

curl -X POST "$API_BASE/api/customer/v1/cart" \
  -H "X-Store-Name: your-store-name" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. Run the example storefront

The storefront starter is a small Next.js application that does the full flow: upload, price, sign-in, checkout, and order tracking.

git clone https://github.com/phas-io/storefront-starter.git
cd storefront-starter
cp .env.example .env.local   # then fill in the values
npm install
npm run dev

The repository also contains an agent skill in skills/phasio-storefront. It gives a coding agent the setup procedure and the API rules. Refer to the README of the repository for the installation.

4. Build your storefront

• Authentication: credentials, guest sessions, sign-up, sign-in, tokens, rate limits.
• The purchase flow: each call from upload to payment, in sequence.
• Customer API reference: all endpoints, data shapes, store settings, and errors.

Rules that you must obey

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.
• Access tokens are valid for 9 hours and cannot be revoked. Store them carefully.

Store settings

Your storefront must apply the settings of the store. The API does not apply all of them for you.

• loginStage: if it is BEFORE_PRICE, ask for sign-in before uploads and prices.
• maximumFileSize: reject larger part files before the upload.
• Payment methods: show only the methods that the store and the customer type permit.
• purchasability.canBePurchased: if it is false, offer "request a quote", not payment.
• termsOfServiceLink: show the link where customers upload files and sign in.

Things that are different from what you possibly expect

• There is no OAuth redirect and no hosted login page. You build the login screens.
• There is no refresh token and no sign-out endpoint.
• Part files must be compressed with gzip before the upload.
• The analysis result is MessagePack, and you can read it one time only.
• 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.
• 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.

Go-live checklist

• Separate storefront credentials for each environment.
• The client secret is in a secret store, not in the code.
• Session cookies are HttpOnly and Secure.
• Sign-in handles WAIT_FOR_APPROVAL, two factors, and 429.
• The guest cart is claimed after sign-in and after sign-up.
• 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.
• An expired token (401) sends the customer to sign-in, or gets a new guest token.