Create a connector

Creates a connector from a source on the product page (a selector, or a Print Options field by role or id), a mode and, for modes that need them, a mapping per choice. Each mode’s rules are checked: page numbers for pageIndex, your own designs for designSelector, hex colours for underlayColor. Try it first with POST /v2/connectors/test, then attach it with POST /v2/designs/{id}/connectors.

POST /v2/connectors

Create a connector

cURL

curl --request POST \
  --url https://api.print.app/v2/connectors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Print side → pages",
  "mode": "pageIndex",
  "source": {
    "selector": "input[name=\"Print side\"]:checked"
  },
  "mappings": [
    {
      "from": "Front",
      "to": "1"
    },
    {
      "from": "Back",
      "to": "2"
    },
    {
      "from": "Front and back",
      "to": "1,2"
    }
  ]
}
'

201

{
  "object": "connector",
  "id": "01KADX3Q7M2B8C4D5E6F7G8H9J",
  "title": "Print side → pages",
  "mode": "pageIndex",
  "source": {
    "type": "selector",
    "selector": "input[name=\"Print side\"]:checked"
  },
  "query": "input[name=\"Print side\"]:checked",
  "mappings": [
    {
      "from": "Front",
      "to": "1"
    },
    {
      "from": "Back",
      "to": "2"
    },
    {
      "from": "Front and back",
      "to": "1,2"
    }
  ],
  "twoWay": true,
  "page": null,
  "text": null,
  "event": null,
  "created": "2026-10-27T10:00:00Z",
  "modified": "2026-10-27T10:00:00Z"
}

Authorizations

Authorization · string · header · required

A secret key from Print.App admin → Domains → Secret keys, sent as Authorization: Bearer sk_…. Server-side only.

Headers

Idempotency-Key · string

Makes a retry safe: a second request with the same key and the same body gets the first response back (for 24 hours) instead of creating the resource again. Use a new key, such as a UUID, for every new request.

Required string length: 1 - 255

Body

application/json

A new connector. Attach it to designs with POST /v2/designs/{id}/connectors.

title · string · required

The connector's name, shown in the dashboard.

Required string length: 1 - 200

mode · enum<string> · required

What the connector does:

• pageIndex: Shows only the pages a choice maps to (to: page numbers such as 1 or 1,2). The other pages are set aside: not shown, printed or saved.
• designSelector: Opens another design for each choice (to: a design id). Every design it can open must be assigned to the product and carry this connector too.
• pageClone: Repeats one page (page, default the first) as many times as the number chosen, when the editor opens.
• pageCount: Sends the number of pages to the field as the customer adds or removes pages (editor to product page).
• printedPageCount: Sends the number of pages (sides) that carry a print to the field, so the price can follow (editor to product page). The field takes a number.
• pageWidth: Sets the page width from a number field, in the design's unit (a Print Options size field carries its own). With twoWay, a resize in the editor is sent back.
• pageHeight: Sets the page height from a number field, in the design's unit (a Print Options size field carries its own). With twoWay, a resize in the editor is sent back.
• pageOrientation: Turns the pages (or page alone) landscape or portrait, from the choice's wording or its mapping (to: landscape or portrait).
• textValue: Puts what the customer types into the text item titled text. With twoWay, edits in the editor are sent back.
• underlayColor: Sets the product colour of an underlay design (a T-shirt, a mug): to is a hex colour, or leave the choice unmapped when it is the colour's name in the design.
• event: Fires an editor event (event.name, with event.data) when the field changes. For integrations that listen to editor events.

Available options: pageIndex, designSelector, pageClone, pageCount, printedPageCount, pageWidth, pageHeight, pageOrientation, textValue, underlayColor, event

source · object · required

Where on the product page the connector reads (and, for two-way modes, writes): a CSS selector for a control of the store's theme, or a Print Options field by role (preferred: one connector then works on every product) or by field id. GET /v2/product-page lists both for a page.

Show child attributes

mappings · object[]

What each choice on the product page becomes in the editor. from is the choice as the page sends it: its value, or for dropdowns and Print Options choices also the text the customer sees (case and surrounding spaces ignored). Radio choices send their value only.

Maximum array length: 200

Show child attributes

twoWay · boolean · default: true

For pageWidth, pageHeight, textValue and underlayColor: also send changes made in the editor back to the product page.

page · integer | null

For pageClone, pageWidth, pageHeight and pageOrientation: the page (from 1) it acts on. Default: the first page (pageOrientation: every page).

Required range: 1 <= x <= 500

text · string | null

For textValue: the title of the text item it fills.

Required string length: 1 - 200

event · object | null

For event: the editor event to fire.

Show child attributes

Response

201

application/json

Created.

Links an option on a store's product page to the editor: the choice a customer makes shows the right pages, opens the right design, sets the size or the colour.

object · string · required

Allowed value: "connector"

id · string | null · required

null for a connector tried in a test without saving it.

title · string | null · required

mode · string · required

One of: pageIndex, designSelector, pageClone, pageCount, printedPageCount, pageWidth, pageHeight, pageOrientation, textValue, underlayColor, event.

source · object · required

Show child attributes

query · string · required

The source as the editor stores it: the selector, or po:role/<role>, po:field/<id>.

mappings · object[] · required

Show child attributes

twoWay · boolean · required

page · integer | null · required

text · string | null · required

event · object | null · required

Show child attributes

created · string<date-time> | null · required

modified · string<date-time> | null · required