Printmotor API

Setting up

Setting up the API is easy. All you need are your credentials, service key and the data for the order and you're set! Follow the instructions below for guidance. If you have trouble, send a message through the chat box or hit up our customer support. We'll be happy to help!

Authorisation credentials

Once you've signed up, you'll be pending for verification by the Printmotor team. While unverified, the test credentials can be used to authorise your app. Make sure to be using the right combination of credentials. Once your account has been verified, whenever you send an order with production credentials will be automatically processed, shipped and charged from your account.

Service Key

Provide the Service Key in the header of the post request in the key X-Printmotor-Service. Service key defines which service is being used. Include this header in all requests sent to Printmotor. You get a Service Key for your service while creating an account, and it's visible in partner admin, too.

X-Printmotor-Service: your-service-key

Authorisation

Each request is required to be authorised to prevent just anyone from changing your information. This defines who is accessing the API. You can access the API with either test or production credentials.

Authorization is done using HTTP Basic authentication. That means that in addition to X-Printmotor-Service-request header you need to specify a Authorization header in your request. You may generate the header value below by typing your user name and password.

Verification

You'll receive an email when your account has been activated for production. The status of your service is visible in partner admin as well.

API Calls

Printmotor API endpoint is

https://api.printmotor.com/api/v1

Printmotor has just a couple of key API Calls, most important being the POST and GET Orders. Below you can find the API calls listed. For more information on the parameters and responses, check out the Examples.

POST /orders

Send orders to Printmotor for production. Requires JSON data request payload.

GET /orders

Fetch all the orders from specified range

GET /orders/{#order}

Fetch a single order with the given order number.

PATCH /orders/{#order}

Patches existing order information. Note that due to technical and production related details only delivery address and recipient information can be patched at the moment. An order can be patched until it's been processed at Printmotor - after that a bad request response (400) is returned.

DELETE /orders/{#order}

Cancels an order. Cancelling an order is possible until it's been processed at Printmotor - after that a bad request response (400) is returned.

GET /country

Simple request to fetch all the countries.

GET /version

Will return the version of the api as a string. No authorisation required.

Content

Printmotor uses JSON to receive order requests. Data type of the data being sent in the request must be defined in the header.

Content-Type: application/json

Fields

These are the most basic components of the JSON file. More detailed information on the fields below can be found at Fields.

Customer section

Information on the customer who purchased the products. If you don't have first and last names separated, you may put the whole recipient name in lastName-field.

"orderer": {
    "firstName": "string",
    "lastName": "string",
    "emailAddress": "string",
    "phone": "string"
}

Address section

Address information is sent to the carrier.

"address": {
    "address": "string",
    "postalArea": "string",
    "postalCode": "string",
    "countryIso2": "string"
}

Products section

Type of product being ordered and the print to be used for customized products.

"products": [
    {
        "product": "matt-poster",
        "size": "50x70",
        "amount": 1
        "image": "https://my.image.bank/img/image-name.png"
    }
]

Putting the requests together

We'll be using a curl commands in this example, but it will easily translate to other languages that you might be using.

Note that using curl's --user username:password will leave your credentials in the terminal log. For better safety practice, please look into converting your credentials into base64 Basic Authentication.

Curl terms in case

Provide the Service Key in the header of the post request in the key X-Printmotor-Service. This defines which service is being used.

Attribute Description
Request method -X
Request header -H, --header
Basic authentication -u, --user
Request payload data -d, --data
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic Q29uc9RxeTVudGURW4u5mecx" \
  -H "X-Printmotor-Service: t2fbd06buR8a69cr6cee4d7abfd75" \
  -d @../data/order.json \
     "https://api.printmotor.com/api/v1/orders"
curl -X POST \
  -u username:password \
  -H "Content-Type: application/json" \
  -H "X-Printmotor-Service: t2fbd06buR8a69cr6cee4d7abfd75" \
  -d {...}  \
     "https://api.printmotor.com/api/v1/orders"

Fields and attributes

Below, you can find the fields needed to send an order to Printmotor.

Orderer

This field has all the information needed on the user that sent the order. It contains all their contact information in the occurrence that there is a problem with the order, or if the delivery has not been picked up. Information will be sent to carrier.

"orderer" : {
  "firstName": "string",
  "lastName": "string",
  "emailAddress": "string",
  "phone": "string"
}
Attribute Description
firstName User's first name, when given separately from last name.
lastName
Required field
Required field. Can also be used as the whole name.
emailAddress
Required field
Will be used to contact customer if there are any issues with the production of the items.
phone
Required field
Will be passed onto the carrier for contact during delivery. Please use international format, e.g. +358 50 1234 567

Address

Information on the place to send the product to. In the case that the recipient is different from the orderer's details, you can override those details here.

"address": {
  "recipientCompanyName": "string",
  "recipientName": "string",
  "recipientPhone": "string",
  "address": "string",
  "address2": "string",
  "state": "string",
  "postalArea": "string",
  "postalCode": "string",
  "countryIso2": "string"
}
Attribute Description
recipientCompanyName Recipient company name
recipientName Name of the person to receive the order, if different from one in orderer object.
recipientPhone Phone number for contact during , if different from one in orderer object.
address
Required field
Address to be delivered to. Required.
address2 Address line 2 in case it's needed.
postalArea
Required field
City. Required.
postalCode
Required field
Also known as Zipcode. Required.
countryIso2
Required field
A two letter country code in ISO-3166-2 format.

Products

An array of product objects, to be manufactured and sent to customer. In the simplest form you may only need a product and wanted size and/or color. In addition to that, when agreed with Printmotor you may refer to customized print layout, with one or more customizable input data.

Each order may contain one or more products.

See products and pricing.

"products": [
  {
    ... product1 ...
  },
  {
    ... product2 ...
  }
]
{
    "product": "matt-poster",
    "image": "https://..../filereference.png"
}
{
  "product": "matt-poster",
  "size": "30x40",
  "layoutName": "custom-layout-30x40",
  "amount": 2,
  "customization": [
    {
      "fieldName": "topText",
      "value": "Cool poster!"
    },
    {
      "fieldName": "backgroundImage",
      "value": "https://..../filereference.png"
    }
  ],
  "endUserPrice": {
    "priceValue": 40,
    "currencyIso4217": "EUR"
  }
}
Attribute Description
product
Required field
Name of the product.
amount Number of units/packages. For products that come in packages, amount refers to the package. Check out the admin page for more information on the amount of units in a package. In case of t-shirts or posters this is the amount of shirts or posters, but e.g. for 25-pack postcard products this is amount of wanted packs. Defaults to 1 unit/package.
color Wanted color name. Required in some products, e.g. for t-shirts.
size Wanted size name. Required in most of the products, e.g. for posters and t-shirts.
image HTTP(S)-URL to high-resolution printfile. PNG format is highly recommended.
pdf HTTP(S)-URL to print-ready PDF. PDF format 1.4A or higher is required. Usage of 3 mm bleeds is highly recommended with posters with non-white backgrounds.
layoutName Name of the layout chosen. If not given, product's referenced layout is chosen.
customization Defines the customization of the layout in case of a customized layout.
customization.fieldName The name of the customizable field, depending on referenced layout. E.g. image, top-text or similar.
customization.value The value for the customized field. In case of a binary reference (image, PDF), complete HTTP(S) URL is required.
endUserPrice.priceValue
Required field
Currency value of product to be printed on label for customs. This should match the value of the product - in most cases being the amount that user has paid for the product.
endUserPrice.currencyIso4217
Required field
Standard currency code for currency where customer has bought the product. This information is printed to customs labeling when necessary.

Meta Data

These fields explain a little more on the order's details. In meta-section you can e.g. define your own order/reference number which is then shown in our partner admin together with Printmotor's order number.

When you get an order object as a response to your order query or order placement request, meta-block may contain information about package's tracking code and tracking links.

"meta" : {
  "reference" : "string",
  "trackingCode" : "string",
  "externalTrackingLinks" : [
    {
      "id" : "string",
      "title" : "Customized title",
      "absoluteUrl" : "string"
    }
  ]
}
Attribute Description
reference Defines which order is being referenced to in your own system.
trackingCode Only in response - the tracking code for this order. Depending on carrier, this information is not always right after placing order, but after order is produced and shipped by Printmotor. You can use webhooks to get notified when package is shippped - then tracking code known.
externalTrackingLinks Only in response - when present, contains hyperlinks for track the order. Especially in postal network different tracking services give different tracking information.

Postal Details

Use optional fields postalClass and productionClass to determine express shipping or high speed production.

    "postalClass" : "PRIORITY",
    "productionClass" : "REGULAR"
Attribute Description
postalClass When present, value of either PRIORITY or EXPRESS. Shipping prices can be found from Printmotor's web site.
productionClass When present, a value of either REGULAR and HIGH. High production class orders cost more, but they're printed the next day from receiving the order.

Additional Features

Use an optional field array additionalFeatures that holds 0-n additionalFeature objects. These are used to describe custom, additional features for an user order. E.g. if one would like to Printmotor to include a small note with the product, or request posters to be shipped in a tube with different color, they'd be described as user order's additional features. For detailed instructions please contact Printmotor support.

    "additionalFeatures": [
        {
            "type": "matt-a6-note-landscape",
            "customValue": "https://link-to-server/path/printready-a6-12345.pdf"
        }
    ]
Attribute Description
type Specifies the type of the requested additional feature.
customValue Specifies feature customization when necessary - depending on the requested additional feature. E.g. a PDF-file URL for a printed paper note. E.g. for a black poster tube this value is optional.

Examples

Order one item to specific address

If you'd like to make one custom order, you should perform a HTTPS POST to /orders.

    {
      "orderer": {
        "firstName": "Firstname",
        "lastName": "Lastname",
        "emailAddress": "my.name@mydomain.com",
        "phone": "+358301234567",
      },
      "address": {
        "address": "Street address",
        "address2": "extended street address",
        "postalArea": "01234",
        "postalCode": "Stockholm",
        "countryIso2": "SE"
      },
      "products": [
        {
          "product": "matt-poster",
          "size": "70x100",
          "amount": 1,
          "pdf": "https://url.to.high.res/file.pdf"
        }
      ]
    }        

When a new order request should be sent, the following information needs to be told:

Authentication

You will receive credentials from us. Make sure to add them in the request headers

Orderer

Contact information on the customer. Commonly provide firstName, lastName, emailAddress and phone.

Address

Common address details are supplied. Includes address, postalArea, postalCode and countryIso2 which is the country code.

Products

Array of products that have been ordered. A product has attributes that are needed for Printmotor to know the detailed information of the product to be produced.

product

Defines which product should be ordered.

size

Defines which product size - poster size in this case.

amount

Posters and textiles: the amount of units to be produced.

Others (e.g. post cards, business cards) this is the amount of packages; e.g. "2" will deliver two packages of post cards, each containing 25 cards. Contact support for more information on the different packages.

pdf

Reference to a high-resolution PDF-file with 3 mm bleeds. If you have a PNG file, use image-field instead.

More information can be found at Fields and Attributes

Fetch an order

To fetch one specific order, you should perform a HTTPS GET to /orders/{ordernumber} with the orderNumber being the number of that order from Printmotor.

This is an imaginary response for an order.

 {
    "orderNumber": 84621,
    "meta": {
        "reference": "myservice-12345",
        "trackingCode": "RS072596432DE",
        "externalTrackingLinks": [
            {
                "title": "Aftership DHL Germany tracking",
                "absoluteUrl": "https://track.aftership.com/dhl-germany/RS072596432DE"
            }
        ]
    },
    "deliveryTime": "2021-05-14T10:16:16.706",
    "processingStatusDescription": "In production",
    "postalClass" : "PRIORITY"
}
Attribute Description
orderNumber Order number in Printmotor's system
trackingCode Tracking code for package once it is shipped out.
deliveryTime If the order has been delivered, this field will display the time it was sent out.
estimatedDeliveryTime Restimated arrival time in Finnnish timezone.
processingStatusDescription Short description of the process the order is going through
postalClass Postal class of the order. Either PRIORITY or EXPRESS.

Webhooks

Printmotor provides a possibility to configure on or more webhooks. You may get notifications by defining a HTTPS server address where Printmotor will POST a HTTP request e.g. when order is shipped from Printmotor facilities.

Currently you may get notifications when user order is created and/or when it's produced and shipped from Printmotor. The latter one will also include a tracking code for the parcel, if that's needed e.g. by your own systems or email communications.

Here's an example what an event payload looks like:

{
    "eventType":"USER_ORDER_DELIVERED",
    "userOrder":{
        "orderNumber":9156,
        "meta":{
            "trackingCode":"RE402891561SE"
        },
        "processingStatusDescription":"In production",
        "postalClass":"PRIORITY"
    }
}
  • There are two difference eventTypes:
    • USER_ORDER_CREATED
    • USER_ORDER_DELIVERED
  • userOrder is similar to what you get if you request for order information

Webhook HTTP request

Each webhook event is sent as soon as possible, normally in seconds after the event has happened at Printmotor.

Webhook HTTP request is a HTTPS 1.1 POST request to given address. Webhook destination server have ten seconds time to answer to request. If it takes longer, event sending is considered as failed.

Also if server responses with HTTP status that's not between 200 and 299, event sending is failed.

Validating Printmotor webhook - MAC calculation

Each request contains a X-Printmotor-Hmac-SHA256 custom header that contains a SHA-256 digest of given payload, initialized with shared private key. With this value webhook destination may calculate a hash from received payload and compare it to received one, to make sure that Printmotor is the origin of a webhook content.

Webhook HTTP response

For a successful processing of a hook, server should return a valid HTTP response with status code between 200 and 299. The returned payload or content type doesn't matter, but it shouldn't be more than one kilobyte long.

Resends

If a webhook sending fails, Printmotor will try to resend hook at most 15 times. After 15 attempts event is discarded.

The first redelivery will happen after approximately one minute of the first one. If this one fails too, two minutes from the original time is waited. If this one also fails, four minutes is waited and so on. Below is a list of waiting times as a function of attempts:

  • redelivery attempt #1: 1 minute
  • redelivery attempt #2: 2 minutes
  • redelivery attempt #3: 4 minutes
  • redelivery attempt #4: 8 minutes
  • redelivery attempt #5: approx. 15 minutes
  • redelivery attempt #6: approx. 30 minutes
  • redelivery attempt #7: approx. 1 hour
  • redelivery attempt #8: approx. 2 hours
  • redelivery attempt #9: approx. 4 hours
  • redelivery attempt #10: approx. 8 hours
  • redelivery attempt #11: approx. 16 hours
  • redelivery attempt #12: approx. 1,5 days
  • redelivery attempt #13: approx. 3 days
  • redelivery attempt #14: approx. 5 days
  • redelivery attempt #15: approx. 11 days
  • after failed 15th attempt webhook event is cancelled and ignored.