Printago API
POST /v1/sku-variants

Create a new SKU variant

Create a variant option, such as Color or Size, that SKUs can offer. Options are shared across your store: define Color once and bind it to every SKU sold in colors. Variant endpoints require a commercial account. /v1/sku-options is an alias of /v1/sku-variants and behaves identically.

Send Authorization: ApiKey <your-api-key>.

How variants fit together

Piece Endpoint What it is
Option POST /v1/sku-variants A choice a buyer makes, for example Color. Set isPersonalization: true for a free-text question such as a name to engrave.
Value POST /v1/sku-variants/values One answer to an option, for example Red. skuSuffixes let a code like BENCHY-RED resolve to the base SKU BENCHY with Color = Red.
Binding POST /v1/sku-variants/bindings Offers an option on one SKU. Bound options are required on that SKU's orders unless the binding is optional.
Property POST /v1/sku-variants/props Something an option's value controls, typed material, text or plate_quantities, for example a Filament property on Color.
Property value POST /v1/sku-variants/prop-values The setting a property takes for a given value, for example Filament for Red is a specific red PLA.

A SKU's linked parts then point at properties: materialAssignments entries of { "propertyId": ... } for materials, parameterBindings for parametric text, and plateQuantitiesBinding for which 3MF plates to print. When an order or build selects Color = Red, Printago looks up each bound property's value for Red and applies it to the print.

Typical setup for a color option

  1. POST /v1/sku-variants with { "name": "Color", "isPersonalization": false }.
  2. POST /v1/sku-variants/values once per color, with skuSuffixes if your storefront encodes the color in the SKU code.
  3. POST /v1/sku-variants/props with { "optionId": "<Color ID>", "name": "Filament", "type": "material" }.
  4. POST /v1/sku-variants/prop-values with one entry per color, each setting materialValue.
  5. Create the SKU with optionBindings: ["<Color ID>"] and a linked part whose materialAssignments uses { "propertyId": "<Filament ID>" } (see POST /v1/skus), or bind an existing SKU with POST /v1/sku-variants/bindings.

Option names and aliases must be unique across your store, ignoring case and extra spaces. A clash returns 409.

Requires: sku.edit

Request Body

- SKU variant data

CreateSkuOptionRequest
aliasesoptional
string[]

Other names that resolve to this option, for example the label a marketplace uses for the same field.

isPersonalizationrequired
boolean

true for a free-text question whose answer is passed through as typed, for example a name to engrave. Personalization options are not part of variant SKU codes.

namerequired
string

Name of the option as buyers and orders refer to it, for example Color. Name-based lookups (build options, marketplace imports) ignore case and extra spaces.

Example Request

application/json 
{
  "name": "string",
  "isPersonalization": true,
  "aliases": [
    "string"
  ]
}

Examples

Create a Color option

Request 
{
  "name": "Color",
  "isPersonalization": false
}
Response 
{
  "id": "v2a6r0i4a8n1t5c9o3l7o2r6",
  "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
  "name": "Color",
  "isPersonalization": false,
  "aliases": [],
  "createdAt": "2026-09-23T16:20:01.114Z",
  "updatedAt": "2026-09-23T16:20:01.114Z"
}

Create a personalization question with aliases

Aliases let orders from marketplaces that label the field differently resolve to the same option.

Request 
{
  "name": "Name",
  "isPersonalization": true,
  "aliases": [
    "Personalization",
    "Name to engrave"
  ]
}
Response 
{
  "id": "n7a1m3e5t9x2o4q6w8e0r2t4",
  "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
  "name": "Name",
  "isPersonalization": true,
  "aliases": [
    "Personalization",
    "Name to engrave"
  ],
  "createdAt": "2026-09-23T16:21:37.806Z",
  "updatedAt": "2026-09-23T16:21:37.806Z"
}

Response Schema

SkuOption
aliasesoptionalnullable
string[]

Other names that resolve to this option, for example the label a marketplace uses for the same field.

createdAtrequired
string
format: date-time
idrequired
string
pattern: ^[a-z0-9]{24}$
isPersonalizationrequired
boolean

true for a free-text question whose answer is passed through as typed, for example a name to engrave. Personalization options are not part of variant SKU codes.

namerequired
string

Name of the option as buyers and orders refer to it, for example Color. Name-based lookups (build options, marketplace imports) ignore case and extra spaces.

storeIdrequired
string
pattern: ^[a-z0-9]{24}$
updatedAtrequired
string
format: date-time

Example Response

201 OK — application/json 
{
  "name": "string",
  "isPersonalization": true,
  "aliases": [
    "string"
  ],
  "id": "string",
  "storeId": "string",
  "createdAt": "2025-01-15T12:00:00.000Z",
  "updatedAt": "2025-01-15T12:00:00.000Z"
}