PRINTMOTOR API

We provide a RESTful API for sending print orders for production and delivery.

Signup!

How does it work?

Your online store sends orders through the Printmotor RESTful API, then we print the orders and ship them to your customers.

Scroll down for the full Printmotor API documentation to help you set up your service.

Overview

Information here is for customers using the Printmotor API.

  • All communication is implemented over HTTPS
  • Data is JSON
  • Each sent HTTP(S) request needs authentication headers

Endpoints

  • Production: https://api.printmotor.io/api/v1
  • Development: https://test.printmotor.io/api/v1

Authentication

There are two things that needs to be told to Printmotor API in order to perform successful requests:

  1. Which service you are using
  2. Who are you

Service recognition

You can define more than one service in Printmotor. Each service has their own user database, own print layouts and own products. For example, one could define services “Post card service” and “Poster service” to Printmotor, and while performing requests to Printmotor these services must be determined. This is done by setting a request header to all incoming requests:

X-Printmotor-Service: servicepublicidentificator

User authentication and authorization

Most of the endpoints are available only for registered users. When sending requests to Printmotor, it’s good practice to define user information to all requests even if they are open to public.

For each controlled request, you must provide an authentication with basic authentication. That is, each request must hold a username-password as base64 encoded in Authentication-HTTP request header.

How to get username and password

Please contact sales@printmotor.io for access credentials.

Error handling

API provides corresponding HTTP status code based on request status.

Billing

Printmotor API billing is postpaid – Printmotor will send an invoice to you each month. Every user order that is sent to Printmotor will automatically go into production, and will be delivered to the customer.

When you agree to the Terms of service on this website, you agree that each request will automatically be printed and shipped to the customer.

Customization

Currently you can define offline paper type, size and orientation and dynamic fields. In the future, this will available via a web based interface also. You can create a layout with changing text, PDF, image etc. – when performing an order, just define dynamic values as request variables and Printmotor takes care of the rest.

Address

Methods
URI
Description
POST

/api/v1/address

Adds an address to user's address book
Details
GET

/api/v1/address

Gets all user's addresses in a list. If no addresses are yet set, an empty response is returned.
Details
DELETE

/api/v1/address/{addressId}

Deletes given address from user's address book. Returns a true/false response, telling if deletion was successful or not. User can delete her addresses even if there are already orders performed to this address - deleting this address will not affect these orders in any way.
Details
GET

/api/v1/address/{addressId}

Returns single address with a given address id
Details

Country

Methods
URI
Description
GET

/api/v1/country

Returns all countries available for delivery
Details

Layout

Methods
URI
Description
POST

/api/v1/layout/search

Searches for layouts based on a name
Details

Order

Methods
URI
Description
POST

/api/v1/order
/api/v1/orders

Places a new order. Please prefer "/api/v1/orders" over "/api/v1/order.
Details
GET

/api/v1/order/{orderNumber}
/api/v1/orders/{orderNumber}

Get order status. Please prefer "/api/v1/orders" over "/api/v1/order.
Details
GET

/api/v1/orders

Get orders
Details

Version

Methods
URI
Description
GET

/api/v1/version

Returns version as a string
Details

Order one item to specific address

To make an order, you need to perform an HTTP POST to the userorders resource.

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

  • Authentication in request headers
    • We’ll provide you with the credentials
  • Customer name.
    • Typically, you should provide firstName and lastName
    • When applicable, an ID alone can be provided (for example, in the case of existing user orders, repeat orders etc.)
  • Delivery address
    • If this is a predefined address, the address ID can be provided
    • Typically, address details are provided
  • Product information: this is an array of “products”, each defining:
    • layout
      • Defines which layout should be used
      • Determines page (print) size, available fields, etc.
      • Either a UUID of a layout or a name that will be used to search for the appropriate layout
        • UUID refers to a single layout
        • When a name is provided, the first layout matching this name will be used
      • ID is available via the layout search resource or from the partner web interface
    • amount of ordered packs/units
      • For posters this is typically the number of units required
      • For items like postcards this is the number of packs – e.g. 2 means two boxes of postcards, each containing 25 cards
    • customization means the possible customisations for this layout. This is an array of customisation objects, each defining a single customisation – e.g. a string or an image
      • id determines the UUID for the field to be customised. This information is available through a layout search (page field ID) or through the web interface. If a name is provided, the first field matching that name will be used for customisation
      • determines the customisation value: for strings, this is the input value, for images it is the internet-fetchable absolute URL value
      • value determines the customisation value: for strings, this is the input value, for images it is the internet-fetchable absolute URL value
{
  "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" : [ {
    "layout" : "api-poster-30x40",
    "amount" : 1,
    "customization" : [
        {
          "name" : "imagefile",
          "value" : "https://my.image.bank.com/images/3a140734-272d-43fc-8048-5adb970df8a5.png"
        } ]
  } ]
}

Webhooks

Printmotor provides the possibility to configure one or more webhooks.

You can receive notifications by defining an HTTP or HTTPS server address where Printmotor will POST a request.

Currently you can receive notifications when an order is created and/or when it is produced and delivered from Printmotor’s facilities. The latter notification will also include a tracking code for the parcel if required by your systems.

Here is an example of what an event looks like:

{
    "eventType":"USER_ORDER_DELIVERED",
    "userOrder":{
        "orderNumber":9156,
        "meta":{
            "trackingCode":"RE402891561SE"
        },
        "estimatedDeliveryTime":"2015-10-03T12:00",
        "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 facilities.

Webhook HTTP request is a HTTP 1.1 POST 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.

MAC

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 webhook.

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 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