User Guide

API Documentation

Welcome to the Print Trail API documentation, designed for developers who wish to create an integration.

👉 We recommend you read the sections describing how orders and fulfilments work.

OpenAPI

The Print Trail API is a REST API.

A full OpenAPI (formerly Swagger) description of the API is available (OpenAPI 3.0.3):

Contact us if you have any questions.

OpenAPI enables you to integrate more quickly through the use of code generators such as OpenAPI Generator and Swagger Codegen. You can also load the specification into viewers such as Swagger UI or ReDoc to browse the endpoints interactively.

The specification covers the full set of endpoints, including a lightweight POST /test-connection check to verify your credentials, a GET /stock-levels endpoint that returns compact per-SKU stock for all of your published products in a single call, and a POST /products/validate-skus endpoint for bulk-validating external SKUs against Print Trail products without pulling the full stock feed.

When creating an order, an optional strictSkus flag on POST /orders rejects the whole order (422) if any line references an unmatched SKU, instead of silently dropping that line — useful for integrations that want mapping mistakes to fail fast. See the OpenAPI specification for the exact request and response shapes.

API Credentials

The Print Trail API uses bearer authentication.

To use the Print Trail API, you must first generate API credentials.

Creating API credentials

API credentials are created per channel.

  1. In the Print Trail app go to Settings > Channels where you can either select an existing channel or create a new channel.
  2. In the channel’s ‘API Integration’ panel, click the ‘Create API credentials’ button.
  3. A ‘Channel ID’ and ‘API Secret’ will be created (click the eye icon to see the API secret).

These API details are per channel. Each integration will require a new channel, e.g. one per third-party e-commerce site or app.

Using API credentials

Authenticate each request by sending a bearer token in the Authorization header:

Authorization: Bearer <your API Secret>

Your Channel ID and API Secret are shown in the channel’s API Integration panel (see Creating API credentials).

Webhooks

Webhooks are machine-to-machine notifications sent from Print Trail to your apps or e-commerce stores, for instance when an order’s state changes.

Webhooks are particularly useful for asynchronous events like when a fulfilment has shipped, or a tracking link has been added to a fulfilment.

To configure webhooks

  1. To configure webhooks you must first enable the Print Trail API on a channel – see Creating API credentials.
  2. Once API credentials are enabled for a channel, the ‘API integration’ panel will be visible on that channel in Print Trail.
  3. In the ‘API integration’ panel, there is a ‘Webhook endpoint URL’ field – enter the URL at which you wish to receive webhook notifications.

⚠️ Webhooks are sent per channel, i.e. webhooks are sent to a channel’s configured endpoint only for orders created within that channel.

Webhook events

Webhooks are sent to a channel’s webhook URL when:

  • A fulfilment is one of: dispatched, returned, invalid, cancelled, failed, back-order (in general, when a fulfilment’s status changes).
  • Tracking details are added to a fulfilment.
  • An order is one of: holding, processing, complete, cancelled, back-order, returned, invalid, error, partial (in general, when an order’s status changes).

👉 Webhooks are only sent for a channel when the channel has a webhook URL configured - must be a valid URL starting with https://.

Re-requesting a webhook

If your endpoint missed or failed to process an order webhook, you can ask Print Trail to send it again using the resend endpoint (POST /webhooks/resend) with the order’s UUID and the event type. Only order-level events (order-created / order-status-updated) can be re-requested. See the OpenAPI specification for the exact request and response shapes.

Webhook payload

The payload consists of some common details, and some additional details provided by the event.

The common details are:

  • tenantCode - Note: ‘tenant’ and ‘team’ have the same meaning
  • channelCode
  • orderUuid
  • orderNumber - your own order reference, as supplied when the order was created
  • message - a user-oriented description of what has happened.
  • createdAt
  • updatedAt
  • originalStatus
  • currentStatus

For orders, the message template is:

Order "{orderNumber}" status has changed from "{originalStatus}" to "{currentStatus}"'

When tracking details are added to a fulfilment, each tracking-detail object includes both the newer, recommended keys – carrier, trackingNumber, trackingUrl – and the legacy keys – courier, number, url. The two sets hold the same values; prefer the newer keys in new integrations.

Webhooks should be interpreted as a prompt to fetch the full details for the relevant resource (fulfilment and/or order).