Customer API reference

<API_BASE>/api/customer/v1

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

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
}

type LeadTime = { id: string; name: string; isDefault: boolean; isDeleted: boolean }

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[] }

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

type Jurisdiction = { country: string; name: string; iso: string }

type AnalysisResult = {
  partRevisionId: string        // the ID for all later calls
  fileName: string
  versionNumber: number
  createdAt: string
  originalCadFileType: string
  availableAccessories: string[]

  width: number
  height: number
  length: number
  volume: number
  area: number
  convexHullVolume: number
  minBoundingBoxVolume: number
  shrinkWrapVolume: number
  minimumWallThickness: number | null
  watertight: boolean           // false: the part cannot be purchased instantly
  repaired: boolean             // the mesh was repaired automatically
  baseRotation: number[][]

  thumbnail: Uint8Array | null  // image bytes
  stl: Uint8Array               // gzip-compressed STL mesh, for a 3D viewer
  wallThickness: Uint8Array | null
  bending?: object | null       // sheet metal data
  machining?: object | null     // machining data
}

{ partRevisionId: string; units: MeasurementUnit; processPricesId: string; materialId: number }

type PartManufacturability = {
  partRevisionId: string
  limits: { withinBoundingBoxLimit: boolean; withinWallThicknessLimit: boolean }
  warnings: { hasOptimalWallThickness: boolean }
  values: { boundingBox: [number, number, number] | null; wallThicknessLimit: number | null; wallThicknessWarning: number | null }
}

type MeasurementUnit = 'MILLIMETERS' | 'CENTIMETERS' | 'METRES' | 'INCHES' | 'FEET'

type CreateOrder = {
  currency: string                                 // one of acceptedCurrencies
  requisitions: Record<string, CreateRequisition>  // key: a UUID that you select for each line
  shipping: CreateShipping | null
  shippingId: null
  billingAddressId: number | null
  discountId: number | null
  operatorNote: string | null                      // a note to the manufacturer
  affiliate: string | null
  cartId: string | null                            // POST /order only
  intent?: 'CHECKOUT'                              // POST /order only
}

type CreateRequisition = {
  sequence: number              // position of the line, from 0
  partRevisionId: string
  units: MeasurementUnit
  quantity: number
  processPricesId: string
  materialId: number
  infillId: number | null
  precisionId: number | null
  colorId: number | null
  leadTimeId: string | null
  postProcessingIds: number[]
  comments: { conversationType: 'REQUISITION_TAGGED'; message: string }[]
  constraints?: { constraintType: 'FIXED_ORIENTATION' }[]
  name: string | null
}

type CreateShipping =
  | { shippingMode: 'SELF_COLLECTION'; shippingMethodId: number; contactName?: string; contactPhoneNumber?: string }
  | { shippingMode: 'FIXED_PRICE'; shippingMethodId: number; rateId: string; toAddressId: number }
  | { shippingMode: 'CARRIER_ACCOUNT'; shippingMethodId: number; rateId: string; toAddressId: number }
  | { shippingMode: 'CUSTOMER_ACCOUNT'; shippingMethodId: number; toAddressId: number; accountNumber: string }

type PreOrder = {
  quote: Quote
  purchasability: Purchasability
  constraints: Record<string, object[]>
}

type Quote = {
  currency: string
  price: number                 // total
  subtotal: number
  shipping: number
  discount: number
  topUp: number | null          // amount added to reach the minimum order amount
  tax: {
    totalPrice: number
    totalPercentage: number
    components: { shortName: string; longName: string; percentage: number; amount: number }[]
    isTaxAppliedToShipping: boolean
    isTaxExempted: boolean
    isTaxReverseCharged: boolean
  }
  lineItems: { name: string; price: number }[]
  requisitions: Record<string, RequisitionQuote | null>   // null: no instant price for this line
  expectedDispatchDate: string | null
}

type RequisitionQuote = {
  partRevisionId: string
  quantity: number
  price: number
  unitPrice: number
  manufacturingPrice: number
  postProcessingPrice: number
  postProcessingOptions: { id: number; price: number }[]
}

type Purchasability = {
  canBePurchased: boolean       // false: offer "request a quote", not payment
  isPriceReviewRequired: boolean
  withinMaximumOrderValue: boolean
  withinBoundingBoxLimit: boolean
  withinWallThicknessLimit: boolean
  isMaterialPurchasable: boolean
  isPostProcessingPurchasable: boolean
  parts: Record<string, PartManufacturability>
}

type BulkQuote = { quantity: number; price: number; unitPrice: number; savingsPerUnit: number }

type Cart = {
  cartId: string
  status: 'OPEN' | 'DELETED' | 'CONVERTED'
  items: CartItem[]
  customerId: number | null     // null: a guest cart that is not claimed
  currency: string | null
  notes: string | null
  affiliate: string | null
  discountId: number | null
  billingAddressId: number | null
  toAddressId: number | null
  shippingMethodId: number | null
  rateId: string | null
  createdAt: string
  lastUpdated: string
}

type CartItem = {
  id: number                    // omit when you create an item
  partRevisionId: string
  name: string | null
  quantity: number
  units: MeasurementUnit | null
  processPricesId: string | null
  materialId: number | null
  colorId: number | null
  infillId: number | null
  precisionPricesId: number | null   // NOTE: "precisionId" in pre-order and order lines
  leadTimeId: string | null
  postProcessingIds: number[] | null
  useOriginalOrientation: boolean | null
  files: { id: number; fileName: string | null; contentType: string | null; size: number | null }[] | null
}

type Customer = {
  customerId: number
  email: string | null
  firstName: string | null
  lastName: string | null
  phoneNumber: string | null
  organisationName: string | null
  language: string
  notificationPreference: 'EMAIL' | 'SMS' | 'WHATSAPP'
  customerType: 'PRO_FORMA' | 'ACCOUNT' | 'INTERNAL'
  discountPercentage: number | null
}

type Address = {
  addressId: number             // omit when you create an address
  name: string                  // name of the contact person
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: string
  country: string               // the "country" value from GET /countries
  jurisdictionIsoCode: string   // the "iso" value from GET /countries/{country}/jurisdictions
  phone: string
  email: string
  residential: boolean
  taxId: string | null
  isBillingAddress: boolean
  isShippingAddress: boolean
  countryAlpha2Code: string     // response only
  countryAlpha3Code: string     // response only
}

// Request
{
  currency: string
  toAddressId: number
  parts: { partRevisionId: string; units: MeasurementUnit; quantity: number; processPricesId: string; materialId: number }[]
}

// Response
type ShippingRates = {
  shippingMethodId: number | null
  tooLargeForBoxes: boolean     // the parts do not fit the boxes of the manufacturer
  errorWithCarrier: boolean     // the carrier gave no rate
  rates: { id: string; rate: number; currency: string; serviceType: string; serviceName: string; shippingMethodId: number }[]
}[]

type Order = {
  id: number
  state: 'QUOTE' | 'ORDER'
  quoteNumber: string | null
  orderNumber: string | null    // set when the quote becomes an order
  price: number | null
  currency: string
  paymentStatus: 'UNPAID' | 'PROCESSING' | 'PAID' | 'REFUNDED' | 'EXTERNALLY_TRACKED'
  isReviewRequired: boolean
  isVoided: boolean
  isArchived: boolean
  operatorNote: string | null
  purchaseOrderNumber: string | null
  requisitionIds: number[]
  threadId: number              // for messages and files
  shipping: Shipping | null
  shipments: Shipment[]
  billingAddress: Address | null
  discount: { discountId: number; code: string | null; percentage: number } | null
  tax: object | null
  kanbanColumn: { id: string; name: string; color: string | null } | null   // production stage
  createdAt: string
  lastUpdated: string
}

type Requisition = {
  id: number
  orderId: number
  sequence: number
  name: string
  partRevisionId: string
  units: MeasurementUnit
  quantity: number
  processPricesId: string
  materialId: number
  colorId: number | null
  infillId: number | null
  precisionId: number | null
  leadTimeId: string | null
  postProcessingIds: number[]
  pricePaid: number | null
  watertight: boolean
}

type Shipment = {
  id: string
  type: 'COURIER' | 'COLLECTION'
  fulfilledAt: string
  destination: object
  parcels: object[]
  tracking?: { provider: string; providerService: string; trackingNumber: string; trackingUrl: string | null } | null
}

{ order: Order; requisitionMapping: Record<string, Requisition> }   // key: your line key

type Payment = {
  id: string
  provider: string              // the paymentProvider of the store
  finalPrice: number
  tax: number
  currency: string
  clientSecret?: string | null
  paymentPrincipal?: string | null
  merchantAccount?: string | null
  flywireGatewayUrl?: string | null
  stripePaymentIntentStatus?: string | null
}

{ "activityType": "CONVERSATION", "conversationType": "GENERIC", "threadId": 880, "message": "When will you ship?" }

type Page<T> = { content: T[]; totalElements: number; totalPages: number; pageNumber: number; pageSize: number; isEmpty: boolean; isFirst: boolean; isLast: boolean }