CloudApps API

This documentation describes the CloudApps API v1.0

Getting started

To get started with Cloudprinter please register online here: Client registration

See how to register your app with Cloudprinter.com here: Register your app

Basics

RESTful API

The CloudApps API is RESTful. All API calls are implemented as HTTP 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.

Authentication

CloudApps use OAuth2 authentication method and each request to the API must include a valid Bearer Token. Read more about OAuth2 authentication for CloudApps.

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.

Order calls

List all orders

endpoint

https://api.cloudprinter.com/cloudapps/1.0/orders/

Request a list of all orders

Methods: GET, POST

Example request

json

{}

const axios = require('axios');
const data = JSON.stringify({}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/orders/',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/orders/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/orders/"

payload = json.dumps({}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/orders/' \
--header 'Content-Type: application/json' \
--data '{}
'

Example JSON Response

json

[
    {
        "reference": "12346",
        "order_date": "2015-08-05 10:00:00",
        "state": "1",
        "state_code": "order_state_new"
    },
    {
        "reference": "12348",
        "order_date": "2015-08-05 10:00:00",
        "state": "1",
        "state_code": "order_state_new"
    }
]

Parameters None

Return values

Name	Type	Description
reference	string	the clients own order reference identifier
state	string	the order state. See state definitions
state_code	string	the text version of the order state
order_date	string	the time the order was added

HTTP status codes

Code	Status	Description
200	OK	the request has succeeded
204	No content	the requested order was not found
400	Bad request	the request was invalid or parameters are missing
403	Forbidden	the request was denied due to missing credentials

Get order info

endpoint

https://api.cloudprinter.com/cloudapps/1.0/orders/info

Request details on a specific order

Methods POST

json

{
    "reference": "12346"
}

const axios = require('axios');
const data = JSON.stringify({
    "reference": "12346"
}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/orders/info',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/orders/info',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "reference": "12346"
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/orders/info"

payload = json.dumps({
    "reference": "12346"
}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/orders/info' \
--header 'Content-Type: application/json' \
--data '{
    "reference": "12346"
}
'

Example JSON Response

json

{
  "reference": "123456",
  "state": "45",
  "state_code": "order_state_uploaded",
  "order_date": "2017-02-01 11:22:33",
  "email": "customer1@example.com",
  "is_cancelable": true,
  "addresses": [
    {
      "type": "delivery",
      "firstname": "John",
      "lastname": "Doe",
      "street1": "Example street",
      "zip": "1234",
      "city": "Example city",
      "country": "NL"
    }
  ],
  "items": [
    {
      "reference": "123561",
      "name": "Textbook PB A4 P BW TNR",
      "product_reference": "textbook_pb_a4_p_bw",
      "count": "1",
      "shipping_option": "DHL - National Standard (DE)",
      "tracking": "SA234425244",
      "is_reordable": false,
      "options": [
        {
          "option_reference": "total_pages",
          "note": "The total number of pages in a book",
          "type_name": "Total pages",
          "count": "24"
        },
        {
          "option_reference": "pageblock_80off",
          "note": "Pageblock paper 80gsm Offset",
          "type_name": "Main paper",
          "count": "24"
        },
        {
          "option_reference": "cover_finish_gloss",
          "note": "Cover lamination Gloss finish",
          "type_name": "Cover finishing",
          "count": "1"
        }
      ],
      "files": [
		{
		  "type": "cover",
		  "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
		  "md5sum": "4578c3ecf64e47581b175d542f8b0160"
		},
		{
		  "type": "book",
		  "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
		  "md5sum": "1ef89e74e628e223ae94aa4586330833"
		}
	  ]
    }
  ]
}

Parameters

Name	Type	Description	Required
reference	string	the clients own order reference identifier	required

Return values

Name	Type	Description
reference	string	the clients own order reference identifier
state	string	the order state. See state definitions
state_code	string	the text version of the order state
order_date	string	the time the order was added
email	string	the email address of the end consumer
is_cancelable	boolean	says whether the order can be canceled

Addresses	Type	Description
addresses	array	array of one or more address objects
addresses:type	string	the addres type (delivery)
addresses:firstname	string	firstname of the recipient
addresses:lastname	string	lastname of the recipient
addresses:street1	string	Street
addresses:zip	string	zip
addresses:city	string	city
addresses:state	string	state - ANSI INCITS 38:2009 alpha-2
addresses : country	string	country - ISO 3166-1 alpha-2

Items	Type	Description
items	array	array of one or more item objects
items:reference	string	the clients item reference id
items:name	string	short description of the product
items:product_reference	string	the api reference of the product
items:count	string	the quantity of the item
items:shipping_option	string	the shipping option of the item
items:tracking	string	tracking code of the item
items:is_reordable	boolean	says whether the order can be reordered

Item options	Type	Description
options	array	array of zero or more option objects
options:option_reference	string	the option api reference
options:note	string	short description of the option
options:type_name	string	the name of the option category type
options:count	string	the quantity of the option on the item

Files	Type	Description
files	array	Array of one or more file objects
files : type	string	The type of file
files : md5	string	Md5 sum of the file - used for validation
files : url	string	Url to the order file

HTTP status codes

Code	Status	Description
200	OK	the request has succeeded
400	Bad request	the request was invalid or parameters are missing
410	Gone	the requested order was not found

Add order

endpoint

https://api.cloudprinter.com/cloudapps/1.0/orders/add

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

Note: Files are added with a URL from where Cloudprinter 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 access control list is recomented.

Example: "https://download.example.com/files/28fa76ff5a9e0566eaa1e11f1ce51f09"

Methods POST

Example request

json

{
    "reference": "12346",
    "email": "customer1@example.com",
    "addresses": [
        {
            "type": "delivery",
            "company": "Example company",
            "firstname": "Example firstname",
            "lastname": "Example lastname",
            "street1": "Example street 1234",
            "zip": "99999",
            "city": "Example city",
            "country": "DE",
            "email": "email@example.com",
            "phone": "12345678"
        }
    ],
    "items": [
        {
            "reference": "12346-1",
            "product_reference": "textbook_pb_a4_p_bw",
            "shipping_level": "cp_saver",
            "title": "A great book",
            "count": "5",
            "files": [
                {
                    "type": "cover",
                    "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
                    "md5sum": "4578c3ecf64e47581b175d542f8b0160"
                },
                {
                    "type": "book",
                    "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
                    "md5sum": "1ef89e74e628e223ae94aa4586330833"
                }
            ],
            "options": [
                {
                    "option_reference": "total_pages",
                    "count": "36"
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": "36"
                }
            ]
        }
    ]
}

const axios = require('axios');
const data = JSON.stringify({
    "reference": "12346",
    "email": "customer1@example.com",
    "addresses": [
        {
            "type": "delivery",
            "company": "Example company",
            "firstname": "Example firstname",
            "lastname": "Example lastname",
            "street1": "Example street 1234",
            "zip": "99999",
            "city": "Example city",
            "country": "DE",
            "email": "email@example.com",
            "phone": "12345678"
        }
    ],
    "items": [
        {
            "reference": "12346-1",
            "product_reference": "textbook_pb_a4_p_bw",
            "shipping_level": "cp_saver",
            "title": "A great book",
            "count": "5",
            "files": [
                {
                    "type": "cover",
                    "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
                    "md5sum": "4578c3ecf64e47581b175d542f8b0160"
                },
                {
                    "type": "book",
                    "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
                    "md5sum": "1ef89e74e628e223ae94aa4586330833"
                }
            ],
            "options": [
                {
                    "option_reference": "total_pages",
                    "count": "36"
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": "36"
                }
            ]
        }
    ]
}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/orders/add',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/orders/add',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "reference": "12346",
    "email": "customer1@example.com",
    "addresses": [
        {
            "type": "delivery",
            "company": "Example company",
            "firstname": "Example firstname",
            "lastname": "Example lastname",
            "street1": "Example street 1234",
            "zip": "99999",
            "city": "Example city",
            "country": "DE",
            "email": "email@example.com",
            "phone": "12345678"
        }
    ],
    "items": [
        {
            "reference": "12346-1",
            "product_reference": "textbook_pb_a4_p_bw",
            "shipping_level": "cp_saver",
            "title": "A great book",
            "count": "5",
            "files": [
                {
                    "type": "cover",
                    "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
                    "md5sum": "4578c3ecf64e47581b175d542f8b0160"
                },
                {
                    "type": "book",
                    "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
                    "md5sum": "1ef89e74e628e223ae94aa4586330833"
                }
            ],
            "options": [
                {
                    "option_reference": "total_pages",
                    "count": "36"
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": "36"
                }
            ]
        }
    ]
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/orders/add"

payload = json.dumps({
    "reference": "12346",
    "email": "customer1@example.com",
    "addresses": [
        {
            "type": "delivery",
            "company": "Example company",
            "firstname": "Example firstname",
            "lastname": "Example lastname",
            "street1": "Example street 1234",
            "zip": "99999",
            "city": "Example city",
            "country": "DE",
            "email": "email@example.com",
            "phone": "12345678"
        }
    ],
    "items": [
        {
            "reference": "12346-1",
            "product_reference": "textbook_pb_a4_p_bw",
            "shipping_level": "cp_saver",
            "title": "A great book",
            "count": "5",
            "files": [
                {
                    "type": "cover",
                    "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
                    "md5sum": "4578c3ecf64e47581b175d542f8b0160"
                },
                {
                    "type": "book",
                    "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
                    "md5sum": "1ef89e74e628e223ae94aa4586330833"
                }
            ],
            "options": [
                {
                    "option_reference": "total_pages",
                    "count": "36"
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": "36"
                }
            ]
        }
    ]
}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/orders/add' \
--header 'Content-Type: application/json' \
--data '{
    "reference": "12346",
    "email": "customer1@example.com",
    "addresses": [
        {
            "type": "delivery",
            "company": "Example company",
            "firstname": "Example firstname",
            "lastname": "Example lastname",
            "street1": "Example street 1234",
            "zip": "99999",
            "city": "Example city",
            "country": "DE",
            "email": "email@example.com",
            "phone": "12345678"
        }
    ],
    "items": [
        {
            "reference": "12346-1",
            "product_reference": "textbook_pb_a4_p_bw",
            "shipping_level": "cp_saver",
            "title": "A great book",
            "count": "5",
            "files": [
                {
                    "type": "cover",
                    "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
                    "md5sum": "4578c3ecf64e47581b175d542f8b0160"
                },
                {
                    "type": "book",
                    "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
                    "md5sum": "1ef89e74e628e223ae94aa4586330833"
                }
            ],
            "options": [
                {
                    "option_reference": "total_pages",
                    "count": "36"
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": "36"
                }
            ]
        }
    ]
}
'

Example JSON Response

json

{
    "reference": "12346"
}

Parameters

Name	Type	Description	Required
reference	string	the clients own order reference identifier - this must be unique among all orders	required
email	string	email address of end customer - used for sending tracking information	required
price	string	end customer sales price ex. vat/tax pr item in selected currency - comma as decimal separator, used for customs	optional
currency	string	the currency of the end customer sales price - ISO 4217	optional
hc	string	harmonized code - classify product according to Harmonized System	optional
meta	array	meta data array for custom production parameters - only available for Enterprise clients	optional
mode	string	order mode - valid values are: "live"(real order), "sandbox"(virtual order)	optional

addresses
addresses	array	array of one or more address objects	required
addresses : type	string	the type of address - valid values are: "delivery"	required
addresses : company	string	end customers company name	optional
addresses : firstname	string	end customers firstname	required
addresses : lastname	string	end customers lastname	required
addresses : street1	string	end customers street name	required
addresses : street2	string	end customers street name	optional
addresses : zip	string	end customers zip/postal code	required
addresses : city	string	end customers city name	required
addresses : state	string	end customers state name - ANSI INCITS 38:2009 alpha-2 - required for US and CA	optional
addresses : country	string	end customers country - ISO 3166-1 alpha-2	required
addresses : email	string	end customers email address - used in case of problems during delivery	required
addresses : phone	string	end customers phone number - used in case of problems during delivery	required

files
files	array	array of zero or more file objects	optional
files : type	string	the type of file - valid values are: "delivery_note", "promotion", "reorder_doc"	required
files : url	string	url to the order file	required
files : md5sum	string	md5 sum of the file - used for validation	required

items
items	array	array of one or more item objects	required
items : reference	string	the clients own item reference identifier - this must be unique with in the order	required
items : product_reference	string	the api reference of the product - valid values can be requested via Products Calls	required
items : count	string	the number of copies to produce of this specific item	required
items : shipping_level	string	the preferred shipping level - standard options are: "cp_postal", "cp_ground", "cp_saver", "cp_fast" (required if no "quote" hash is set)	required
items : quote	string	A quote hash reference from a quote call.	optional
items : title	string	the title of the product	optional
items : price	string	end customer sales price ex. vat/tax in selected currency - comma as decimal separator, used for customs	optional
items : currency	string	the currency of the end customer sales price - ISO 4217	optional
items : hc	string	harmonized code - classify product according to Harmonized System	optional
items : reorder_cause	string	reorder cause for reorders - Read more	optional
items : reorder_desc	string	additional description of the problem - Read more	optional
items : reorder_order_reference	string	reference to the original order - Read more	optional
items : reorder_item_reference	string	reference to the item in the original order - Read more	optional

items files
items : files	array	array of one or more file objects	required
items : files : type	string	the type of file - valid values are: "product", "cover", "book"	required
items : files : url	string	url to the product file for the specific item	required
items : files : md5sum	string	md5 sum of the file - used for validation	required

items options
items : options	array	array of zero or more option objects	optional
items : options : option_reference	string	the api reference of the option - "total_pages" required for books	required
items : options : count	string	the number of times the specific option is used pr item	required

Return values

Name	Type	Description
reference	string	the clients own order reference identifier

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

Cancel order

endpoint

https://api.cloudprinter.com/cloudapps/1.0/orders/cancel

Request cancellation of a specific order.

Methods POST

Example request

json

{
    "reference": "12346"
}

const axios = require('axios');
const data = JSON.stringify({
    "reference": "12346"
}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/orders/cancel',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/orders/cancel',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "reference": "12346"
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/orders/cancel"

payload = json.dumps({
    "reference": "12346"
}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/orders/cancel' \
--header 'Content-Type: application/json' \
--data '{
    "reference": "12346"
}
'

Parameters

Name	Type	Description	Required
reference	string	the clients own order reference identifier	required

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 credentials
409	Conflict	the request failed due to wrong order state
410	Gone	the requested order was not found

Order log

endpoint

https://api.cloudprinter.com/cloudapps/1.0/orders/log

Request log data for a specific order.

Methods POST

Example request

json

{
    "reference": "12346"
}

const axios = require('axios');
const data = JSON.stringify({
    "reference": "12346"
}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/orders/log',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/orders/log',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "reference": "12346"
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/orders/log"

payload = json.dumps({
    "reference": "12346"
}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/orders/log' \
--header 'Content-Type: application/json' \
--data '{
    "reference": "12346"
}
'

Example JSON Response

json

[
    {
        "reference": "12346",
        "create_date": "2016-04-12 12:37:01",
        "state": "5"
    },
    {
        "reference": "12346",
        "create_date": "2016-04-12 12:37:02",
        "state": "6"
    }
]

Parameters

Name	Type	Description	Required
reference	string	The clients own order reference identifier	required

Return values

Name	Type	Description
reference	string	The clients own order reference identifier
create_date	string	The date the order was created
state	string	The order state. See state definitions

HTTP status codes

Code	Status	Description
200	OK	The request has succeeded
204	No content	The requested order was not found
400	Bad request	The request was invalid or parameters are missing

Order quote

endpoint

https://api.cloudprinter.com/cloudapps/1.0/orders/quote

Request quote data for a list of items

Methods POST

Example request

json

{
    "country": "NL",
    "items": [
        {
            "reference": "ref_id_1234567",
            "product_reference": "textbook_pb_a4_p_bw",
            "count": "1",
            "options": [
                {
                    "option_reference": "pageblock_80off",
                    "count": "120"
                },
                {
                    "option_reference": "total_pages",
                    "count": "120"
                }
            ]
        }
    ]
}

const axios = require('axios');
const data = JSON.stringify({
    "country": "NL",
    "items": [
        {
            "reference": "ref_id_1234567",
            "product_reference": "textbook_pb_a4_p_bw",
            "count": "1",
            "options": [
                {
                    "option_reference": "pageblock_80off",
                    "count": "120"
                },
                {
                    "option_reference": "total_pages",
                    "count": "120"
                }
            ]
        }
    ]
}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/orders/quote',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/orders/quote',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "country": "NL",
    "items": [
        {
            "reference": "ref_id_1234567",
            "product_reference": "textbook_pb_a4_p_bw",
            "count": "1",
            "options": [
                {
                    "option_reference": "pageblock_80off",
                    "count": "120"
                },
                {
                    "option_reference": "total_pages",
                    "count": "120"
                }
            ]
        }
    ]
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/orders/quote"

payload = json.dumps({
    "country": "NL",
    "items": [
        {
            "reference": "ref_id_1234567",
            "product_reference": "textbook_pb_a4_p_bw",
            "count": "1",
            "options": [
                {
                    "option_reference": "pageblock_80off",
                    "count": "120"
                },
                {
                    "option_reference": "total_pages",
                    "count": "120"
                }
            ]
        }
    ]
}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/orders/quote' \
--header 'Content-Type: application/json' \
--data '{
    "country": "NL",
    "items": [
        {
            "reference": "ref_id_1234567",
            "product_reference": "textbook_pb_a4_p_bw",
            "count": "1",
            "options": [
                {
                    "option_reference": "pageblock_80off",
                    "count": "120"
                },
                {
                    "option_reference": "total_pages",
                    "count": "120"
                }
            ]
        }
    ]
}
'

Example JSON Response

json

{
  "price": "4.5412",
  "vat": "0.00",
  "currency": "EUR",
  "expire_date": "2018-02-18T15:32:58+00:00",
  "subtotals": {
    "items": "1.7912",
    "fee": "2.7500",
    "app_fee": "0.0000"
  },
  "shipments": [
    {
      "total_weight": "712",
      "items": [
        {
          "reference": "ref_id_1234567"
        }
      ],
      "quotes": [
        {
          "quote": "a1e771f2e375bc33b5385fcc8091a328481bc45f3bff13de96ba0e7585ff936f",
          "service": "Postal - Untracked",
          "shipping_level": "cp_postal",
          "shipping_option": "National Post - Int. Postal Untracked",
          "price": "4.2000",
          "vat": "0.0000",
          "currency": "EUR"
        },
        {
          "quote": "90aa928c65b6115e2fd76f5c3238381e42630fbe6cd137422db469fb070b5f7f",
          "service": "Express ground - Tracked",
          "shipping_level": "cp_ground",
          "shipping_option": "National Post - Int. Postal Tracked",
          "price": "6.2300",
          "vat": "0.0000",
          "currency": "EUR"
        },
        {
          "quote": "c6159e6c0a1b3e2d4ad7be940a327fb139351149e9f7ad7a1295a534cc37a4c3",
          "service": "Express fast - Tracked",
          "shipping_level": "cp_fast",
          "shipping_option": "DHL - International Express",
          "price": "14.5000",
          "vat": "0.0000",
          "currency": "EUR"
        }
      ]
    }
  ],
  "invoice_currency": "EUR",
  "invoice_exchange_rate": "1.0000"
}

Parameters

Name	Type	Description	Required
currency	string	the currency of the price quote - ISO 4217 - default value is EUR	optional
country	string	the country the order will ship to - ISO 3166-1 alpha-2	required
state	string	the state in the delivery country - ANSI INCITS 38:2009 alpha-2 - required for US and CA	optional
items	array	array of item objects in the order	required
items : reference	string	client item reference	required
items : product_reference	string	the product api reference	required
items : count	string	the product quantity	required
items : options	array	array of option objects on a item	optional
items : options : option_reference	string	the option api reference	required
items : options : count	string	the option count	required

Return values

Name	Type	Description	Required
price	string	the total product sum for the order, ex shipping and incl VAT	required
vat	string	the vat part of the total product sum	required
currency	string	the currency of the price quote	required
invoice_currency	string	the currency of the invoice for the order	required
invoice_exchange_rate	string	the currency exchange rate between the quote currency and invoice currency	required
expire_date	string	the quote expiration date, 48 hours after the request was made	required
subtotals	array	array of objects - subtotals	required
subtotals : items	string	the sum of the item cost for the order	required
subtotals : fee	string	the sum of the fees for the order	required
subtotals : app_fee	string	the sum of the app fees for the order	required
shipments	array	array of objects - shipments (item bundles)	required
shipments : total_weight	string	the calculated total weight of the shipment	required
shipments : items	array	array of objects - the items contained in this shipment	required
shipments : items : reference	string	the item reference	required
shipments : quotes	array	array of objects - available shipping options	required
shipments : quotes : quote	string	the unique quote id	required
shipments : quotes : service	string	the service level - [Fastest, Normal, Economy]	required
shipments : quotes : shipping_level	string	the shipping service level reference	required
shipments : quotes : shipping_option	string	text description of the specific shipping option	required
shipments : quotes : price	string	the price of the shipment	required
shipments : quotes : vat	string	the vat part of the shipment	required
shipments : quotes : currency	string	the currency of the price quote	required

HTTP status codes

Code	Status	Description
200	OK	the request has succeeded
204	No content	the requested order was not found
400	Bad request	the request was invalid or parameters are missing

Product calls

List all products

endpoint

https://api.cloudprinter.com/cloudapps/1.0/products

Request a list of all products already enabled for the account.

Methods GET, POST

Example request

json

{}

const axios = require('axios');
const data = JSON.stringify({}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/products',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/products',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/products"

payload = json.dumps({}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/products' \
--header 'Content-Type: application/json' \
--data '{}
'

Example JSON Response

json

[
  {
    "name": "Textbook CW A6 P BW",
    "note": "Textbook Casewrap (PUR, 3 mm board) A6 Portrait DIG BW 80OFF",
    "product_reference": "textbook_cw_a6_p_bw",
    "category": "Textbook BW",
    "from_price": "-",
    "currency": "EUR"
  },
  {
    "name": "Textbook CW A5 P BW",
    "note": "Textbook Casewrap (PUR, 3 mm board) A5 Portrait DIG BW 80OFF",
    "product_reference": "textbook_cw_a5_p_bw",
    "category": "Textbook BW",
    "from_price": "-",
    "currency": "EUR"
  }
]

Parameters None

Return values

Name	Type	Description
name	string	Product short name
note	string	Product long description
reference	string	Product API reference
category	string	Product category
from_price	string	Product from price
currency	string	The currency in ISO 4217

HTTP status codes

Code	Status	Description
200	OK	The request has succeeded
204	No content	The requested order was not found
400	Bad request	The request was invalid or parameters are missing
403	Forbidden	The request was denied due to missing credentials

Product info

endpoint

https://api.cloudprinter.com/cloudapps/1.0/products/info

Get detailed information on a single product. This includes price on the base product and available options, as well as specs on the product.

Methods POST

Example request

json

{
  "product_reference": "textbook_cw_a6_p_bw"
}

const axios = require('axios');
const data = JSON.stringify({
  "product_reference": "textbook_cw_a6_p_bw"
}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/products/info',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/products/info',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "product_reference": "textbook_cw_a6_p_bw"
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/products/info"

payload = json.dumps({
  "product_reference": "textbook_cw_a6_p_bw"
}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/products/info' \
--header 'Content-Type: application/json' \
--data '{
  "product_reference": "textbook_cw_a6_p_bw"
}
'

Example JSON Response

json

{
  "name": "Textbook CW A6 P BW",
  "note": "Textbook Casewrap (PUR, 3 mm board) A6 Portrait DIG BW 80OFF",
  "product_reference": "textbook_cw_a6_p_bw",
  "prices": [
    {
      "price": "3.3300",
      "min": "1",
      "max": "65535",
      "note": "Textbook Casewrap (PUR, 3 mm board) A6 Portrait DIG BW 80OFF",
      "reference": "-",
      "currency": "EUR",
      "price_unit": "Pr quantity"
    },
    {
      "price": "0.0150",
      "min": "1",
      "max": "65535",
      "note": "Pageblock paper 80gsm Offset",
      "reference": "pageblock_80off",
      "currency": "EUR",
      "price_unit": "Pr page"
    }
  ],
  "specs": [
    {
      "note": "Binding method / technology",
      "value": "CW - Casewrap",
      "reference": "binding"
    },
    {
      "note": "Bleed in mm",
      "value": "3",
      "reference": "bleed_in_mm"
    }
  ]
}

Parameters

Name	Type	Description	Required
product_reference	string	The api reference of the product	required

Return values

Name	Type	Description
name	string	Product short name
note	string	Product long description
reference	string	Product API reference

Name	Type	Description
prices	array	Array of price objects
prices : price	string	Product or option price
prices : min	string	Minimum item quantity range
prices : max	string	Maximum item quantity range
prices : note	string	Product long description
prices : reference	string	For options, the API reference
prices : currency	string	The currency in ISO 4217
prices : price_unit	string	The price unit type (Pr. Order, Pr. Item, Pr. Quantity, Pr. Page)

Name	Type	Description
specs	array	Array of spec objects
specs : note	string	Spec long description
specs : value	string	Spec value
specs : reference	string	Spec reference

HTTP status codes

Code	Status	Description
200	OK	The request has succeeded
204	No content	The requested order was not found
400	Bad request	The request was invalid or parameters are missing

Shipping calls

List all countries

endpoint

https://api.cloudprinter.com/cloudapps/1.0/shipping/countries

Request a list of all countries that supported by cloudprinter.com

Methods GET, POST

Example request

json

{}

const axios = require('axios');
const data = JSON.stringify({}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/shipping/countries',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/shipping/countries',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/shipping/countries"

payload = json.dumps({}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/shipping/countries' \
--header 'Content-Type: application/json' \
--data '{}
'

Example JSON Response

json

{
    "shipping_countries": [
        {
            "country_reference": "AE",
            "note": "United Arab Emirates",
            "require_state": 0
        },
        {
            "country_reference": "AF",
            "note": "Afghanistan",
            "require_state": 0
        },
        {
            "country_reference": "AG",
            "note": "Antigua and Barbuda",
            "require_state": 0
        },
        {
            "country_reference": "AI",
            "note": "Anguilla",
            "require_state": 0
        },
        {
            "country_reference": "AL",
            "note": "Albania",
            "require_state": 0
        },
        {
            "country_reference": "AM",
            "note": "Armenia",
            "require_state": 0
        },
        {
            "country_reference": "AO",
            "note": "Angola",
            "require_state": 0
        },
        {
            "country_reference": "AQ",
            "note": "Antarctica",
            "require_state": 0
        },
        {
            "country_reference": "AR",
            "note": "Argentina",
            "require_state": 0
        }
    ]
}

Parameters None

Return values

Name	Type	Description
shipping_countries	array	List of countries
shipping_countries : country_reference	string	Country - ISO 3166-1 alpha-2
shipping_countries : note	string	The name of the country
shipping_countries : require_state	boolean	The '1' - if country has states, '0' - otherwise

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 credentials

List all states

endpoint

https://api.cloudprinter.com/cloudapps/1.0/shipping/states

Request a list of all states depends on country

Methods GET, POST

Example request

json

{
    "country_reference": "US"
}

const axios = require('axios');
const data = JSON.stringify({
    "country_reference": "US"
}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/shipping/states',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/shipping/states',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "country_reference": "US"
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/shipping/states"

payload = json.dumps({
    "country_reference": "US"
}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/shipping/states' \
--header 'Content-Type: application/json' \
--data '{
    "country_reference": "US"
}
'

Example JSON Response

json

{
    "shipping_states": [
        {
            "state_reference": "AA",
            "note": "U.S. Armed Forces - Americas"
        },
        {
            "state_reference": "AE",
            "note": "U.S. Armed Forces - Europe"
        },
        {
            "state_reference": "AK",
            "note": "Alaska"
        },
        {
            "state_reference": "AL",
            "note": "Alabama"
        },
        {
            "state_reference": "AP",
            "note": "U.S. Armed Forces - Pacific"
        },
        {
            "state_reference": "AR",
            "note": "Arkansas"
        },
        {
            "state_reference": "AZ",
            "note": "Arizona"
        }
	]
}

Parameters

Name	Type	Description	Required
country_reference	string	Country code - ISO 3166-1 alpha-2	required

Return values

Name	Type	Description
shipping_states	array	List of states
shipping_states : state_reference	string	State code - ANSI INCITS 38:2009 alpha-2
shipping_states : note	string	State 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 credentials

List all shipping level

endpoint

https://api.cloudprinter.com/cloudapps/1.0/shipping/levels

Request a list of all shipping levels

Methods GET, POST

Example request

json

{}

const axios = require('axios');
const data = JSON.stringify({}
);

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.cloudprinter.com/cloudapps/1.0/shipping/levels',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.log(error);
});

php

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cloudprinter.com/cloudapps/1.0/shipping/levels',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.cloudprinter.com/cloudapps/1.0/shipping/levels"

payload = json.dumps({}
)
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

curl --location 'https://api.cloudprinter.com/cloudapps/1.0/shipping/levels' \
--header 'Content-Type: application/json' \
--data '{}
'

Example JSON Response

json

{
    "shipping_levels": [
        {
            "shipping_level_reference": "cp_fast",
            "name": "Express fast - Tracked",
            "note": "Fast express - Fastest possible trackaed delivery - Cloudprinter shared"
        },
        {
            "shipping_level_reference": "cp_saver",
            "name": "Express saver - Tracked",
            "note": "Saver express  - Fast saver tracked delivery - Cloudprinter shared"
        },
        {
            "shipping_level_reference": "cp_ground",
            "name": "Express ground - Tracked",
            "note": "Ground express - Fast ground delivery - Cloudprinter shared"
        },
        {
            "shipping_level_reference": "cp_postal",
            "name": "Postal - Untracked",
            "note": "Postal - Untracked postal delivery - Cloudprinter shared"
        }
    ]
}

Parameters None

Return values

Name	Type	Description
shipping_levels	array	List of shipping levels
shipping_levels : shipping_level_reference	string	Shipping level reference
shipping_levels : name	string	Shipping level name
shipping_levels : note	string	Shipping level description

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 credentials

CloudApps API ​

Getting started ​

Basics ​

RESTful API ​

Authentication ​

Request Data ​

Return Data ​

Content-type ​

Order calls ​

List all orders ​

Get order info ​

Add order ​

Cancel order ​

Order log ​

Order quote ​

Product calls ​

List all products ​

Product info ​

Shipping calls ​

List all countries ​

List all states ​

List all shipping level ​

CloudApps API

Getting started

Basics

RESTful API

Authentication

Request Data

Return Data

Content-type

Order calls

List all orders

Get order info

Add order

Cancel order

Order log

Order quote

Product calls

List all products

Product info

Shipping calls

List all countries

List all states

List all shipping level