Create Print Job
POST
/terminal/v1/{terminalSerial}/sync/print/job
🚧 Beta — Early Access
This API is in early access. Endpoints, parameters, and response structures
may change without prior notice. Do not deploy to production without
coordinating with the Kushki integration team.
Returns 202 Accepted with a
PENDING status immediately.COMPLETED or FAILED) is delivered via:webhookUrl in the request.POST .../print/job_status?print_job_id={id}.Command Types
commands array contains polymorphic objects. The type property(required on every object) determines its behavior. All enum values must be
sent in UPPERCASE.
type | Description |
|---|---|
text | Text line with configurable size, alignment, bold, italic, and underline. |
columns | Multi-column row with proportional widths — ideal for item/price lines. |
divider | Full-width separator: SOLID, DOTTED, or EMPTY. |
feed | Advance paper N blank lines. |
space | Insert precise pixel-level vertical whitespace. |
cut | Trigger the auto-cutter. Silently ignored on cutterless terminals. |
image | Print a Base64-encoded PNG/JPG — typically used for merchant logos. |
qr | Generate a QR code natively in printer hardware. |
barcode | Generate a CODE128 barcode natively in printer hardware. |
text — Text Line
Append
\n to the text field to force an explicit line break.| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
text | String | ✅ | — | Text to print. |
align | LEFT | CENTER | RIGHT | ❌ | LEFT | Horizontal alignment. |
size | Integer | ❌ | 24 | Font size in px. Reference: 24 normal · 32 subtitle · 48 title. |
bold | Boolean | ❌ | false | Bold. |
italic | Boolean | ❌ | false | Italic. |
underline | Boolean | ❌ | false | Underline. |
{
"type": "text",
"text": "RESTAURANT EL BUEN SABOR\n",
"align": "CENTER",
"size": 32,
"bold": true
}columns — Multi-Column Row
The
weight field controls the relative width of each column.| Field (per column) | Type | Required | Default | Description |
|---|---|---|---|---|
text | String | ✅ | — | Cell text. |
weight | Integer | ❌ | 1 | Relative width. Weights 2 and 1 give the first column 2/3 of the paper. |
align | LEFT | CENTER | RIGHT | ❌ | LEFT | Alignment within the cell. |
{
"type": "columns",
"columns": [
{ "text": "2x Combo Burger", "weight": 2, "align": "LEFT" },
{ "text": "$30.00", "weight": 1, "align": "RIGHT" }
]
}divider — Separator Line
(header, items, totals).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
dividerType | SOLID | DOTTED | EMPTY | ❌ | EMPTY | Line style. |
offset | Integer | ❌ | 10 | Extra space in px before the separator. |
{ "type": "divider", "dividerType": "DOTTED", "offset": 10 }feed — Paper Advance
cut to fully exposethe printed content past the tear edge.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
lines | Integer | ❌ | 1 | Number of blank lines to advance. |
{ "type": "feed", "lines": 3 }space — Pixel-Precise Spacing
feedfor fine adjustments between receipt elements.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
pixels | Integer | ❌ | 10 | Pixels of blank space to insert. |
{ "type": "space", "pixels": 20 }cut — Paper Cut
On cutterless terminals (e.g., Sunmi V2) the command is silently ignored.
{ "type": "cut" }image — Base64 Image
in the receipt header.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
base64Image | String | ✅ | — | Raw Base64 string. Do not include the data:image/...;base64, prefix. |
align | LEFT | CENTER | RIGHT | ❌ | CENTER | Image alignment. |
width | Integer | ❌ | — | Max width in px. Sunmi P3 / P2 SE support up to 384 px. |
algorithm | BINARIZATION | DITHERING | ❌ | DITHERING | BINARIZATION: maximum sharpness for logos. DITHERING: simulates grayscale for photos. |
Send only the raw Base64 string. Including the data:image/png;base64,
prefix will cause the image to fail silently.
{
"type": "image",
"base64Image": "iVBORw0KGgoAAAANSUhEUgAAAAo...",
"align": "CENTER",
"width": 384,
"algorithm": "BINARIZATION"
}qr — QR Code
no image rendering required. Faster and higher-density than sending a
pre-rendered bitmap.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
content | String | ✅ | — | URL or text to encode. |
dotSize | Integer | ❌ | 8 | Size in px of each QR module. Affects the total code size. |
errorLevel | L | M | Q | H | ❌ | L | Error correction: L=7% · M=15% · Q=25% · H=30%. |
align | LEFT | CENTER | RIGHT | ❌ | CENTER | Horizontal alignment. |
{
"type": "qr",
"content": "https://yourstore.com/receipt/4421",
"dotSize": 6,
"errorLevel": "M",
"align": "CENTER"
}barcode — CODE128 Barcode
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
content | String | ✅ | — | Data to encode (e.g., UPC, invoice number). |
align | LEFT | CENTER | RIGHT | ❌ | CENTER | Horizontal alignment. |
width | Integer | ❌ | 3 | Width of each vertical bar in points. |
height | Integer | ❌ | 162 | Total barcode height in px. |
{
"type": "barcode",
"content": "A-1234567890",
"align": "CENTER",
"width": 2,
"height": 162
}Idempotency
Reuse the same printJobIdon retries to prevent duplicate prints.
The terminal deduplicates byprintJobId.
Request
Path Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://api-uat.kushkipagos.com/terminal/v1//sync/print/job' \
--header 'Content-Type: application/json' \
--data '{
"printJobId": "CUST-TICKET-001",
"commands": [
{
"type": "text",
"text": "RECIBO DE PAGO\n",
"align": "CENTER",
"size": 28,
"bold": true
},
{
"type": "feed",
"lines": 3
},
{
"type": "cut"
}
]
}'Response Response Example
202 - default
{
"printJobId": "CUST-TICKET-001",
"status": "PENDING",
"message": "Impresión encolada correctamente."
}Modified at 2026-06-09 20:34:29