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.
| Region | Base URL | Auth API |
|---|---|---|
| Europe (EU) | https://c-api.eu.phas.io/api/customer/v1 | https://auth.eu.phas.io |
| United States (US) | https://c-api.us.phas.io/api/customer/v1 | https://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:
| Header | When | Value |
|---|---|---|
X-Store-Name | Always | Your store name. It must be the same as the operator-name claim of the token. |
Authorization | All endpoints that are not public | Bearer <access token> |
Content-Type | Requests with a JSON body | application/json |
Access levels
Each endpoint has one of these access levels. The reference shows the level of each endpoint.
| Level | Meaning |
|---|---|
| Public | No token is necessary. X-Store-Name is necessary. |
| Guest | A guest token (ANONYMOUS) or a customer token (CUSTOMER) |
| Customer | A 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.
| Item | Value |
|---|---|
| Public keys (JWKS) | <AUTH_SERVER>/.well-known/jwks.json |
Issuer (iss) | <AUTH_SERVER> |
| Lifetime | 9 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":
| Claim | Type | Meaning |
|---|---|---|
iss | string | Auth API base URL |
sub | string | Customer ID, as a string |
iat, exp | number | Issue time and expiry time, in seconds |
scope | string | CUSTOMER |
type | string | customer |
operator-id | number | ID of your organisation (the manufacturer) |
operator-name | string | Your store name |
customer-id | number | Customer ID |
customer-principal | string | Sign-in identifier (the email address, in lower case) |
customer-organisation-id | number | ID of the customer's organisation |
client-id | string | Client ID of the storefront credentials |
first-name, last-name | string | Customer name |
language | string | Customer language, in lower case (default en) |
notification-preference | string | Default EMAIL |
has-custom-pricing | boolean | The customer has custom pricing |
is-approved | boolean | Always 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,Securecookie 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
nullwhen you do not use them.
Terms
| Term | Meaning |
|---|---|
| Operator | The manufacturer that owns the store (you) |
| Part revision | One uploaded version of a part |
| Process | A manufacturing process of the store (for example SLS or CNC) with its price list. Its ID is the processPricesId. |
| Requisition | One line of a quote or an order |
| Quote / order | One resource. state is QUOTE until the customer pays or accepts; then it is ORDER. |
| Thread | The conversation that belongs to an order or a project |
Pagination
Paginated list endpoints take three optional query parameters:
| Parameter | Description |
|---|---|
page | Zero-based page index. Default 0. |
size | Number of items on a page. Default 20. |
sort | property,asc or property,desc. Repeat the parameter to sort by more than one property. |
The response wraps the items in a page object:
| Field | Description |
|---|---|
content | The items on this page |
pageNumber | Zero-based index of this page |
pageSize | Number of items on a page |
totalElements | Number of items on all pages |
totalPages | Number of pages |
isFirst, isLast | This is the first or the last page |
isEmpty | This 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.
| Status | Meaning |
|---|---|
400 | The request is not valid |
401 | The token is missing, not valid, or expired |
403 | The request is not permitted, for example a guest token on a customer endpoint |
404 | The resource does not exist |
409 | The request conflicts with the state of the resource, for example a cart that is not open |
Common error codes
| Code | Status |
|---|---|
UNSUPPORTED_FILE_TYPE | 400 |
ANALYSIS_NOT_FOUND, PART_REVISION_NOT_FOUND | 404 |
CART_NOT_FOUND, CART_ITEM_NOT_FOUND | 404 |
CART_NOT_OPEN, CART_ALREADY_CLAIMED, CART_NOT_CLAIMED | 409 |
CART_FILE_TOO_LARGE | 400 |
ADDRESS_NOT_FOUND, SHIPPING_METHOD_NOT_FOUND, SHIPPING_RATE_NOT_FOUND | 404 |
INVALID_SHIPPING, SHIPPING_ERROR | 400 |
ORDER_HAS_NO_ITEMS, ORDER_ERROR | 400 |
ORDER_NOT_FOUND | 404 |
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
| Limit | Value |
|---|---|
All /customer/* calls | 600 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.
| Limit | Value |
|---|---|
| Sign-in codes sent | 5 in 15 minutes |
| Sign-up codes sent | 5 in 15 minutes |
| Incorrect codes | 10 in 15 minutes |
| Incorrect passwords | 10 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