Print API
The Print API enables document printing functionality in your POS UI extension. Use this API to trigger the native print dialog for your documents.
Supported document types:
- HTML documents (
.html,.htm) - Best printing experience with full CSS styling, embedded images, and complex layouts. Use for receipts, invoices, and formatted reports. - Text files (
.txt,.csv) - Plain text with basic content and tabular data support. Use for simple receipts and data exports. - Image files (
.png,.jpg,.jpeg,.gif,.bmp,.webp) - Common web formats with format-specific optimizations. Use for logos, charts, QR codes, and barcodes. - PDF files (
.pdf) - Behavior varies by platform: prints directly on iOS/desktop, but downloads to external viewer on Android. Use for complex documents and compliance requirements.
Use cases
- Custom receipts: Print custom receipts or invoices with branded formatting.
- Labels: Generate and print shipping labels or return labels.
- Reports: Create printed reports for sales analytics or inventory counts.
- Custom workflows: Implement custom printing workflows for specialized business processes.
Supported targets
- pos.
customer-details. action. menu-item. render - pos.
customer-details. action. render - pos.
customer-details. block. render - pos.
draft-order-details. action. menu-item. render - pos.
draft-order-details. action. render - pos.
draft-order-details. block. render - pos.
home. modal. render - pos.
home. tile. render - pos.
order-details. action. menu-item. render - pos.
order-details. action. render - pos.
order-details. block. render - pos.
product-details. action. menu-item. render - pos.
product-details. action. render - pos.
product-details. block. render - pos.
purchase. post. action. menu-item. render - pos.
purchase. post. action. render - pos.
purchase. post. block. render
Supported targets
- pos.
customer-details. action. menu-item. render - pos.
customer-details. action. render - pos.
customer-details. block. render - pos.
draft-order-details. action. menu-item. render - pos.
draft-order-details. action. render - pos.
draft-order-details. block. render - pos.
home. modal. render - pos.
home. tile. render - pos.
order-details. action. menu-item. render - pos.
order-details. action. render - pos.
order-details. block. render - pos.
product-details. action. menu-item. render - pos.
product-details. action. render - pos.
product-details. block. render - pos.
purchase. post. action. menu-item. render - pos.
purchase. post. action. render - pos.
purchase. post. block. render
Anchor to propertiesProperties
The object provides properties for triggering document printing. Access these properties through api.print to initiate print operations with various document types.
- Anchor to printprintprint(src: string) => Promise<void>(src: string) => Promise<void>requiredrequired
Triggers a print dialog for the specified document source. The
print()method accepts either:- A relative path that will be appended to your app's application_url
- A full URL to your app's backend that will be used to return the document to print
Returns a promise that resolves when content is ready and the native print dialog appears. Use for printing custom documents, receipts, labels, or reports.
Examples
Print a document from a tile
Description
Trigger the native print dialog directly from a tile interaction. This example demonstrates using `api.print()` to initiate printing from a tile tap, enabling quick access to print functionality for receipts, reports, or other documents without requiring modal navigation.
React
import React from 'react'; import { Tile, reactExtension, useApi, } from '@shopify/ui-extensions-react/point-of-sale'; const TileComponent = () => { const api = useApi(); return ( <Tile title="My app" subtitle="Hello world!" onPress={() => { api.print.print('documents/test-print'); }} enabled /> ); }; export default reactExtension('pos.home.tile.render', () => { return <TileComponent />; });TS
import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My app', subtitle: 'Hello world!', enabled: true, onPress: () => { api.print.print('/documents/test-print'); }, }); root.append(tile); });Print using a relative file path
Description
Print documents using relative file paths within your extension. This example shows how to use `api.print()` with relative URLs to access documents bundled with your extension, ideal for printing static templates, pre-formatted receipts, or embedded resources.
React
// If your application_url is "https://my-app.com" // This will resolve to "https://my-app.com/api/print/document" await print.print('/api/print/document');Print using an external URL
Description
Print documents from external URLs or dynamically generated content. This example demonstrates using `api.print()` with full URLs to print documents hosted externally or generated by your backend, supporting dynamic receipts, invoices, or reports with real-time data.
React
// Using a full URL directly await print.print('https://my-print-service.com/api/print/document');
Anchor to best-practicesBest practices
- Handle printing errors gracefully: Implement proper error handling for print operations, including network failures, unsupported document types, or printer connectivity issues.
- Optimize documents for printing: Design your printable documents with appropriate sizing, margins, and formatting that work well with printers and standard paper sizes.
- Provide user feedback: Give users clear feedback about print operations, including loading states, success confirmations, and error messages when printing fails.
Anchor to limitationsLimitations
- PDF printing on Android devices requires downloading the file and using an external application, which may interrupt the user workflow.
- Print operations depend on device printer connectivity and configuration, which may not be available in all POS setups.
- Document formatting and appearance may vary depending on the printer type, paper size, and device capabilities.