Orders
An order is a customer's checkout: who placed it, how it ships, and one line item per
quoted part. You post the line items with their prices, and the server computes every
total from them, so the stored order always adds up. The order you read back from
GET /v1/order/{order_id} is the same object every webhook
delivers in data. Orders are a paid-plan feature (Pro and Max).
Prerequisites
- A
widget_idwith ordering turned on. Orders are placed against a widget, which supplies the currency, the shipping cost, the priority scope, and the discount rules. - A
quote_idfor each part. See Creating Quotes. - Your API token in the
Authorization: Bearer ...header. Creating or updating needs theorders:writepermission and reading needsorders:read(see Token Permissions).
Place an order
POST /v1/order takes the customer, the delivery choice, and at least one line item.
widget_id, customer_name, customer_email, deadline (a YYYY-MM-DD date),
shipping_selected, and line_items are required. shipping_address is required
when shipping_selected is true and must be omitted when it is false (pickup).
The response is a short acknowledgment: order_id, custom_order_id (or null),
created_at, user_id, and status: "success". Every new order starts in status
new, and order.created fires to your subscribed webhook endpoints.
Optional fields on the request:
customer_phone,notes: free text, stored as sent.discount_code: one of the widget's discount codes. An unknown code is a400.notification_email: sends the new-order email here instead of the widget's configured address, for this order only.base_price_application: how each line'sbase_priceis charged, one value for the whole order. Defaults toper_item. See How totals are computed.
Errors you can get back:
403Ordering is disabledwhen the widget is disabled or has ordering off.404when the widget does not exist on your account.422when a line item's quote was sliced with different settings than the preset it names inprint_settings.print_settings_id(infill density, perimeters, top/bottom layers, or supports), so you never sell a part priced at one setting and printed at another. Quote with the same preset you order with.
The order object
GET /v1/order/{order_id} returns one order, and GET /v1/order lists them newest
first (filter with status, cap with limit, default 50, max 200). Both return
this shape, and so does every webhook's data:
Code
Order fields
order_id(string): the Cloud Slicer ID. Every order API call and webhook keys on this.custom_order_id(string ornull): your human-facing order number ({prefix}{n}), assigned at create time only if custom order IDs are enabled in order settings. It is a label; the API never accepts it in place oforder_id.status(string):new,in_progress,printing,completed, orcancelled.priority_scope(string):per_orderorper_item, from the widget at create time. It decides how priority surcharges are charged.priority(string ornull): computed, never set by you. Underper_orderit is the name of the priority whose surcharge is charged (the line with the highest surcharge, the first one on a tie). Underper_itemit isnull, because each line is charged its own priority. Apriorityyou send is ignored.base_price_application(string):per_item,per_line_item,per_order, orminimum_spend. Fixed when the order is created; repricing never changes it.currency(string): the widget's currency, for exampleUSD.subtotal,order_base_fee,order_priority_surcharge,discount_amount,shipping_cost,total(numbers): all computed. See How totals are computed.shipping_address(object ornull):nullunlessshipping_selectedistrue.company,address_line2,state_region, andpostal_codeare nullable.deadline(string): the date the customer needs the order by,YYYY-MM-DD.
Line item fields
Each line item groups related fields into objects. On input, only file_name,
quantity (at least 1), material.color, and priority.name are required;
everything else is optional.
quote_id(string ornull): the quote this line was priced from.status(string): the line's own status, same values as the order's. Setting the order tocompletedmarks every linecompleted.file_name(string): the name shown to the customer and on the order.quantity(integer): copies to print. Every price on the line is per unit, and every quote is sliced for one copy.files:file_id,file_path(the stored model),gcode_path, andgcode_name(the sliced G-code), for downloads.material:filament_id,filament_name,filament_type, and the customer'scolor(required) andcolor_name.print_settings: the preset the part was quoted with (print_settings_id,print_settings_name) and the customer's quality choice (quality_name,layer_heightin mm). Quality has no surcharge; it is recorded so you print at the layer height that was quoted.priority: the turnaround the customer chose,name(required) andsurcharge(per unit, default0).addons(array): add-ons the customer selected, copied onto the order so its totals survive later catalog edits. Each hasid,name,addon_type(amountorpercentage),number, andnote. Extra keys you attach are kept.dimensions(object ornull): the part's bounding box,x,y,zin mm.estimate: slicer estimates for one unit,filament_weight_gandprint_time_seconds.pricing:base_price(the flat fee) andunit_price(the per-unit print cost, excluding the fee) are inputs.addons_total,priority_total, andline_totalare computed by the server, and any value you send for them is ignored.
A line item with quote_id but no price at all (base_price and unit_price both
0 or omitted) is priced from its stored quote, so a client that posts only the
quote still gets a correct total.
How totals are computed
The server reprices the whole order on every create and on any update that changes
line_items or shipping_selected, so the totals always follow from the line items.
Every figure is rounded half-up to two decimals.
For each line:
- Part cost depends on
base_price_application:per_item:(base_price + unit_price) × quantity. The fee is charged on every unit.per_line_item:base_price + unit_price × quantity. The fee is charged once per line.per_orderandminimum_spend:unit_price × quantity. The fee moves to the order level (below).
addons_total: anamountadd-on chargesnumber × quantity; apercentageadd-on chargesnumber% of the part cost.priority_total:surcharge × quantityunder aper_itempriority scope, else0.line_total= part cost +addons_total+priority_total.
Then for the order:
order_base_fee: underper_order, the highestbase_priceamong the lines, charged once. Underminimum_spend, that base price is a floor: only the shortfall between it and the sum of the line totals is charged. Otherwise0.order_priority_surcharge: under aper_orderpriority scope, the highest line surcharge, charged once. Otherwise0.subtotal= sum ofline_total+order_base_fee+order_priority_surcharge, give or take a cent (it rounds the unrounded sum).discount_amount: the larger of the widget's discount rules and the discount code, capped atsubtotal.shipping_cost: the widget's shipping cost whenshipping_selectedistrue, else0.total=subtotal - discount_amount + shipping_cost. There is no tax field.
In the example above, the brackets are (2.00 + 3.50) × 4 = 22.00 plus a 1.00 × 4
sanding add-on, a line_total of 26.00; the lid is (2.00 + 12.25) × 1 = 14.25.
The priority scope is per_order, so the Rush surcharge of 10.00 is charged once as
order_priority_surcharge, and priority is "Rush". The subtotal is
26.00 + 14.25 + 10.00 = 50.25, and with 8.00 shipping the total is 58.25.
Update an order
PATCH /v1/order/{order_id} changes an order. Every field is optional, but send at
least one: status, notes, deadline, shipping_selected, shipping_address,
line_items. order_id must be the Cloud Slicer ID, not custom_order_id.
- Any status can move to any other; there are no blocked transitions.
line_itemsreplaces the whole list and takes the same shape as on create.- Sending
line_itemsorshipping_selectedreprices the order. The repricing uses the widget's discount rules but does not re-apply a discount code.
The response is a short acknowledgment (order_id, updated_at), not the updated
order. Call GET /v1/order/{order_id} for the recomputed record, or read it from the
order.updated webhook that every update fires.
Delete an order
DELETE /v1/order/{order_id} removes the order and fires order.deleted with its last
known state. It needs the orders:delete permission.
Deleting cannot be undone. To stop work on an order but keep its record, set its
status to cancelled instead.