Customer API reference
Conventions, store settings, and errors of the Customer API
The Customer API is the API that a storefront uses for all store data: settings, parts, prices, carts, orders, and payments.
For tokens, refer to Authentication.
Reference pages
The reference follows the order of the purchase flow.
| Page | Contents |
|---|---|
| This page | Conventions, store settings, and errors |
| API: parts, carts, and prices | Part upload and analysis, manufacturability, carts, pre-order prices, bulk prices, discount codes |
| API: customers and orders | Customer profile, addresses, shipping rates, orders, payment, documents, messages, projects, catalog |
Base URL
<API_BASE>/api/customer/v1All paths in the Customer API reference are relative to this base URL. API_BASE depends on your region. Refer to Base URLs.
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 in the reference shows its access level.
| 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.
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 |
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 this reference. Ignore them.
- In request bodies, send optional fields with the value
nullwhen you do not use them.
Lists
List endpoints return a full JSON array. Only GET /project uses pages.
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.
Store settings
Read these first. They tell your storefront what to offer and which rules to apply.
/operatorThe store settingsPublicGET/operator/logoThe store logoPublicGET/operator/processesProcesses, materials, and optionsPublicGET/operator/lead-timesLead timesPublicGET/operator/shipping-methodsShipping methodsCustomerGET/countriesCountries for addressesPublicGET/countries/{country}/jurisdictionsStates, provinces, or regionsCustomerRead the store settings
/operatorPublicReturns the settings of your store. Your storefront must apply some of them. Refer to Storefront rules.
| Field | Type | Meaning and what to do |
|---|---|---|
name | string | Your store name |
currency | string | Default currency |
acceptedCurrencies | string[] | Currencies that a customer can select. Send the selected one in price and order calls. |
country | string | Country of the store (ISO alpha-2) |
loginStage | BEFORE_PRICE | AFTER_PRICE | BEFORE_PRICE: ask for sign-in before the visitor uploads parts or sees prices. AFTER_PRICE: guests can upload and see prices; sign-in is necessary to order. Your storefront must apply this rule. |
loginMethod | EMAIL | PHONE | ANY | The sign-in identifier that the store prefers. New customers always sign up with an email address. |
paymentProvider | string | STRIPE, PAYPAL, PAYPAL_SINGLE_PARTY, RAZORPAY_SINGLE_PARTY, FLYWIRE, or NONE. NONE means no online payment. |
isPayByInvoiceEnabled | boolean | Offer "pay by invoice" |
isPayByPurchaseOrderEnabled | boolean | Offer "pay by purchase order" |
maximumFileSize | number | null | Maximum size of an uploaded part file, in megabytes. Check this in your storefront before the upload. |
termsOfServiceLink | string | null | Show this link where the customer uploads files and signs in |
landingPageMessage | string | null | A message from the manufacturer for the first page |
videoLink | string | null | A help video |
storefrontTheme | SYSTEM | LIGHT | DARK | The colour mode that the manufacturer prefers |
isTaxIDEnabled | boolean | Show a tax ID field on addresses |
isInvoiceDownloadEnabled | boolean | If false, the invoice PDF is not available (403) |
isCustomerLineItemDeletionEnabled | boolean | Customers can remove lines from a quote |
isOrientationConstraintEnabled | boolean | Offer "keep my part orientation" |
Store rules that are not in this response
These rules reach you through the price calls and the Auth API:
| Store rule | Where you see it |
|---|---|
| Minimum order amount | quote.topUp (an added amount) |
| Maximum order amount | purchasability.withinMaximumOrderValue |
| Manual price review, quote-only materials | purchasability.canBePurchased, isPriceReviewRequired, isMaterialPurchasable, isPostProcessingPurchasable |
| Approval of new customers | WAIT_FOR_APPROVAL from the Auth API |
Get the logo
/operator/logoPublicReturns the logo image of the store as bytes. 400 if the store has no logo.
List processes and materials
/operator/processesPublicReturns the configuration options: Process[].
type Process = {
id: string // UUID. This is the processPricesId.
technology: string // for example 'FDM', 'SLS', 'MJF', 'SLA', 'CNC', 'SHEET_METAL'
description: string | null
isDefault: boolean
materials: Material[]
infills: Infill[]
precisions: Precision[]
postProcessings: PostProcessing[]
bulkPricingQuantities: number[]
}
type Material = {
id: number
name: string
datasheetSummary: string | null
isDefault: boolean
quoteOnly: boolean // true: no instant purchase with this material
colors: Color[]
wallThicknessWarning: number | null
wallThicknessLimit: number | null
}
type Color = { id: number; name: string; code: string }
type Infill = { id: number; name: string; value: number; default: boolean }
type Precision = { id: number; name: string; price: number; isActive: boolean }
type PostProcessing = {
id: number
name: string
isDefault: boolean
purchasable: boolean // false: no instant purchase with this option
colors: Color[]
incompatibleMaterialIds: number[] // do not offer with these materials
mutuallyExclusiveGroup: string | null // offer one option only from each group
}If you send a customer token, the list can be specific to that customer's organisation.
List lead times
/operator/lead-timesPublictype LeadTime = { id: string; name: string; isDefault: boolean; isDeleted: boolean }Do not offer lead times that have isDeleted: true.
List shipping methods
/operator/shipping-methodsCustomertype ShippingMethod =
| { shippingMethodId: number; shippingMode: 'SELF_COLLECTION'; isDefault: boolean; name: string; enableContactInfoCollection: boolean }
| { shippingMethodId: number; shippingMode: 'FIXED_PRICE'; isDefault: boolean; name: string; price: number | null }
| { shippingMethodId: number; shippingMode: 'CARRIER_ACCOUNT'; isDefault: boolean; carrierAccountProvider: string }
| { shippingMethodId: number; shippingMode: 'CUSTOMER_ACCOUNT'; isDefault: boolean; name: string; countries: string[] }List countries
/countriesPublictype Country = { country: string; name: string; alpha2Code: string; alpha3Code: string }Use the country value in address calls.
List jurisdictions
/countries/{country}/jurisdictionsCustomerStates, provinces, or regions of a country. {country} is the country value from GET /countries.
type Jurisdiction = { country: string; name: string; iso: string }Errors
Error body
The standard error body:
{ "error": "CART_NOT_OPEN", "message": "Cart is not open" }Use error (a stable code) and the HTTP status in your logic. Validation errors can add a fields object.
Cases that you must handle
Always check the HTTP status first. Do not assume that a body is present.
| Case | Response |
|---|---|
| Missing, invalid, or expired token | 401, empty body |
| A guest token on a customer endpoint | 403, empty body |
X-Store-Name is missing or does not match the token | 401 or 403 |
| Some "not permitted" and "not found" cases | 400, 404, or 409 with an empty body |
| Cart item endpoints | { "error": "<text for a person>" } with no message field |
| Unexpected error | 500 { "error": "INTERNAL_ERROR", … } |
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 |
ORDER_WRONG_STATE | 409 |
REQUEST_VALIDATION_FAILED, REQUEST_BODY_UNREADABLE | 400 |
Last updated on