DevelopersAPI reference

Designs API

REST endpoints for designs in SKUFlow: 8 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.skuflow.ai/api. Every call needs Authorization: Bearer skf_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

OperationEndpointRisk
List designsGET /organizations/{organizationId}/designsread
Create a designPOST /organizations/{organizationId}/designswrite
Get a designGET /organizations/{organizationId}/designs/{designId}read
Update a designPATCH /organizations/{organizationId}/designs/{designId}write
Delete a designDELETE /organizations/{organizationId}/designs/{designId}sensitive
Duplicate a designPOST /organizations/{organizationId}/designs/{designId}/duplicatewrite
Render the design's mockupsPOST /organizations/{organizationId}/designs/{designId}/mockupswrite
Price a design at quantitiesGET /organizations/{organizationId}/designs/{designId}/priceread

List designs

GET /organizations/{organizationId}/designs

Designs (a product with artwork placed on it), newest first, with the first mockup: filter by product or customer (with includeShared, that customer's and the business's own), search by name. Read-only.

Permissiondecoration.read (Owner, Admin, Staff, Member)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP tooldesigns_list (toolset decoration)

Parameters

NameInTypeRequiredDescription
productIdquerystringNo
customerIdquerystringNo
includeSharedqueryboolean or enumNoWith customerId: also the business's own designs (no customer), e.g. to choose one for that customer's quote.
queryquerystringNoFree-text search over the list's names, numbers and contact details. Up to 200 characters.
limitqueryintegerNoPage size, 1–200. Default 50.
offsetqueryintegerNoRows to skip; the answer's total counts every match. Default 0.

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
itemsarray of object
items[].idstring
items[].namestring
items[].productIdstring
items[].productobject
items[].product.idstring
items[].product.namestring
items[].product.kindstring
items[].customerobject or null
items[].customer.idstring
items[].customer.namestring
items[].placementCountinteger
items[].mockupobject or null
items[].mockup.viewenumOne of FRONT, BACK, SIDE, DETAIL, OTHER.
items[].mockup.colorNamestring or null
items[].mockup.widthPxinteger
items[].mockup.heightPxinteger
items[].mockup.urlstring or nullThe flattened PNG (signed, 1 hour).
items[].mockupsStaleboolean
items[].updatedAtstring (date-time)
totalinteger

Create a design

POST /organizations/{organizationId}/designs

A product (GET /products) decorated: the colours, and placements (an area key from the product's decoration areas, a method, artwork version layers, print size, ink colours / stitch count / size band). Art can be added later. Then render the mockups (POST /designs/{designId}/mockups) and put it on a quote line (product.designId).

Permissiondesigns.manage (Owner, Admin, Staff)
Riskwrite, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it.
MCP tooldesigns_create (toolset decoration)

Request body

FieldTypeRequiredDescription
customerIdstring or nullNoWhose design (their library); null = the business's own.
namestring or nullNoUp to 200 characters.
colorNamesarray of stringNoProduct colours it is shown and ordered in (variant colorName). Up to 30 items.
notesstring or nullNoUp to 5000 characters.
largeFormatobject or nullNoLarge format: size in inches, FIT / FILL / STRETCH, bleed, safe area, background, double-sided, grommets.
largeFormat.widthInnumberNoAt most 10000.
largeFormat.heightInnumberNoAt most 10000.
largeFormat.fitenumNoFit: the whole image inside; FILL: cover the piece (cropped); STRETCH: distorted to fill. One of FIT, FILL, STRETCH. Default FILL.
largeFormat.bleedInnumberNo0–12. Default 0.125.
largeFormat.safeInnumberNo0–24. Default 1.
largeFormat.backgroundstringNoDefault #ffffff.
largeFormat.doubleSidedbooleanNoDefault false.
largeFormat.grommetSpacingInnumber or nullNoAt most 120.
largeFormat.grommetEdgesenumNoOne of ALL, TOP_BOTTOM, LEFT_RIGHT, TOP. Default ALL.
placementsarray of objectNoReplaces every placement when given. Up to 20 items.
placements[].areaKeystringYesOne of the product's decoration areas (GET /products/{productId} decorationAreas). Up to 60 characters.
placements[].areaNamestring or nullNoUp to 120 characters.
placements[].viewenum or nullNoDefault: the area's view. One of FRONT, BACK, SIDE, DETAIL, OTHER.
placements[].methodIdstring or nullNoThe decoration method (GET /decoration-methods).
placements[].xnumber or nullNoThe print area on the view's picture, 0–1. -1–2.
placements[].ynumber or nullNo-1–2.
placements[].widthnumber or nullNoAt most 3.
placements[].heightnumber or nullNoAt most 3.
placements[].inkColorsinteger or nullNoInk colours (COLORS tables). 1–30.
placements[].stitchCountinteger or nullNoStitches (STITCHES tables). 0–1000000.
placements[].sizeBandKeystring or nullNoA size band column key (SIZE_BAND). Up to 40 characters.
placements[].printWidthInnumber or nullNoAt most 10000.
placements[].printHeightInnumber or nullNoAt most 10000.
placements[].optionsobject or nullNo
placements[].options.underbaseboolean or nullNoForce the white underbase on (true) or off (false); default: on dark colours.
placements[].options.puffboolean or nullNoEmbroidery 3D puff.
placements[].options.alreadyDigitizedboolean or nullNoThe embroidery file exists (a reorder): no digitizing fee.
placements[].options.artServiceboolean or nullNoAsk for the art fee (redraw, clean-up).
placements[].options.doubleSidedboolean or nullNoLarge format: print both sides.
placements[].options.setupWaivedboolean or nullNoScreens or set-up already paid (a reorder).
placements[].layersarray of objectNoArtwork on the picture: artwork versions with position, size and rotation as fractions. Up to 12 items.
placements[].layers[].kindenumNoOne of ARTWORK, TEXT, CLIPART. Default ARTWORK.
placements[].layers[].artworkVersionIdstringNoARTWORK layers: GET /artwork/{artworkId} versions. Up to 64 characters.
placements[].layers[].textstringNoTEXT layers: one line. Up to 120 characters.
placements[].layers[].fontenumNoTEXT layers (default sans). One of sans, sans-bold, serif, serif-bold, mono.
placements[].layers[].colorstringNoTEXT and CLIPART layers: the ink colour (#rrggbb).
placements[].layers[].clipartKeystringNoCLIPART layers: a key of the clipart library (GET /public/studio/…). Up to 40 characters.
placements[].layers[].xnumberYesLeft edge, as a fraction of the picture's width. -1–2.
placements[].layers[].ynumberYesTop edge, as a fraction of the picture's height. -1–2.
placements[].layers[].widthnumberYesAt most 3.
placements[].layers[].heightnumberYesAt most 3.
placements[].layers[].rotationnumberNo-360–360. Default 0.
productIdstringYesThe product (GET /products).

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"productId":"product_id"}'

Response

201: the answer's fields
FieldTypeDescription
idstring
productIdstring
customerIdstring or null
customerobject or null
customer.idstring
customer.namestring
namestring
colorNamesarray of string
notesstring or null
revisionintegerBumped on every change; proofs show a revision.
mockupsarray of object
mockups[].viewenumOne of FRONT, BACK, SIDE, DETAIL, OTHER.
mockups[].colorNamestring or null
mockups[].widthPxinteger
mockups[].heightPxinteger
mockups[].urlstring or nullThe flattened PNG (signed, 1 hour).
mockupsStalebooleanThe mockups show an older revision: render them again.
largeFormatanyLarge format: size, fit, bleed, safe area, background, double-sided, grommets; null otherwise.
productanyThe product: kind, pictures per colour and view (signed links), decoration areas, colours, active variants with prices.
placementsanyPlacements: area, view, method, print area on the picture (0–1), print size, ink colours / stitches / size band, options, and artwork layers (artwork version with links, position, rotation, checks = print warnings).
createdAtstring (date-time)
updatedAtstring (date-time)

Get a design

GET /organizations/{organizationId}/designs/{designId}

One design with its product (pictures per colour and view, decoration areas, colours), placements (method, print size, pricing inputs, artwork layers with print checks) and mockups. Read-only.

Permissiondecoration.read (Owner, Admin, Staff, Member)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP tooldesigns_get (toolset decoration)

Parameters

NameInTypeRequiredDescription
designIdpathstringYes

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs/{designId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
idstring
productIdstring
customerIdstring or null
customerobject or null
customer.idstring
customer.namestring
namestring
colorNamesarray of string
notesstring or null
revisionintegerBumped on every change; proofs show a revision.
mockupsarray of object
mockups[].viewenumOne of FRONT, BACK, SIDE, DETAIL, OTHER.
mockups[].colorNamestring or null
mockups[].widthPxinteger
mockups[].heightPxinteger
mockups[].urlstring or nullThe flattened PNG (signed, 1 hour).
mockupsStalebooleanThe mockups show an older revision: render them again.
largeFormatanyLarge format: size, fit, bleed, safe area, background, double-sided, grommets; null otherwise.
productanyThe product: kind, pictures per colour and view (signed links), decoration areas, colours, active variants with prices.
placementsanyPlacements: area, view, method, print area on the picture (0–1), print size, ink colours / stitches / size band, options, and artwork layers (artwork version with links, position, rotation, checks = print warnings).
createdAtstring (date-time)
updatedAtstring (date-time)

Update a design

PATCH /organizations/{organizationId}/designs/{designId}

Changes the fields sent; placements replaces every placement. Bumps the revision: mockups go stale and the next quote send makes a new proof. Quote lines already priced keep their price until re-priced.

Permissiondesigns.manage (Owner, Admin, Staff)
Riskwrite, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it.
MCP tooldesigns_update (toolset decoration)

Parameters

NameInTypeRequiredDescription
designIdpathstringYes

Request body

FieldTypeRequiredDescription
customerIdstring or nullNoWhose design (their library); null = the business's own.
namestring or nullNoUp to 200 characters.
colorNamesarray of stringNoProduct colours it is shown and ordered in (variant colorName). Up to 30 items.
notesstring or nullNoUp to 5000 characters.
largeFormatobject or nullNoLarge format: size in inches, FIT / FILL / STRETCH, bleed, safe area, background, double-sided, grommets.
largeFormat.widthInnumberNoAt most 10000.
largeFormat.heightInnumberNoAt most 10000.
largeFormat.fitenumNoFit: the whole image inside; FILL: cover the piece (cropped); STRETCH: distorted to fill. One of FIT, FILL, STRETCH. Default FILL.
largeFormat.bleedInnumberNo0–12. Default 0.125.
largeFormat.safeInnumberNo0–24. Default 1.
largeFormat.backgroundstringNoDefault #ffffff.
largeFormat.doubleSidedbooleanNoDefault false.
largeFormat.grommetSpacingInnumber or nullNoAt most 120.
largeFormat.grommetEdgesenumNoOne of ALL, TOP_BOTTOM, LEFT_RIGHT, TOP. Default ALL.
placementsarray of objectNoReplaces every placement when given. Up to 20 items.
placements[].areaKeystringYesOne of the product's decoration areas (GET /products/{productId} decorationAreas). Up to 60 characters.
placements[].areaNamestring or nullNoUp to 120 characters.
placements[].viewenum or nullNoDefault: the area's view. One of FRONT, BACK, SIDE, DETAIL, OTHER.
placements[].methodIdstring or nullNoThe decoration method (GET /decoration-methods).
placements[].xnumber or nullNoThe print area on the view's picture, 0–1. -1–2.
placements[].ynumber or nullNo-1–2.
placements[].widthnumber or nullNoAt most 3.
placements[].heightnumber or nullNoAt most 3.
placements[].inkColorsinteger or nullNoInk colours (COLORS tables). 1–30.
placements[].stitchCountinteger or nullNoStitches (STITCHES tables). 0–1000000.
placements[].sizeBandKeystring or nullNoA size band column key (SIZE_BAND). Up to 40 characters.
placements[].printWidthInnumber or nullNoAt most 10000.
placements[].printHeightInnumber or nullNoAt most 10000.
placements[].optionsobject or nullNo
placements[].options.underbaseboolean or nullNoForce the white underbase on (true) or off (false); default: on dark colours.
placements[].options.puffboolean or nullNoEmbroidery 3D puff.
placements[].options.alreadyDigitizedboolean or nullNoThe embroidery file exists (a reorder): no digitizing fee.
placements[].options.artServiceboolean or nullNoAsk for the art fee (redraw, clean-up).
placements[].options.doubleSidedboolean or nullNoLarge format: print both sides.
placements[].options.setupWaivedboolean or nullNoScreens or set-up already paid (a reorder).
placements[].layersarray of objectNoArtwork on the picture: artwork versions with position, size and rotation as fractions. Up to 12 items.
placements[].layers[].kindenumNoOne of ARTWORK, TEXT, CLIPART. Default ARTWORK.
placements[].layers[].artworkVersionIdstringNoARTWORK layers: GET /artwork/{artworkId} versions. Up to 64 characters.
placements[].layers[].textstringNoTEXT layers: one line. Up to 120 characters.
placements[].layers[].fontenumNoTEXT layers (default sans). One of sans, sans-bold, serif, serif-bold, mono.
placements[].layers[].colorstringNoTEXT and CLIPART layers: the ink colour (#rrggbb).
placements[].layers[].clipartKeystringNoCLIPART layers: a key of the clipart library (GET /public/studio/…). Up to 40 characters.
placements[].layers[].xnumberYesLeft edge, as a fraction of the picture's width. -1–2.
placements[].layers[].ynumberYesTop edge, as a fraction of the picture's height. -1–2.
placements[].layers[].widthnumberYesAt most 3.
placements[].layers[].heightnumberYesAt most 3.
placements[].layers[].rotationnumberNo-360–360. Default 0.

Example

curl -X PATCH "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs/{designId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"customer_id","name":"Dana Whitfield","colorNames":["string"]}'

Response

200: the answer's fields
FieldTypeDescription
idstring
productIdstring
customerIdstring or null
customerobject or null
customer.idstring
customer.namestring
namestring
colorNamesarray of string
notesstring or null
revisionintegerBumped on every change; proofs show a revision.
mockupsarray of object
mockups[].viewenumOne of FRONT, BACK, SIDE, DETAIL, OTHER.
mockups[].colorNamestring or null
mockups[].widthPxinteger
mockups[].heightPxinteger
mockups[].urlstring or nullThe flattened PNG (signed, 1 hour).
mockupsStalebooleanThe mockups show an older revision: render them again.
largeFormatanyLarge format: size, fit, bleed, safe area, background, double-sided, grommets; null otherwise.
productanyThe product: kind, pictures per colour and view (signed links), decoration areas, colours, active variants with prices.
placementsanyPlacements: area, view, method, print area on the picture (0–1), print size, ink colours / stitches / size band, options, and artwork layers (artwork version with links, position, rotation, checks = print warnings).
createdAtstring (date-time)
updatedAtstring (date-time)

Delete a design

DELETE /organizations/{organizationId}/designs/{designId}

Destructive: deletes the design and its placements. Refused while an open quote uses it (duplicate it instead).

Permissiondesigns.manage (Owner, Admin, Staff)
Risksensitive, OAuth scope skuflow.sensitive. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tooldesigns_delete (toolset decoration)
ApprovalOver MCP, this tool always waits for your approval in SKUFlow. See Approvals.

Parameters

NameInTypeRequiredDescription
designIdpathstringYes

Example

curl -X DELETE "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs/{designId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
oktrue

Duplicate a design

POST /organizations/{organizationId}/designs/{designId}/duplicate

A copy with the same product, colours and placements (to change a design an open quote uses, or start a reorder variant).

Permissiondesigns.manage (Owner, Admin, Staff)
Riskwrite, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it.
MCP tooldesigns_duplicate (toolset decoration)

Parameters

NameInTypeRequiredDescription
designIdpathstringYes

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs/{designId}/duplicate" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

201: the answer's fields
FieldTypeDescription
idstring
productIdstring
customerIdstring or null
customerobject or null
customer.idstring
customer.namestring
namestring
colorNamesarray of string
notesstring or null
revisionintegerBumped on every change; proofs show a revision.
mockupsarray of object
mockups[].viewenumOne of FRONT, BACK, SIDE, DETAIL, OTHER.
mockups[].colorNamestring or null
mockups[].widthPxinteger
mockups[].heightPxinteger
mockups[].urlstring or nullThe flattened PNG (signed, 1 hour).
mockupsStalebooleanThe mockups show an older revision: render them again.
largeFormatanyLarge format: size, fit, bleed, safe area, background, double-sided, grommets; null otherwise.
productanyThe product: kind, pictures per colour and view (signed links), decoration areas, colours, active variants with prices.
placementsanyPlacements: area, view, method, print area on the picture (0–1), print size, ink colours / stitches / size band, options, and artwork layers (artwork version with links, position, rotation, checks = print warnings).
createdAtstring (date-time)
updatedAtstring (date-time)

Render the design's mockups

POST /organizations/{organizationId}/designs/{designId}/mockups

Flattens the art onto the product's pictures, a PNG per view (and per chosen colour, up to six); large format renders the piece at its size with the image fitted or filled and the grommets. Stored and returned with the design.

Permissiondesigns.manage (Owner, Admin, Staff)
Riskwrite, OAuth scope skuflow.write. Write: creates or changes records inside the business; nothing leaves it.
MCP tooldesigns_renderMockups (toolset decoration)

Parameters

NameInTypeRequiredDescription
designIdpathstringYes

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs/{designId}/mockups" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
idstring
productIdstring
customerIdstring or null
customerobject or null
customer.idstring
customer.namestring
namestring
colorNamesarray of string
notesstring or null
revisionintegerBumped on every change; proofs show a revision.
mockupsarray of object
mockups[].viewenumOne of FRONT, BACK, SIDE, DETAIL, OTHER.
mockups[].colorNamestring or null
mockups[].widthPxinteger
mockups[].heightPxinteger
mockups[].urlstring or nullThe flattened PNG (signed, 1 hour).
mockupsStalebooleanThe mockups show an older revision: render them again.
largeFormatanyLarge format: size, fit, bleed, safe area, background, double-sided, grommets; null otherwise.
productanyThe product: kind, pictures per colour and view (signed links), decoration areas, colours, active variants with prices.
placementsanyPlacements: area, view, method, print area on the picture (0–1), print size, ink colours / stitches / size band, options, and artwork layers (artwork version with links, position, rotation, checks = print warnings).
createdAtstring (date-time)
updatedAtstring (date-time)

Price a design at quantities

GET /organizations/{organizationId}/designs/{designId}/price

The design's price at quantities per variant (items; or quantity of its first colour): sizes priced alike grouped (blank + decoration per piece at the total), per-location detail and one-time fees. Read-only.

Permissiondecoration.read (Owner, Admin, Staff, Member)
Riskread, OAuth scope skuflow.read. Read: reads only.
MCP tooldesigns_price (toolset decoration)

Parameters

NameInTypeRequiredDescription
designIdpathstringYes
itemsqueryarray of objectNoUp to 200 items.
quantityqueryintegerNo1–1000000.
waivedFeesqueryarray of stringNoUp to 50 items.

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/designs/{designId}/price" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields
FieldTypeDescription
okboolean
groupsanySizes priced alike: unit price (blank + decoration), quantity, colours, sizes and items.
placementsanyPer location: method, the column and quantity break used, price per piece (and on dark colours).
quantitynumber
totalCentsinteger
goodsCentsinteger
feesCentsinteger
feesarray of object
fees[].keystring{placementKey}:{kind}: name it in waivedFees to leave it off.
fees[].kindenumOne of setup, digitizing, art, layout, minimum.
fees[].labelstring
fees[].amountCentsinteger
fees[].costCentsanyOur cost of the fee. Present only for roles with costing.read.
fees[].costKnownanyFalse when the method has no cost table (the fee's cost counts as 0). Present only for roles with costing.read.
problemsarray of string
totalCostCentsanyOur cost of the whole line, fees included. Present only for roles with costing.read.
marginCentsanyPrice minus cost. Present only for roles with costing.read.
costKnownanyTrue when every cost behind totalCostCents is known (each blank has a cost, each method a cost table); false means part of it counted as 0. Present only for roles with costing.read.

On this page