Documentation

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 being published. Contact us if you need the OpenAPI specification in the meantime.

OpenAPI enables you to integrate more quickly through the use of code generators such as OpenAPI Generator and Swagger Codegen.

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://.

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
  • 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}"'

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