/v2/builds/preview
Preview part builds and jobs (dry run)
Dry run for POST /v2/builds. Send the same body and get back the part builds and print jobs that request would create, without creating or queueing anything.
Use it to show a confirmation screen, check how plate quantities and SKU quantities multiply out, or catch a bad request before it touches the queue. Each previewed part build lists its jobs in queue order with the label each job will carry, its plate (for 3MF and GCODE 3MF parts) and its position within the build (quantityIndex of quantityTotal). summary gives the totals.
SKU options, linked part overrides and variant bindings are resolved exactly as a real build resolves them, so materials and plateQuantities show the values the build would use.
The preview applies the same checks as a real build for unknown part and SKU IDs, unknown option names, and parts whose file processing has not finished or has failed (all 400). It does not validate material assignments against your material library, so a request that previews cleanly can still be rejected by POST /v2/builds for an invalid material.
Request Body
- Build configuration specifying parts and SKUs to preview
Individual parts to print. Each entry becomes one part build. Get part IDs from GET /v1/parts.
Pack this build's copies onto shared plates instead of printing one copy per job. Off unless enabled is true. partSpacingMm and plateMarginMm override your store's spacing settings for this build, and bedSize sets the target plate (defaults to the smallest bed among your printers).
Label shown on the print jobs in the queue. Defaults to the part name. For 3MF and GCODE 3MF parts, the plate name is appended.
Material to use per filament channel, keyed by the channel index from the part's materials[].index (0 for a single-material part). Each value is a list of material specs in order of preference, each one of { "variantId": ... } (an exact material and color), { "materialId": ... }, { "groupId": ... } or { "materialType": "PLA" }. Channels you leave out keep the part's own material assignments.
Parameter overrides for parametric parts, as { "name": value } pairs. Names match the part's parameters[].name.
ID of the part to print, from GET /v1/parts. The part must have finished file processing (processingStatus is null).
3MF and GCODE 3MF parts only. Per-plate label overrides keyed by plate ID. A job for that plate is labeled <label> - <plateLabels[plateId]> instead of using the plate name from the file.
3MF and GCODE 3MF parts only. Copies to print per plate, keyed by plate ID (for example { "1": 2, "3": 1 }). Only the listed plates are printed, and quantity is ignored. Plate IDs are in the part's metadata.plates.
Where the new jobs go within their priority tier: "back" (default) or "front".
100 (normal, the default) or 1000 (low). Normal-priority jobs are printed before low-priority ones.
Number of copies, 0 to 500, default 1. For a 3MF or GCODE 3MF part, every plate in the file is printed this many times. Ignored when plateQuantities is set.
Bambu printers only. Objects to skip per plate, keyed by plate ID, as lists of identifyId strings from metadata.plates[].sliced.objects[]. The print starts normally and the listed objects are skipped once the printer reports it has started.
Printer-matching tags added to the job's required printer tags. Jobs only go to printers whose tags satisfy them.
SKUs (products) to print. Identify each one by skuId or by its SKU code in sku. Each entry can also set quantity (complete units, 1 to 500, default 1), options (variant selections as { "name": "Color", "value": "Red" } or { "id": "<optionId>", "value": "Red" }; the value can be a value name or a value ID), linkedPartConfigs (overrides keyed by linked part ID, accepting the same quantity, parameters, label, tags, plateQuantities, plateLabels, skipObjects and materials fields as a part entry), priority, position, consolidation and tags. Every linked part of the SKU gets its own part build.
Example Request
{
"parts": [
{
"partId": "string",
"priority": 100,
"position": "front",
"consolidation": {
"enabled": true,
"partSpacingMm": 1,
"plateMarginMm": 1,
"bedSize": {
"x": 1,
"y": 1,
"z": 1
}
},
"quantity": 0,
"parameters": {},
"label": "string",
"tags": {
"printer.provider": "string",
"printer.id": "string",
"printer.nozzleDiameter": "string",
"printer.modelName": "string",
"filament.type": "string",
"user.tags": "string"
},
"plateQuantities": {},
"plateLabels": {},
"materials": {},
"skipObjects": {}
}
],
"skus": [
{
"skuId": "string",
"quantity": 1,
"linkedPartConfigs": {},
"tags": {
"printer.provider": "string",
"printer.id": "string",
"printer.nozzleDiameter": "string",
"printer.modelName": "string",
"filament.type": "string",
"user.tags": "string"
},
"priority": 100,
"position": "front",
"consolidation": {
"enabled": true,
"partSpacingMm": 1,
"plateMarginMm": 1,
"bedSize": {
"x": 1,
"y": 1,
"z": 1
}
},
"skuInstanceStart": 1,
"order": {
"orderId": "string",
"orderItemId": "string"
},
"options": [
{
"id": "string",
"value": "string"
}
]
}
]
}
Examples
Preview a multi-plate 3MF
A 3MF part with two plates, printed twice, becomes four jobs.
{
"parts": [
{
"partId": "d4n7c2v8b1x5z9m3q6w0e4r8",
"quantity": 2
}
]
}
{
"partBuilds": [
{
"source": "part",
"partId": "d4n7c2v8b1x5z9m3q6w0e4r8",
"partName": "Desk Organizer",
"partThumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/d4n7c2v8b1x5z9m3q6w0e4r8/thumbnail.png",
"label": "Desk Organizer",
"quantity": 2,
"sku": null,
"materials": null,
"plateQuantities": {
"1": 2,
"2": 2
},
"jobs": [
{
"label": "Desk Organizer - Base",
"quantityIndex": 1,
"quantityTotal": 4,
"plateId": "1",
"plateName": "Base",
"thumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/d4n7c2v8b1x5z9m3q6w0e4r8/plates/render-plate-1.png"
},
{
"label": "Desk Organizer - Base",
"quantityIndex": 2,
"quantityTotal": 4,
"plateId": "1",
"plateName": "Base",
"thumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/d4n7c2v8b1x5z9m3q6w0e4r8/plates/render-plate-1.png"
},
{
"label": "Desk Organizer - Drawers",
"quantityIndex": 3,
"quantityTotal": 4,
"plateId": "2",
"plateName": "Drawers",
"thumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/d4n7c2v8b1x5z9m3q6w0e4r8/plates/render-plate-2.png"
},
{
"label": "Desk Organizer - Drawers",
"quantityIndex": 4,
"quantityTotal": 4,
"plateId": "2",
"plateName": "Drawers",
"thumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/d4n7c2v8b1x5z9m3q6w0e4r8/plates/render-plate-2.png"
}
]
}
],
"summary": {
"partBuildCount": 1,
"skuBuildCount": 0,
"jobCount": 4
}
}
Preview a SKU with a variant selection
The material bound to the selected Color value appears in materials.
{
"skus": [
{
"sku": "BENCHY",
"quantity": 2,
"options": [
{
"name": "Color",
"value": "Red"
}
]
}
]
}
{
"partBuilds": [
{
"source": "sku",
"partId": "p8f2k6m1q9w3e7r5t0y4u2i6",
"partName": "Benchy",
"partThumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/p8f2k6m1q9w3e7r5t0y4u2i6/thumbnail.png",
"label": "Benchy",
"quantity": 2,
"sku": {
"skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
"sku": "BENCHY"
},
"materials": {
"0": [
{
"variantId": "m6a0t4v8a2r5i9a3n7t1j2w4"
}
]
},
"plateQuantities": null,
"jobs": [
{
"label": "Benchy",
"quantityIndex": 1,
"quantityTotal": 2,
"thumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/p8f2k6m1q9w3e7r5t0y4u2i6/thumbnail.png"
},
{
"label": "Benchy",
"quantityIndex": 2,
"quantityTotal": 2,
"thumbnailUri": "k3m9x2p7q8r4t6v1w5y0z3a2/parts/p8f2k6m1q9w3e7r5t0y4u2i6/thumbnail.png"
}
]
}
],
"summary": {
"partBuildCount": 1,
"skuBuildCount": 1,
"jobCount": 2
}
}
Response Schema
One entry per part build the request would create. Direct parts come first (source: "part"), followed by the linked parts of each SKU (source: "sku").
The print jobs this part build would create, in queue order. For 3MF and GCODE 3MF parts, jobs are grouped by plate in ascending plate ID, and plates with a quantity of 0 produce no jobs.
Total number of print jobs across all part builds.
Example Response
{
"partBuilds": [
{
"source": "sku",
"partId": "string",
"partName": "string",
"partThumbnailUri": "string",
"label": "string",
"quantity": 1,
"sku": {
"skuId": "string",
"sku": "string"
},
"materials": {},
"plateQuantities": {},
"jobs": [
{
"label": "string",
"quantityIndex": 1,
"quantityTotal": 1,
"plateId": "string",
"plateName": "string",
"thumbnailUri": "string"
}
]
}
],
"summary": {
"partBuildCount": 1,
"skuBuildCount": 1,
"jobCount": 1
}
}