Get started

Introduction

This documentation describes the Printpartnerz API v1.0

Getting started

To get started with Printpartnerz please get in touch with us, and we'll be glad to assist you in getting started.

Basics

RESTful API

The Printpartnerz API is RESTful API. Calls are implemented as HTTP GET or POST. The HTTP response codes 200 and 201 are positive responses, all other response codes must be considered as error. Data will only be returned for HTTP response code 200. Error descriptions can be returned on 4xx response codes.

Request data

All request data posted to the API must be in JSON objects. The documentation for each API call describes the request data parameters in detail.

Return data

Return data from the API is in JSON objects. The documentation for each API call describes the return values in detail.

Content-type

Set content-type to application/json on all requests.

Authentication

Each request to the API contains an API key for authentication. API keys are provided by Printpartnerz.

Sandbox

A separate API key will be provided for testing purposes. For sandboxing change api. in the HTTP requests with sandbox.

Note

Please be advised: every order pushed to the production environment (api. ) will be produced and charged unless cancelled before it is in production.

Product calls

List products

GET https://api.printpartnerz.com/v1/products

Request a list of all enabled products.

Example JSON Request
{
    "apikey": "7ZS9D4NY6eVy3KXfNEkzpN3EnkYSt"
}
Example JSON Response
[
    {
        "name": "Aluminium geborsteld 40x30",
        "sku": "aluminium_geborsteld_40x30"
    },
    {
        "name": "Acrylglas 30x30",
        "sku": "acrylglas_30x30"
    },
    {
        "name": "Aluminium wit 40x40",
        "sku": "aluminium_wit_40x40"
    }
]
Parameters
Name Type Description Required
apikey string API access key required
Return values
Name Type Description
name string Product name
sku string Product number
HTTP status codes
Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing or incorrect credentials

List options

GET https://api.printpartnerz.com/v1/options

Request a list of all enabled options.

Example JSON Request
{
    "apikey": "7ZS9D4NY6eVy3KXfNEkzpN3EnkYSt"
}
Example JSON Response
[
    {
        "name": "Blind ophangsysteem",
        "sku": "blind_ophangsysteem"
    },
    {
        "name": "Voorgemonteerd frame",
        "sku": "voorgemonteerd_frame"
    }
]
Parameters
Name Type Description Required
apikey string API access key required
Return values
Name Type Description
name string Product name
sku string Product number
HTTP status codes
Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing or incorrect credentials

Product info

GET https://api.printpartnerz.com/v1/products/info

Get detailed information on a single product.

Example JSON Request
{
    "apikey": "7ZS9D4NY6eVy3KXfNEkzpN3EnkYSt",
    "sku": "aluminium_geborsteld_40x30"
}
Example JSON Response
{
    "name": "Aluminium geborsteld 40x30",
    "sku": "aluminium_geborsteld_40x30"
}
Parameters
Name Type Description Required
apikey string API access key required
sku string Product number required
Return values
Name Type Description
name string Product name
sku string Product number
HTTP status codes
Code Status Description
200 OK The request has succeeded
204 No content The requested product was not found
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing or incorrect credentials

Order calls

Add order

POST https://api.printpartnerz.com/v1/orders/add

Add a new order including a shipping address, one or more items, options and files.

Note

Files are added with a URL from where Printpartnerz can fetch the files when the order has been accepted. A TLS encrypted HTTPS connection, use of an access key in the query string and use of a network ACL is recommended.

Example: https://mystore.example.com/files/77345809358907345445

Example JSON Request
{
    "apikey": "7ZS9D4NY6eVy3KXfNEkzpN3EnkYSt",
    "reference": "123456",
    "email": "johndoe@example.com",
    "phone": "12345678",
    "whitelabel": false,
    "shippingaddress": {
        "companyname": "My company",
        "firstname": "John",
        "lastname": "Doe",
        "street": "Main street",
        "housenumber": "10",
        "zipcode": "1234 AB",
        "city": "Amsterdam",
        "country": "NL"
    },    
    "orderitems": [
        {
            "reference": "123456-1",            
            "sku": "aluminium_geborsteld_40x30",
            "quantity": 1,
            "file": "https://mystore.example.com/files/77345809358907345445",
            "options": [
                {
                    "sku": "blind_ophangsysteem",
                    "quantity": 1
                }
            ]
        },
        {
            "reference": "123456-2",            
            "sku": "aluminium_geborsteld_90x130",
            "quantity": 2,
            "file": "https://mystore.example.com/files/77345809358907345446",
            "options": [
                {
                    "sku": "voorgemonteerd_frame",
                    "quantity": 1
                }
            ]
        }
    ]
}
Example JSON Response
{
    "reference": "123456",
    "order_id": 278903,
    "shipping_workdays": 3,
    "shipping_date": "07-08-2024",
    "subtotal": 222.66,
    "shippingcosts": 27.25,
    "tax": 52.48,
    "total": 302.39
}
Parameters
Name Type Description Required
apikey string API access key required
reference string Clients own order reference identifier required
email string End customer's email address (used for shipping/delivery purposes) required
phone string End customer's phone number (used for shipping/delivery purposes) optional
whitelabel boolean Indicates whether a shipment has client sender details associated with it. When the boolean is set to false, it signifies that the shipment includes client sender information; when set to true, client sender information will be omitted. optional
shippingaddress array Array of one address object required
shippingaddress : companyname string End customer's shipping company name optional
shippingaddress : firstname string End customer's shipping firstname required
shippingaddress : lastname string End customer's shipping lastname required
shippingaddress : street string End customer's shipping street name required
shippingaddress : housenumber string End customer's shipping housenumber required
shippingaddress : street2 string End customer's shipping street name 2 optional
shippingaddress : housenumber2 string End customer's shipping housenumber 2 optional
shippingaddress : zipcode string End customer's shipping zipcode required
shippingaddress : city string End customer's shipping city name required
shippingaddress : country string End customer's shipping country (ISO 3166-1 alpha-2 code retrieved from List shipping countries) required
orderitems array Array of one or more order item objects required
orderitems : reference string Clients own order item reference identifier required
orderitems : sku string Product number (Retrieved from List products) required
orderitems : quantity integer Number of copies to produce for this specific item required
orderitems : file string URL to the print file - starting with HTTPS
  • Supported files are JPG and PNG
  • Supported maximum width/height is 10000 pixels
  • Don't include bleed and crop marks
 required
orderitems : options array Array of one or more order item options objects optional
orderitems : options : sku string The product option identification number (Retrieved from List options) required
orderitems : options : quantity integer The number of times the specific option is used per item required
Return values
Name Type Description
reference string Clients own order reference identifier
order_id integer Printpartnerz uniquely generated order identifier
shipping_workdays integer Number of workdays for the order to be shipped
shipping_date date Expected date for the order to be shipped
subtotal decimal Product costs for the order
shippingcosts decimal Shipping costs for the order (Shipping costs are a calculated estimate based on the order items. The costs may change later during order processing, especially for more complex orders with multiple items of different sizes.)
tax decimal Tax for the order
total decimal Total costs for the order
HTTP status codes
Code Status Description
201 Created The order registration was created with success
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing or incorrect credentials

Cancel order

POST https://api.printpartnerz.com/v1/orders/cancel

Request cancellation for a specific order.

Note

Orders that have been processed or are currently in production cannot be canceled though the API. The cancellation period is 20 minutes.

Example JSON Request
{
    "apikey": "7ZS9D4NY6eVy3KXfNEkzpN3EnkYSt",
    "order_id": "278903"
}
Example JSON Response
{
    "reference": "123456",
    "state": "cancelled"
}
Parameters
Name Type Description Required
apikey string API access key required
order_id string Printpartnerz uniquely generated order identifier (Retrieved from Add order) required
Return values
Name Type Description
reference string Clients own order reference identifier
state string New state of the order
HTTP status codes
Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing or incorrect credentials
409 Conflict The request failed due to wrong order state
410 Gone The requested order was not found

Order state

GET https://api.printpartnerz.com/v1/orders/state

Request state details for a specific order.

Example JSON Request
{
    "apikey": "7ZS9D4NY6eVy3KXfNEkzpN3EnkYSt",
    "order_id": "278903"
}
Example JSON Response
{
    "reference": "123456",
    "state": "completed",
    "shipping": "created",
    "tracking": "https://postnl.nl/tracktrace/****"
}
Parameters
Name Type Description Required
apikey string API access key required
order_id string Printpartnerz uniquely generated order identifier (Retrieved from Add order) required
Return values
Name Type Description
reference string Clients own order reference identifier
state string State of the order:
  • created
  • processing
  • completed
  • cancelled
  • failed
shipping string | null State of the shipment:
  • created
  • in_sorting
  • ontheway
  • delivered
  • cancelled
tracking string | null Trackinglink for the shipment
HTTP status codes
Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing or incorrect credentials
410 Gone The requested order was not found

Shipping calls

List shipping countries

GET https://api.printpartnerz.com/v1/shipping/countries

Request a list of available shipping countries.

Example JSON Request
{
    "apikey": "7ZS9D4NY6eVy3KXfNEkzpN3EnkYSt"
}
Example JSON Response
[
    {
        "code": "BE",
        "country": "België"
    },
    {
        "code": "NL",
        "country": "Nederland"
    }
]
Parameters
Name Type Description Required
apikey string API access key required
Return values
Name Type Description
code string ISO 3166-1 alpha-2 country code
country string Country name
HTTP status codes
Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing or incorrect credentials