Skip to Content

Customer API

Connect a custom storefront to your Phasio store with the Customer REST API

The Customer API is the REST API that a custom storefront uses for all store data: settings, parts, prices, carts, orders, and payments. It acts for your store's guests and customers, not for your organisation. To work with your own organisation's data, use the Manufacturer API.

The interactive reference lists every endpoint with its parameters, request and response bodies, and error codes, and lets you send test requests.

Base URL

All paths start with /api/customer/v1. Use the host of the region of your Phasio account.

RegionBase URLAuth API
Europe (EU)https://c-api.eu.phas.io/api/customer/v1https://auth.eu.phas.io
United States (US)https://c-api.us.phas.io/api/customer/v1https://auth.us.phas.io

Use the Customer API and the Auth API of one region together. Credentials and tokens from one region do not work in the other region.

Authentication

The Customer API authenticates with access tokens, not API keys. Your storefront's server gets them from the Auth API with your storefront credentials (a client ID and a client secret):

  • A guest token (ANONYMOUS) for a visitor who has not signed in.
  • A customer token (CUSTOMER) after the customer signs in.

Tokens last 9 hours, and there is no refresh token. For credentials and sign-in, refer to Authentication. For token verification, claims, and lifetime, refer to Access tokens.

Send these headers:

HeaderWhenValue
X-Store-NameAlwaysYour store name. It must be the same as the operator-name claim of the token.
AuthorizationAll endpoints that are not publicBearer <access token>
Content-TypeRequests with a JSON bodyapplication/json

Access levels

Each endpoint has one of these access levels. The reference shows the level of each endpoint.

LevelMeaning
PublicNo token is necessary. X-Store-Name is necessary.
GuestA guest token (ANONYMOUS) or a customer token (CUSTOMER)
CustomerA customer token (CUSTOMER)

If you send a token to a public endpoint, the API validates it. An expired token gives 401 on a public endpoint too.

A customer sees only the data of the customer's own organisation. A guest sees only the parts and carts of the guest's own session.

Access tokens

Access tokens are JWTs signed with RS256.

ItemValue
Public keys (JWKS)<AUTH_SERVER>/.well-known/jwks.json
Issuer (iss)<AUTH_SERVER>
Lifetime9 hours

The JWKS can contain more than one key. Select the key by the kid header. Standard JWT libraries do this for you.

Verify a token on your server

Verify the signature, the issuer, and the expiry before you trust a claim. Example with the jose library:

import { createRemoteJWKSet, jwtVerify } from 'jose'

const jwks = createRemoteJWKSet(new URL(`${process.env.AUTH_SERVER}/.well-known/jwks.json`))

export async function verifyAccessToken(token: string) {
  const { payload } = await jwtVerify(token, jwks, { issuer: process.env.AUTH_SERVER })
  return payload
}

Customer token claims

Claims of a token with scope: "CUSTOMER":

ClaimTypeMeaning
issstringAuth API base URL
substringCustomer ID, as a string
iat, expnumberIssue time and expiry time, in seconds
scopestringCUSTOMER
typestringcustomer
operator-idnumberID of your organisation (the manufacturer)
operator-namestringYour store name
customer-idnumberCustomer ID
customer-principalstringSign-in identifier (the email address, in lower case)
customer-organisation-idnumberID of the customer's organisation
client-idstringClient ID of the storefront credentials
first-name, last-namestringCustomer name
languagestringCustomer language, in lower case (default en)
notification-preferencestringDefault EMAIL
has-custom-pricingbooleanThe customer has custom pricing
is-approvedbooleanAlways true (customers who are not approved get no token)

Claims are read at sign-in. A change to the customer profile shows in the token after the next sign-in.

Guest token claims

Claims of a token with scope: "ANONYMOUS": iss, sub (a random ID for this guest), iat, exp, scope (ANONYMOUS), type (anonymous), operator-id, operator-name, client-id.

Lifetime, refresh, and sign-out

  • A token is valid for 9 hours. There is no refresh token.
  • When a customer token expires, the customer must sign in again.
  • When a guest token expires, get a new guest token.
  • There is no sign-out endpoint. To sign a customer out, delete the token that your storefront holds.
  • A token stays valid until it expires, unless the manufacturer un-approves or deletes the customer's organisation. Then every token issued to that organisation's customers stops working at once and the API returns 401. The customer cannot sign in again while the organisation is not approved.
  • Store tokens carefully. An HttpOnly, Secure cookie set by your server is a good choice.

Make your first request

Read the settings of your store. This call is public, so it needs no token:

curl https://c-api.eu.phas.io/api/customer/v1/operator \
  -H "X-Store-Name: your-store-name"

To create credentials and make your first calls with a token, follow the Quick start.

Browser or server

The Customer API accepts cross-origin calls, so a browser can call it directly with a Bearer token. The Auth API does not. If you call the Customer API from the browser, your scripts hold the access token. If you call it from your server, you can keep the token in an HttpOnly cookie. The example storefront uses the server.

Data formats

  • Dates and times are ISO 8601 strings.
  • Prices are decimal numbers in the given currency.
  • Numeric IDs are JSON numbers. UUID IDs are strings.
  • Enumerations are upper-case strings.
  • Responses can contain fields that are not in the reference. Ignore them.
  • In request bodies, send optional fields with the value null when you do not use them.

Terms

TermMeaning
OperatorThe manufacturer that owns the store (you)
Part revisionOne uploaded version of a part
ProcessA manufacturing process of the store (for example SLS or CNC) with its price list. Its ID is the processPricesId.
RequisitionOne line of a quote or an order
Quote / orderOne resource. state is QUOTE until the customer pays or accepts; then it is ORDER.
ThreadThe conversation that belongs to an order or a project

Pagination

Paginated list endpoints take three optional query parameters:

ParameterDescription
pageZero-based page index. Default 0.
sizeNumber of items on a page. Default 20.
sortproperty,asc or property,desc. Repeat the parameter to sort by more than one property.

The response wraps the items in a page object:

FieldDescription
contentThe items on this page
pageNumberZero-based index of this page
pageSizeNumber of items on a page
totalElementsNumber of items on all pages
totalPagesNumber of pages
isFirst, isLastThis is the first or the last page
isEmptyThis page has no items

Errors

An error response has a JSON body with a stable error code and a message for people:

{
  "error": "CART_NOT_OPEN",
  "message": "Cart is not open"
}

Match on error and the HTTP status in your code, not on message. Validation errors can add a fields object. A missing X-Store-Name, or one that does not match the token, gives 401 or 403.

StatusMeaning
400The request is not valid
401The token is missing, not valid, or expired
403The request is not permitted, for example a guest token on a customer endpoint
404The resource does not exist
409The request conflicts with the state of the resource, for example a cart that is not open

Common error codes

CodeStatus
UNSUPPORTED_FILE_TYPE400
ANALYSIS_NOT_FOUND, PART_REVISION_NOT_FOUND404
CART_NOT_FOUND, CART_ITEM_NOT_FOUND404
CART_NOT_OPEN, CART_ALREADY_CLAIMED, CART_NOT_CLAIMED409
CART_FILE_TOO_LARGE400
ADDRESS_NOT_FOUND, SHIPPING_METHOD_NOT_FOUND, SHIPPING_RATE_NOT_FOUND404
INVALID_SHIPPING, SHIPPING_ERROR400
ORDER_HAS_NO_ITEMS, ORDER_ERROR400
ORDER_NOT_FOUND404

Rate limits

The Auth API applies rate limits for each set of storefront credentials and for each customer. When you exceed a limit, the API returns 429. Some 429 responses have a Retry-After header (seconds). Wait, then try again.

Limits for each set of storefront credentials

LimitValue
All /customer/* calls600 in 1 minute
Guest sessions (/customer/anonymous)1200 in 15 minutes
Sign-in codes sent (/customer/otp/send)600 in 15 minutes
Sign-up codes sent (/customer/signup/otp/send)600 in 15 minutes
Pre-auth calls (/customer/login/pre-auth)1800 in 15 minutes

Limits for each end customer

These limits apply to one email address at your store.

LimitValue
Sign-in codes sent5 in 15 minutes
Sign-up codes sent5 in 15 minutes
Incorrect codes10 in 15 minutes
Incorrect passwords10 in 15 minutes

After a customer uses up the incorrect-code or incorrect-password limit, the correct value also gives 429 until the 15 minutes end. A new sign-in code resets the incorrect-code limit.

Guidance

  • Do not get a new guest token on each page load. Get one for each visitor and keep it.
  • Show a clear "try again later" message on 429.

Last updated on

On this page