Custom Storefronts

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.

PageContents
This pageConventions, store settings, and errors
API: parts, carts, and pricesPart upload and analysis, manufacturability, carts, pre-order prices, bulk prices, discount codes
API: customers and ordersCustomer profile, addresses, shipping rates, orders, payment, documents, messages, projects, catalog

Base URL

<API_BASE>/api/customer/v1

All paths in the Customer API reference are relative to this base URL. API_BASE depends on your region. Refer to Base URLs.

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 in the reference shows its access level.

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.

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

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 null when 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.

Read the store settings

GET/operatorPublic

Returns the settings of your store. Your storefront must apply some of them. Refer to Storefront rules.

FieldTypeMeaning and what to do
namestringYour store name
currencystringDefault currency
acceptedCurrenciesstring[]Currencies that a customer can select. Send the selected one in price and order calls.
countrystringCountry of the store (ISO alpha-2)
loginStageBEFORE_PRICE | AFTER_PRICEBEFORE_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.
loginMethodEMAIL | PHONE | ANYThe sign-in identifier that the store prefers. New customers always sign up with an email address.
paymentProviderstringSTRIPE, PAYPAL, PAYPAL_SINGLE_PARTY, RAZORPAY_SINGLE_PARTY, FLYWIRE, or NONE. NONE means no online payment.
isPayByInvoiceEnabledbooleanOffer "pay by invoice"
isPayByPurchaseOrderEnabledbooleanOffer "pay by purchase order"
maximumFileSizenumber | nullMaximum size of an uploaded part file, in megabytes. Check this in your storefront before the upload.
termsOfServiceLinkstring | nullShow this link where the customer uploads files and signs in
landingPageMessagestring | nullA message from the manufacturer for the first page
videoLinkstring | nullA help video
storefrontThemeSYSTEM | LIGHT | DARKThe colour mode that the manufacturer prefers
isTaxIDEnabledbooleanShow a tax ID field on addresses
isInvoiceDownloadEnabledbooleanIf false, the invoice PDF is not available (403)
isCustomerLineItemDeletionEnabledbooleanCustomers can remove lines from a quote
isOrientationConstraintEnabledbooleanOffer "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 ruleWhere you see it
Minimum order amountquote.topUp (an added amount)
Maximum order amountpurchasability.withinMaximumOrderValue
Manual price review, quote-only materialspurchasability.canBePurchased, isPriceReviewRequired, isMaterialPurchasable, isPostProcessingPurchasable
Approval of new customersWAIT_FOR_APPROVAL from the Auth API
GET/operator/logoPublic

Returns the logo image of the store as bytes. 400 if the store has no logo.

List processes and materials

GET/operator/processesPublic

Returns 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

GET/operator/lead-timesPublic
type LeadTime = { id: string; name: string; isDefault: boolean; isDeleted: boolean }

Do not offer lead times that have isDeleted: true.

List shipping methods

GET/operator/shipping-methodsCustomer
type 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

GET/countriesPublic
type Country = { country: string; name: string; alpha2Code: string; alpha3Code: string }

Use the country value in address calls.

List jurisdictions

GET/countries/{country}/jurisdictionsCustomer

States, 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.

CaseResponse
Missing, invalid, or expired token401, empty body
A guest token on a customer endpoint403, empty body
X-Store-Name is missing or does not match the token401 or 403
Some "not permitted" and "not found" cases400, 404, or 409 with an empty body
Cart item endpoints{ "error": "<text for a person>" } with no message field
Unexpected error500 { "error": "INTERNAL_ERROR", … }

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
ORDER_WRONG_STATE409
REQUEST_VALIDATION_FAILED, REQUEST_BODY_UNREADABLE400

Last updated on

On this page