Get a specific SKU

GET /v1/skus/{id}

Requires: sku.view

Path Parameters

id required

string

The unique identifier of the SKU

Response Schema

SkuLinkedPartsWithPartRelation

createdAtrequired

string

format: date-time

customMetadataoptional

Record<string, any>

Construct a type with a set of properties K of type T

descriptionrequired

string

externalIdrequirednullable

string

externalProviderrequirednullable

"etsy" | "shopify"

etsyshopify

folderIdoptionalnullable

string

pattern: ^[a-z0-9]{24}$

idrequired

string

pattern: ^[a-z0-9]{24}$

linkedPartsrequired

object[]

createdAtrequired

string

format: date-time

exposedParametersrequired

string[]

extensionsoptionalnullable

object

3mfoptional

object

plateLabelsoptional

Record<string, string>

plateQuantitiesrequired

Record<string, number>

skipObjectsoptional

Record<string, string[]>

Construct a type with a set of properties K of type T

idrequired

string

pattern: ^[a-z0-9]{24}$

labelrequired

string

materialAssignmentsoptionalnullable

Record<string, object[]>

Construct a type with a set of properties K of type T

parameterBindingsoptionalnullable

Record<string, string>

Construct a type with a set of properties K of type T

parametersrequired

object[]

namerequired

string

typerequired

"number" | "string" | "boolean" | "file"

numberstringbooleanfile

valueoptional

number | string | boolean

partrequired

object

arrangeableoptional

boolean

createdAtrequired

string

format: date-time

customMetadataoptional

Record<string, any>

Construct a type with a set of properties K of type T

descriptionrequired

string

fileHashesrequired

string[]

min items: 1

fileUrisrequired

string[]

min items: 1

folderIdoptionalnullable

string

pattern: ^[a-z0-9]{24}$

gcodePlateUrisoptionalnullable

Record<string, string>

Construct a type with a set of properties K of type T

idrequired

string

pattern: ^[a-z0-9]{24}$

materialsrequirednullable

object[]

colorrequirednullable

string

pattern: ^#{0,1}[0-9A-F]{6}|[0-9A-F]{8}$

identifieroptionalnullable

string

indexrequired

number

min: 0

nameoptionalnullable

string

skipoptional

boolean

typerequirednullable

string

meshErroroptionalnullable

string

Why tessellating this source failed. Set with `meshUri` cleared, so a file that cannot be meshed is stated once instead of re-converting on every print forever. Replacing the source moves `fileHashes[0]` off this hash, which retires the error without anything having to clear it.

meshSourceHashoptionalnullable

string

`fileHashes[0]` of the source the mesh state describes — the file `meshUri` was tessellated from, or the one `meshError` failed on.

meshUrioptionalnullable

string

Tessellated mesh derived from a boundary-representation source (STEP). The slicer CLI only reads meshes, so this — not `fileUris[0]` — is what the print and estimation paths feed it.

metadataoptionalnullable

object

filamentColorsrequired

string[]

filamentDensitiesoptional

number[]

filamentDiametersoptional

number[]

filamentIdsoptional

string[]

filamentTyperequired

string[]

nozzleDiameterrequired

string

plateRenderSourceHashoptional

string

`fileHashes[0]` of the source that produced the plates' `thumbnailRenderedUri`. Re-extraction carries the renders forward only while this still matches the part's current source; a replaced file leaves them behind rather than showing the previous model's geometry.

platesoptional

object[]

filamentIdsoptional

string[]

filamentMapModeoptional

string

filamentMapsoptional

number[]

gcodeFileoptional

string

idrequired

number

lockedoptional

boolean

nameoptional

string

patternBboxFileoptional

string

pickDataoptional

string

pickFileoptional

string

pickUploadedUrioptional

string

slicedoptional

object

thumbnailDataoptional

string

thumbnailFileoptional

string

thumbnailNoLightFileoptional

string

thumbnailRenderedUrioptional

string

The plate re-rendered by the three.js builder. Written by a different flow, and to a different storage path, than the archive copy above — a later metadata reprocess re-copies the archive image and must not be able to overwrite this. Prefer it over `thumbnailUploadedUri` (see `plateThumbnailUri`).

thumbnailUploadedUrioptional

string

The archive's own plate preview, copied out at metadata-extraction time.

topDataoptional

string

Base64 PNG data for the top/pick images, staged before upload then cleared.

topFileoptional

string

topUploadedUrioptional

string

Uploaded URIs for the plate's top-down image and color-coded object pick mask. Used by the visual skip-objects picker.

printerModelrequired

string

profileCompatrequired

object

compatiblerequired

string[]

saferequired

string[]

slicedrequired

string

slicerVersionoptionalnullable

object

enginerequired

"orcaslicer" | "bambu-studio" | "prusaslicer" | "superslicer"

orcaslicerbambu-studioprusaslicersuperslicer

versionrequired

string

textSlotsoptional

object[]

PrintagoParam text slots with their per-plate occurrence identities, re-detected whenever the file is (re)processed. The saved reuse mode lives on the slot's parameter, which survives a file replacement; this is the geometry-derived half that must always track the current file.

fontNameoptional

string

`font_name` of the first volume seen with this key.

fontVersionoptional

string

`font_version` of the first volume seen with this key.

keyrequired

string

The matching volume/object name — the substitution key.

labelrequired

string

The label this slot's parameter is shown under.

occurrencesoptional

object[]

Every printable object instance carrying this slot, across all plates. Absent when the file predates occurrence detection or has no plate metadata to resolve instances against.

surfaceTypeoptional

number

`surface_type` of the first volume seen with this key (0=flat).

textrequired

string

The text authored into the volume. It prints as-is when the slot goes unfilled, which makes it the parameter's default.

volumeCountrequired

number

How many text volumes in the file carry this slot name.

namerequired

string

overriddenProcessProfileIdrequirednullable

string

pattern: ^[a-z0-9]{24}$

parametersrequired

object[]

acceptedContentTypesoptional

string[]

File-parameter-only fields (populated when `type === PartParameterVariableType.File`). Kept optional on the shared interface so scalar-parameter call sites do not need union-narrowing. See `FilePartParameter` for the strict shape. `acceptedContentTypes` is intentionally an OPEN `string[]` (not a narrow union). The customizer emits SVG, but Etsy attachments and direct API order ingestion can carry ANY mime type (PNG / JPG / PDF / AI / etc). Builders enforce kind constraints; the shared type stays open.

defaultoptional

number | string | boolean

defaultUrioptional

string

Optional fallback file URI (e.g. a known SVG in storage).

descriptionoptional

string

labeloptional

string

What the parameter is shown under wherever a customer or an operator fills it in; `name` stays the key everything binds by (SKU options, order inputs, build overrides, and — for a 3MF text slot — the text volume the substitution travels to). A parameter without one is shown under its name. This interface is the one the API's request validators are generated from, and it is a second declaration of the shape in `../part/parameter`. A field added to only one of them is accepted by the code and then pruned off the wire.

maxoptional

number

minoptional

number

multipleoptional

boolean

Whether the slot accepts >1 file. Reserved for forward compat — the Phase 5 resolver assumes single-file per slot for v1.

namerequired

string

optionsoptional

object[]

labeloptional

string

valuerequired

string | number

serialReuseoptional

"share" | "increment"

For a 3MF text-slot parameter bound to a sequence: whether occurrences repeated on one plate share a serial or each consume the next one. Absent means {@link TextSlotSerialReuse.Share }, today's duplicate-name meaning.

shareincrement

sizingoptional

"stretch" | "fit" | "unconstrained"

3MF text placeholders only: how a substituted value is sized against the bounds of the text volume it replaces. Absent means "fit within bounds", which is what every part declared before the setting existed carries. Declared on this shape as well as on `../part/parameter` for the reason `label` is — the API's request validators are generated from this one, and a field on only the other is pruned off the wire.

stretchfitunconstrained

stepoptional

number

typerequired

"number" | "string" | "boolean" | "file"

numberstringbooleanfile

valueoptional

number | string | boolean

printTagsrequired

object

filament.typeoptional

string

printer.idoptional

string

printer.modelNameoptional

string

printer.nozzleDiameteroptional

string

printer.provideroptional

string

user.tagsoptional

string

processingoptionalnullable

object

Per-stage ingest progress and, on failure, which stage stopped and why.

attemptrequired

number

How many ingests this part has had before this one — a monotonic per-part counter, not a per-file retry count, so no two runs can ever share a workflow key. See {@link nextPartIngestAttempt }.

erroroptional

string

failedStageoptional

"fetch" | "read-metadata" | "thumbnails" | "split-plates" | "estimate"

fetchread-metadatathumbnailssplit-platesestimate

fileHashrequired

string

`fileHashes[0]` this ingest describes; replacing the file retires it.

finishedAtoptional

string

stagesrequired

object[]

attemptsoptional

number

Times the stage has been started, so the UI can say "retrying · attempt N".

erroroptional

string

keyrequired

"fetch" | "read-metadata" | "thumbnails" | "split-plates" | "estimate"

fetchread-metadatathumbnailssplit-platesestimate

statusrequired

"running" | "done" | "pending" | "failed" | "skipped"

runningdonependingfailedskipped

startedAtrequired

string

workflowKeyrequired

string

The workflow run that owns this state. A retry or a file replacement writes a new key first, so a superseded run's writes no longer match and are dropped instead of clobbering the newer run's progress.

processingStatusoptionalnullable

"processing" | "failed"

Where the file's ingest (metadata extraction, thumbnails, plate split, estimation) stands. `null` means ready — parts that predate the ingest workflow are healthy without backfill. System-set, not user-editable.

processingfailed

slicerOverrideoptionalnullable

string

slicingEstimateoptionalnullable

object

estimatedPrintTimeSecondsrequired

number

materialsrequired

object[]

coloroptional

string

indexrequired

number

materialTyperequired

string

usedGramsrequired

number

usedMetersrequired

number

platesoptional

object[]

estimatedPrintTimeSecondsrequired

number

materialsrequired

object[]

plateIdrequired

number

totalWeightGramsrequired

number

profilesoptional

object

filamentProfileIdsrequired

string[]

filamentProfileNamesrequired

string[]

machineProfileIdrequired

string

machineProfileNamerequired

string

processProfileIdrequired

string

processProfileNamerequired

string

slicedAtrequired

string

slicerVersionrequired

string

totalWeightGramsrequired

number

sourceoptionalnullable

"google-drive" | "onedrive"

Which integration created this part. Set only by the cloud-storage providers today; null on every other creation path (upload, API, OpenSCAD, …) rather than carrying a synthetic "manual" value, so existing parts need no backfill. Not user-editable — it records what happened, not a preference.

google-driveonedrive

storeIdrequired

string

pattern: ^[a-z0-9]{24}$

thumbnailUrirequirednullable

string

typerequired

enum

scadcadquerybuild123dstlstep3mfgcode3mfgcode

updatedAtrequired

string

format: date-time

uploadedAtoptionalnullable

string

format: date-time

use3MFProcessProfileoptional

boolean

Slice this part with the process profile embedded in its 3MF rather than the matched printer's. Omit it when creating a 3MF part and it is turned on for you, unless you also send an `overriddenProcessProfileId`; send `false` to slice with the printer's profile instead. Ignored for every other part type.

userTagsoptional

string[]

max items: 10

partIdrequired

string

pattern: ^[a-z0-9]{24}$

plateQuantitiesBindingoptionalnullable

string

quantityrequired

number

min: 0max: 500

sequenceBindingsoptionalnullable

Record<string, string>

Construct a type with a set of properties K of type T

skuIdrequired

string

pattern: ^[a-z0-9]{24}$

storeIdrequired

string

pattern: ^[a-z0-9]{24}$

updatedAtrequired

string

format: date-time

skurequired

string

storeIdrequired

string

pattern: ^[a-z0-9]{24}$

titlerequired

string

totalCogsrequired

number

updatedAtrequired

string

format: date-time

Example Response

200 OK — application/json

{
  "sku": "string",
  "title": "string",
  "description": "string",
  "externalId": "string",
  "externalProvider": "etsy",
  "folderId": "string",
  "totalCogs": 1,
  "customMetadata": {},
  "id": "string",
  "storeId": "string",
  "createdAt": "2025-01-15T12:00:00.000Z",
  "updatedAt": "2025-01-15T12:00:00.000Z",
  "linkedParts": [
    {
      "skuId": "string",
      "partId": "string",
      "parameters": [
        {
          "name": "string",
          "type": "number",
          "value": 1
        }
      ],
      "quantity": 0,
      "label": "string",
      "exposedParameters": [
        "string"
      ],
      "materialAssignments": {},
      "extensions": {
        "3mf": {
          "skipObjects": {},
          "plateQuantities": {},
          "plateLabels": {}
        }
      },
      "parameterBindings": {},
      "sequenceBindings": {},
      "plateQuantitiesBinding": "string",
      "id": "string",
      "storeId": "string",
      "createdAt": "2025-01-15T12:00:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z",
      "part": {
        "name": "string",
        "type": "scad",
        "description": "string",
        "fileUris": [
          "string"
        ],
        "fileHashes": [
          "string"
        ],
        "thumbnailUri": "string",
        "parameters": [
          {
            "default": 1,
            "options": [
              {
                "value": "string",
                "label": "string"
              }
            ],
            "description": "string",
            "min": 1,
            "max": 1,
            "step": 1,
            "acceptedContentTypes": [
              "string"
            ],
            "multiple": true,
            "defaultUri": "string",
            "label": "string",
            "serialReuse": "share",
            "sizing": "stretch",
            "name": "string",
            "type": "number",
            "value": 1
          }
        ],
        "printTags": {
          "printer.provider": "string",
          "printer.id": "string",
          "printer.nozzleDiameter": "string",
          "printer.modelName": "string",
          "filament.type": "string",
          "user.tags": "string"
        },
        "overriddenProcessProfileId": "string",
        "folderId": "string",
        "materials": [
          {
            "index": 0,
            "color": "string",
            "type": "string",
            "skip": true,
            "name": "string",
            "identifier": "string"
          }
        ],
        "slicerOverride": "string",
        "metadata": {
          "printerModel": "string",
          "filamentType": [
            "string"
          ],
          "filamentColors": [
            "string"
          ],
          "filamentDensities": [
            1
          ],
          "filamentDiameters": [
            1
          ],
          "nozzleDiameter": "string",
          "profileCompat": {
            "sliced": "string",
            "compatible": [
              "string"
            ],
            "safe": [
              "string"
            ]
          },
          "slicerVersion": {
            "engine": "orcaslicer",
            "version": "string"
          },
          "plates": [
            {
              "id": 1,
              "name": "string",
              "locked": true,
              "filamentMapMode": "string",
              "filamentMaps": [
                1
              ],
              "gcodeFile": "string",
              "thumbnailFile": "string",
              "thumbnailUploadedUri": "string",
              "thumbnailRenderedUri": "string",
              "thumbnailNoLightFile": "string",
              "thumbnailData": "string",
              "topFile": "string",
              "pickFile": "string",
              "topData": "string",
              "pickData": "string",
              "topUploadedUri": "string",
              "pickUploadedUri": "string",
              "patternBboxFile": "string",
              "sliced": {
                "index": 1,
                "extruderType": "string",
                "nozzleVolumeType": "string",
                "printerModelId": "string",
                "nozzleDiameters": "string",
                "timelapseType": "string",
                "prediction": 1,
                "weight": 1,
                "outside": true,
                "supportUsed": true,
                "labelObjectEnabled": true,
                "filamentMaps": "string",
                "objects": [
                  {}
                ],
                "filaments": [
                  {}
                ],
                "warnings": [
                  {}
                ],
                "layerFilamentLists": [
                  {}
                ]
              },
              "filamentIds": [
                "string"
              ]
            }
          ],
          "filamentIds": [
            "string"
          ],
          "textSlots": [
            {
              "key": "string",
              "label": "string",
              "text": "string",
              "volumeCount": 1,
              "fontName": "string",
              "fontVersion": "string",
              "surfaceType": 1,
              "occurrences": [
                {
                  "plateId": 1,
                  "objectId": "string",
                  "instanceId": 1,
                  "identifyId": "string"
                }
              ]
            }
          ],
          "plateRenderSourceHash": "string"
        },
        "slicingEstimate": {
          "estimatedPrintTimeSeconds": 1,
          "materials": [
            {
              "index": 1,
              "usedGrams": 1,
              "usedMeters": 1,
              "materialType": "string",
              "color": "string"
            }
          ],
          "totalWeightGrams": 1,
          "profiles": {
            "machineProfileId": "string",
            "machineProfileName": "string",
            "processProfileId": "string",
            "processProfileName": "string",
            "filamentProfileIds": [
              "string"
            ],
            "filamentProfileNames": [
              "string"
            ]
          },
          "slicedAt": "string",
          "slicerVersion": "string",
          "plates": [
            {
              "plateId": 1,
              "estimatedPrintTimeSeconds": 1,
              "materials": [
                {
                  "index": 1,
                  "usedGrams": 1,
                  "usedMeters": 1,
                  "materialType": "string",
                  "color": "string"
                }
              ],
              "totalWeightGrams": 1
            }
          ]
        },
        "use3MFProcessProfile": true,
        "arrangeable": true,
        "userTags": [
          "string"
        ],
        "gcodePlateUris": {},
        "meshUri": "string",
        "meshSourceHash": "string",
        "meshError": "string",
        "uploadedAt": "2025-01-15T12:00:00.000Z",
        "customMetadata": {},
        "source": "google-drive",
        "processingStatus": "processing",
        "processing": {
          "workflowKey": "string",
          "fileHash": "string",
          "attempt": 1,
          "startedAt": "string",
          "finishedAt": "string",
          "failedStage": "fetch",
          "error": "string",
          "stages": [
            {
              "key": "fetch",
              "status": "running",
              "attempts": 1,
              "error": "string"
            }
          ]
        },
        "id": "string",
        "storeId": "string",
        "createdAt": "2025-01-15T12:00:00.000Z",
        "updatedAt": "2025-01-15T12:00:00.000Z"
      }
    }
  ]
}