Print Cloud

The Print API (Cloud) lets your POS control the thermal printer on the SmartPOS terminal through Kushki's cloud relay. You send an ordered array of print commands, the terminal executes them, and reports the result via webhook or polling.

Print jobs are asynchronous — the terminal returns 202 Accepted immediately and delivers the final status after printing completes.

Beta — Early Access

The Print API is in Beta for Peru 🇵🇪. Do not deploy to production without coordinating with the Kushki integration team.

Base URL and endpoint pattern

Environment	Base URL
Production	`https://cloudt.kushkipagos.com`
UAT	`https://uat-cloudt.kushkipagos.com`

POST /terminal/v1/{terminalSerial}/sync/print/job
POST /terminal/v1/{terminalSerial}/sync/print/job_status

Authentication

Available operations

Operation	Endpoint	Description
Create Print Job	`POST /sync/print/job`	Queue a print job — returns `202 Accepted` immediately
Get Print Job Status	`POST /sync/print/job_status`	Poll the current status of a queued job

Create Print Job

Request

{
  "printJobId": "RECEIPT-20260101-001",
  "webhookUrl": "https://pos.micomercio.com.pe/webhooks/print",
  "skipIfBusy": false,
  "commands": [
    {
      "type": "text",
      "text": "MI COMERCIO PERÚ\n",
      "align": "CENTER",
      "size": 32,
      "bold": true
    },
    {
      "type": "text",
      "text": "RUC: 20100000001\n",
      "align": "CENTER",
      "size": 20
    },
    {
      "type": "divider",
      "dividerType": "SOLID"
    },
    {
      "type": "text",
      "text": "Fecha: 01/01/2026  Hora: 14:32\n",
      "align": "LEFT",
      "size": 20
    },
    {
      "type": "divider",
      "dividerType": "DOTTED"
    },
    {
      "type": "columns",
      "columns": [
        { "text": "Producto A", "weight": 2, "align": "LEFT" },
        { "text": "S/ 500.00",  "weight": 1, "align": "RIGHT" }
      ]
    },
    {
      "type": "divider",
      "dividerType": "SOLID"
    },
    {
      "type": "columns",
      "columns": [
        { "text": "TOTAL",    "weight": 2, "align": "LEFT", "bold": true },
        { "text": "S/ 500.00", "weight": 1, "align": "RIGHT", "bold": true }
      ]
    },
    {
      "type": "text",
      "text": "APROBADO\n",
      "align": "CENTER",
      "size": 28,
      "bold": true
    },
    {
      "type": "qr",
      "content": "https://micomercio.com.pe/recibo/001",
      "dotSize": 6,
      "errorLevel": "M",
      "align": "CENTER"
    },
    {
      "type": "feed",
      "lines": 4
    },
    {
      "type": "cut"
    }
  ]
}

Response

{
  "print_job_id": "RECEIPT-20260101-001",
  "status": "PENDING"
}

Get Print Job Status

Request

{
  "print_job_id": "RECEIPT-20260101-001"
}

Response

{
  "print_job_id": "RECEIPT-20260101-001",
  "status": "COMPLETED"
}

Status	Description
`PENDING`	Job queued — not yet printed
`COMPLETED`	Printed successfully
`FAILED`	Printing failed — check `errorCode`

Command types

`type`	Description
`text`	Text line — size, alignment, bold, italic, underline
`columns`	Multi-column row — proportional widths, ideal for item/price lines
`divider`	Full-width separator: `SOLID`, `DOTTED`, or `EMPTY`
`feed`	Advance paper N blank lines
`space`	Pixel-precise vertical whitespace
`cut`	Trigger the auto-cutter
`image`	Base64-encoded PNG/JPG — max 384 px wide
`qr`	QR code generated natively in hardware
`barcode`	CODE128 barcode generated natively in hardware

Best practices

Practice	Reason
Always end with `feed` (≥ 3 lines) + `cut`	Ensures content clears the tear edge before cutting
Always set `printJobId`	Enables idempotent retries — terminal deduplicates by this ID
Set `skipIfBusy: false` for payment receipts	Prevents a busy queue from discarding the receipt
Use `qr` / `barcode` over `image` for codes	Native hardware generation is faster and higher density
Use `BINARIZATION` algorithm for logos	Sharper edges on monochrome thermal paper
Set HTTP timeout ≥ 15 s	Cloud relay adds latency before the `202` response

Got a suggestion on this documentation? Contact us.

Base URL and endpoint pattern#

Authentication#

Available operations#

Create Print Job#

Request#

Response#

Get Print Job Status#

Request#

Response#

Command types#

Best practices#

Base URL and endpoint pattern

Authentication

Available operations

Create Print Job

Request

Response

Get Print Job Status

Request

Response

Command types

Best practices