Printago API
POST /v1/orders

Create a new order

Create an order, optionally with a customer and line items, in one call. Use it to bring orders from a storefront or system Printago has no built-in integration for.

Send Authorization: ApiKey <your-api-key>. Orders require a commercial account; other stores get 403.

Line items and SKUs

Each item needs a quantity and a way to find its Printago SKU:

  • skuId: the SKU's ID. Used as given.
  • sku: a SKU code. Printago first looks for a SKU with exactly that code. If none matches, it tries to read the code as a base SKU followed by variant suffixes (for example BENCHY + -RED), using the skuSuffixes configured on your variant values, and fills skuConfig.selectedOptions with the matched values.

An item whose code matches nothing is still saved, with skuId: null and the code in externalSku, so you can map it later. Items with none of skuId, sku or externalSku are dropped.

Customers

If you include customer, Printago reuses an existing customer with the same externalId (or, when there is no externalId, the same email) and creates one otherwise.

Printing

Creating an order does not queue anything. To print it, call POST /v1/orders/print with the order's ID in orderIds and the SKUs to print in skuIds. That creates SKU builds linked to the order, and the resulting print jobs carry its orderId.

processedAt defaults to the time of the request. Items are created with processedStatus: "unprocessed".

Requires: order.create

Request Body

Order details including optional customer and items

CreateOrderDto
customeroptional
object

Customer to attach. Matched to an existing customer by externalId, or by email when there is no externalId; created otherwise.

countryCodeoptionalnullable
string
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
emailoptionalnullable
string
externalIdoptionalnullable
string
nameoptionalnullable
string
phoneoptionalnullable
string
provinceCodeoptionalnullable
string
sourceoptionalnullable
enum
etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix
zipCodeoptionalnullable
string
itemsoptional
object[]

Line items. Each needs quantity (at least 1) and one of skuId, sku or externalSku.

customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
externalIdoptionalnullable
string
externalOrderIdoptionalnullable
string
externalProductIdoptionalnullable
string
externalSkuoptionalnullable
string
ignoredoptionalnullable
boolean
inputsoptionalnullable
Record<string, any>
Construct a type with a set of properties K of type T
originalSkuoptionalnullable
string
Original SKU identifier sent when creating the order item (sku or externalSku), null if skuId was provided directly
processedAtoptionalnullable
string
format: date-time
processedStatusoptionalnullable
"unprocessed" | "processed"
unprocessedprocessed
quantityrequired
number
min: 1
resolutionNoteoptionalnullable
object
Structured note describing why SKU or variant resolution failed. Stored as a dedicated column on order_items for easy querying.
messagerequired
string
occurredAtrequired
number
Timestamp of when this failure occurred
retriablerequired
boolean
Whether this failure can be retried (e.g., API errors are retriable, missing SKUs are not)
typerequired
"variant_enrichment_failed" | "sku_not_found" | "ambiguous_match"
variant_enrichment_failedsku_not_foundambiguous_match
skuoptionalnullable
string

A SKU code to resolve to a Printago SKU, either an exact SKU code or a base code followed by variant value suffixes.

skuConfigoptionalnullable
object

Per-item build settings: selectedOptions (variant option ID to value ID or value name, or free text for an option without predefined values) and linkedPartConfigs (overrides keyed by linked part ID, the same shape as in POST /v2/builds). Used when the order is printed.

freeTextOptionIdsoptional
string[]
Options whose selected value is a buyer's free-text answer rather than one of the option's defined values. A personalization question can reuse a variant option (same name), and its arbitrary answers must not be flagged as invalid values during reconciliation.
linkedPartConfigsoptional
Record<string, object>
Construct a type with a set of properties K of type T
personalizationAnswerKeysoptional
string[]
selectedOptions keys the integration wrote from buyer personalization answers (as opposed to regular variation selections). Only these may be treated as free text when they land on a variant option; an unmatched regular variation value must still fail validation.
selectedOptionsoptional
Record<string, string>
Construct a type with a set of properties K of type T
skuIdoptionalnullable
string
Internal SKU ID (Cuid2). Takes precedence over `sku` if both provided.
sourceoptionalnullable
enum
etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix
statusoptionalnullable
string
orderrequired
object
currencyoptionalnullable
string
customerIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
deadlineoptionalnullable
string

Date the order is due.

externalIdoptionalnullable
string

Your system's ID for the order. When source is set, each externalId can be used only once per source within your store.

externalUrloptionalnullable
string
integrationIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
noteoptionalnullable
string
orderNumberrequired
string

Your order number, shown throughout Printago.

priceoptionalnullable
number
priceBucketoptionalnullable
number
processedAtoptionalnullable
string
shippedAtoptionalnullable
string
sourceoptionalnullable
enum

Where the order came from. Leave it unset for orders you create yourself; the values other than manual are used by Printago's marketplace integrations.

etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix
sourceRefoptionalnullable
string

Example Request

application/json 
{
  "order": {
    "externalId": "string",
    "source": "etsy",
    "integrationId": "string",
    "customMetadata": {},
    "orderNumber": "string",
    "customerId": "string",
    "shippedAt": "2025-01-15T12:00:00.000Z",
    "priceBucket": 1,
    "price": 1,
    "currency": "string",
    "externalUrl": "string",
    "note": "string",
    "deadline": "2025-01-15T12:00:00.000Z",
    "processedAt": "2025-01-15T12:00:00.000Z",
    "sourceRef": "string"
  },
  "customer": {
    "name": "string",
    "externalId": "string",
    "source": "etsy",
    "customMetadata": {},
    "email": "string",
    "phone": "string",
    "countryCode": "string",
    "provinceCode": "string",
    "zipCode": "string"
  },
  "items": [
    {
      "skuId": "string",
      "sku": "string",
      "externalId": "string",
      "source": "etsy",
      "customMetadata": {},
      "status": "string",
      "processedAt": "2025-01-15T12:00:00.000Z",
      "quantity": 1,
      "inputs": {},
      "externalOrderId": "string",
      "externalProductId": "string",
      "externalSku": "string",
      "originalSku": "string",
      "processedStatus": "unprocessed",
      "ignored": true,
      "skuConfig": {
        "linkedPartConfigs": {},
        "selectedOptions": {},
        "freeTextOptionIds": [
          "string"
        ],
        "personalizationAnswerKeys": [
          "string"
        ]
      },
      "resolutionNote": {
        "type": "variant_enrichment_failed",
        "message": "string",
        "retriable": true,
        "occurredAt": 1
      }
    }
  ]
}

Examples

Create an order with a customer and two items

The first item is identified by a variant SKU code, the second by SKU ID.

Request 
{
  "order": {
    "orderNumber": "1042",
    "externalId": "sq-ord-88214",
    "price": 34.5,
    "currency": "USD",
    "note": "Gift wrap, please",
    "deadline": "2026-09-30T00:00:00.000Z"
  },
  "customer": {
    "name": "Jordan Lee",
    "email": "jordan.lee@example.com"
  },
  "items": [
    {
      "sku": "BENCHY-RED",
      "quantity": 2
    },
    {
      "skuId": "s8k2u6c0o4a7s1t5e9r3f2g6",
      "quantity": 1
    }
  ]
}
Response 
{
  "order": {
    "id": "o4r8d2e6r0x3c7v1b5n9m2q6",
    "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
    "orderNumber": "1042",
    "status": "open",
    "source": null,
    "customerId": "c3u7s1t5o9m2e6r0q4w8e1r5",
    "externalId": "sq-ord-88214",
    "price": 34.5,
    "currency": "USD",
    "note": "Gift wrap, please",
    "deadline": "2026-09-30T00:00:00.000Z",
    "processedAt": "2026-09-23T15:20:44.103Z",
    "syncDisabled": false,
    "createdAt": "2026-09-23T15:20:44.180Z",
    "updatedAt": "2026-09-23T15:20:44.180Z"
  },
  "customer": {
    "id": "c3u7s1t5o9m2e6r0q4w8e1r5",
    "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
    "name": "Jordan Lee",
    "email": "jordan.lee@example.com",
    "createdAt": "2026-09-23T15:20:44.151Z",
    "updatedAt": "2026-09-23T15:20:44.151Z"
  },
  "items": [
    {
      "id": "i9t3e7m1q5w2r6t0y4u8i3o5",
      "orderId": "o4r8d2e6r0x3c7v1b5n9m2q6",
      "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
      "source": "manual",
      "quantity": 2,
      "externalSku": "BENCHY-RED",
      "originalSku": "BENCHY-RED",
      "processedStatus": "unprocessed",
      "ignored": false,
      "skuConfig": {
        "selectedOptions": {
          "v2a6r0i4a8n1t5c9o3l7o2r6": "r3e7d1v5a9l2u6e0q4w8e3r7"
        }
      },
      "createdAt": "2026-09-23T15:20:44.214Z",
      "updatedAt": "2026-09-23T15:20:44.214Z"
    },
    {
      "id": "i2w6e0r4t8y1u5i9o3p7a2s6",
      "orderId": "o4r8d2e6r0x3c7v1b5n9m2q6",
      "skuId": "s8k2u6c0o4a7s1t5e9r3f2g6",
      "source": "manual",
      "quantity": 1,
      "externalSku": null,
      "originalSku": null,
      "processedStatus": "unprocessed",
      "ignored": false,
      "skuConfig": {
        "selectedOptions": {}
      },
      "createdAt": "2026-09-23T15:20:44.214Z",
      "updatedAt": "2026-09-23T15:20:44.214Z"
    }
  ]
}

Create an order with a personalized item

Pass variant and personalization choices in skuConfig.selectedOptions, keyed by the ID of a variant option bound to the SKU. Values can be a value ID or a value name, or free text for an option that has no predefined values (such as a name to engrave).

Request 
{
  "order": {
    "orderNumber": "1043"
  },
  "items": [
    {
      "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
      "quantity": 1,
      "skuConfig": {
        "selectedOptions": {
          "v2a6r0i4a8n1t5c9o3l7o2r6": "Red",
          "n7a1m3e5t9x2o4q6w8e0r2t4": "Ada"
        }
      }
    }
  ]
}
Response 
{
  "order": {
    "id": "o7p1q5r9s3t6u0v4w8x2y5z9",
    "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
    "orderNumber": "1043",
    "status": "open",
    "customerId": null,
    "processedAt": "2026-09-23T15:31:02.667Z",
    "syncDisabled": false,
    "createdAt": "2026-09-23T15:31:02.702Z",
    "updatedAt": "2026-09-23T15:31:02.702Z"
  },
  "customer": null,
  "items": [
    {
      "id": "i5o9p3a7s1d4f8g2h6j0k3l7",
      "orderId": "o7p1q5r9s3t6u0v4w8x2y5z9",
      "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
      "source": "manual",
      "quantity": 1,
      "originalSku": null,
      "processedStatus": "unprocessed",
      "skuConfig": {
        "selectedOptions": {
          "v2a6r0i4a8n1t5c9o3l7o2r6": "Red",
          "n7a1m3e5t9x2o4q6w8e0r2t4": "Ada"
        }
      }
    }
  ]
}

Response Schema

OrderDetailsResponse
customerrequirednullable
object

Customer to attach. Matched to an existing customer by externalId, or by email when there is no externalId; created otherwise.

countryCodeoptionalnullable
string
createdAtrequired
string
format: date-time
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
emailoptionalnullable
string
externalIdoptionalnullable
string
idrequired
string
pattern: ^[a-z0-9]{24}$
nameoptionalnullable
string
phoneoptionalnullable
string
provinceCodeoptionalnullable
string
sourceoptionalnullable
enum
etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
updatedAtrequired
string
format: date-time
zipCodeoptionalnullable
string
itemsrequired
object[]

Line items. Each needs quantity (at least 1) and one of skuId, sku or externalSku.

createdAtrequired
string
format: date-time
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
externalIdoptionalnullable
string
externalOrderIdoptionalnullable
string
externalProductIdoptionalnullable
string
externalSkuoptionalnullable
string
idrequired
string
pattern: ^[a-z0-9]{24}$
ignoredoptionalnullable
boolean
inputsoptionalnullable
Record<string, any>
Construct a type with a set of properties K of type T
orderIdrequired
string
pattern: ^[a-z0-9]{24}$
originalSkuoptionalnullable
string
Original SKU identifier sent when creating the order item (sku or externalSku), null if skuId was provided directly
processedAtoptionalnullable
string
format: date-time
processedStatusoptionalnullable
"unprocessed" | "processed"
unprocessedprocessed
quantityrequired
number
min: 1
resolutionNoteoptionalnullable
object
Structured note describing why SKU or variant resolution failed. Stored as a dedicated column on order_items for easy querying.
messagerequired
string
occurredAtrequired
number
Timestamp of when this failure occurred
retriablerequired
boolean
Whether this failure can be retried (e.g., API errors are retriable, missing SKUs are not)
typerequired
"variant_enrichment_failed" | "sku_not_found" | "ambiguous_match"
variant_enrichment_failedsku_not_foundambiguous_match
skuConfigoptionalnullable
object

Per-item build settings: selectedOptions (variant option ID to value ID or value name, or free text for an option without predefined values) and linkedPartConfigs (overrides keyed by linked part ID, the same shape as in POST /v2/builds). Used when the order is printed.

freeTextOptionIdsoptional
string[]
Options whose selected value is a buyer's free-text answer rather than one of the option's defined values. A personalization question can reuse a variant option (same name), and its arbitrary answers must not be flagged as invalid values during reconciliation.
linkedPartConfigsoptional
Record<string, object>
Construct a type with a set of properties K of type T
personalizationAnswerKeysoptional
string[]
selectedOptions keys the integration wrote from buyer personalization answers (as opposed to regular variation selections). Only these may be treated as free text when they land on a variant option; an unmatched regular variation value must still fail validation.
selectedOptionsoptional
Record<string, string>
Construct a type with a set of properties K of type T
skuIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
sourceoptionalnullable
enum
etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix
statusoptionalnullable
string
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
updatedAtrequired
string
format: date-time
orderrequired
object
Order entity representing a retail order
cancelledAtoptionalnullable
string
createdAtrequired
string
format: date-time
currencyoptionalnullable
string
customerIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
deadlineoptionalnullable
string

Date the order is due.

externalIdoptionalnullable
string

Your system's ID for the order. When source is set, each externalId can be used only once per source within your store.

externalUrloptionalnullable
string
idrequired
string
pattern: ^[a-z0-9]{24}$
integrationIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
noteoptionalnullable
string
orderNumberrequired
string

Your order number, shown throughout Printago.

priceoptionalnullable
number
priceBucketoptionalnullable
number
processedAtoptionalnullable
string
shippedAtoptionalnullable
string
sourceoptionalnullable
enum

Where the order came from. Leave it unset for orders you create yourself; the values other than manual are used by Printago's marketplace integrations.

etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix
sourceRefoptionalnullable
string
statusrequired
"open" | "closed"
openclosed
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
syncDisabledrequired
boolean
updatedAtrequired
string
format: date-time

Example Response

201 OK — application/json 
{
  "order": {
    "orderNumber": "string",
    "source": "etsy",
    "status": "open",
    "cancelledAt": "2025-01-15T12:00:00.000Z",
    "shippedAt": "2025-01-15T12:00:00.000Z",
    "customerId": "string",
    "integrationId": "string",
    "priceBucket": 1,
    "price": 1,
    "currency": "string",
    "externalId": "string",
    "externalUrl": "string",
    "sourceRef": "string",
    "note": "string",
    "deadline": "2025-01-15T12:00:00.000Z",
    "processedAt": "2025-01-15T12:00:00.000Z",
    "syncDisabled": true,
    "customMetadata": {},
    "id": "string",
    "storeId": "string",
    "createdAt": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  },
  "customer": {
    "name": "string",
    "email": "string",
    "phone": "string",
    "countryCode": "string",
    "provinceCode": "string",
    "zipCode": "string",
    "externalId": "string",
    "source": "etsy",
    "customMetadata": {},
    "id": "string",
    "storeId": "string",
    "createdAt": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  },
  "items": [
    {
      "orderId": "string",
      "skuId": "string",
      "source": "etsy",
      "quantity": 1,
      "inputs": {},
      "status": "string",
      "externalId": "string",
      "externalOrderId": "string",
      "externalProductId": "string",
      "externalSku": "string",
      "originalSku": "string",
      "processedAt": "2025-01-15T12:00:00.000Z",
      "ignored": true,
      "processedStatus": "unprocessed",
      "skuConfig": {
        "linkedPartConfigs": {},
        "selectedOptions": {},
        "freeTextOptionIds": [
          "string"
        ],
        "personalizationAnswerKeys": [
          "string"
        ]
      },
      "resolutionNote": {
        "type": "variant_enrichment_failed",
        "message": "string",
        "retriable": true,
        "occurredAt": 1
      },
      "customMetadata": {},
      "id": "string",
      "storeId": "string",
      "createdAt": "2025-01-15T12:00:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z"
    }
  ]
}