File Library API
To avoid the need to upload every file again when the same item is ordered, your print files are stored in the File Library and can be reused.
You can use this API to directly add files to the library, and later use File IDs when creating orders. However the more convenient way is to specify the files by URL at the same time the order is created.
Most probably you will never need to use this API - just specify the file URL when creating orders and the files will be added automatically.
File processing can be very time consuming, so they are processed asynchronously. After you add a file, it is saved with the status waiting and downloaded and processed later. Afterwards the status is changed to ok if the file was loaded successfully and was a valid image file, or failed if the process did not succeed. Some of the file metadata fields like dimensions and resolution are only filled in after the file has been processed.
If an order with a file has been confirmed before the file was processed and the file turns out to be invalid, then the order is reverted to a failed state and needs to be corrected and confirmed again.
If you try to add a file that has an identical URL to an already existing file, then no new file is created, and the system returns the old one without refreshing its contents.
Remember - if you have changed the original, make sure that the URL is changed as well for future orders, otherwise the old
version will be reused.
You can add a “last modified” timestamp to the end of the URL to ensure that the URL is different for changed files.
You can add a “last modified” timestamp to the end of the URL to ensure that the URL is different for changed files.
Files that are added through the API can be set not to show up in the File library on the web, just set the visible attribute to false when creating them.
Get list of files
GET https://api.printful.com/files
Returns list of last added files
Input parameters:
Response format:
| status | string | Filter by file status |
| offset | integer | Result set offset |
| limit | integer | Number of items per page (max 100) |
| code | integer | Response status code 200 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| result | File [ ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| paging | Paging | Paging information | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| API key | ||
| status | Filter by file status | |
| offset | Result set offset | |
| limit | Number of items per page (max 100) | |
| Execute | ||
File list with one file just added and three already processed.
Response data:
{
"code": 200,
"result": [{
"id": 11815,
"type": "default",
"hash": null,
"url": "http://www.example.com/images/tshirts/front_123.pdf",
"filename": null,
"mime_type": null,
"size": 0,
"width": null,
"height": null,
"dpi": null,
"status": "waiting",
"created": 1390818471,
"thumbnail_url": null,
"preview_url": null,
"visible": true
}, {
"id": 10003,
"type": "preview",
"hash": "8a635765cc782c8c72a2a37ab7729a07",
"url": "http://example.com/images/tshirts/preview_1.jpg",
"filename": "tshirt_preview.jpg",
"mime_type": "image/jpeg",
"size": 19941,
"width": 420,
"height": 200,
"dpi": 72,
"status": "ok",
"created": 1390818271,
"thumbnail_url": "https://www.printful.com/storage/files/1559/8/8a635765cc782c8c72a2a37ab7729a07_thumb.png",
"preview_url": "https://www.printful.com/storage/files/1559/8/8a635765cc782c8c72a2a37ab7729a07_preview.png",
"visible": false
}, {
"id": 10002,
"type": "default",
"hash": "f259979918a51587c636fbc41508ce9b",
"url": null,
"filename": "mug-template.psd",
"mime_type": "image/x-psd",
"size": 1268210,
"width": 2700,
"height": 1380,
"dpi": 300,
"status": "ok",
"created": 1390554376,
"thumbnail_url": "https://www.printful.com/storage/files/1559/f/f259979918a51587c636fbc41508ce9b_thumb.png",
"preview_url": "https://www.printful.com/storage/files/1559/f/f259979918a51587c636fbc41508ce9b_preview.png",
"visible": true
}, {
"id": 11802,
"type": "default",
"hash": "756a648308bf49d4b763b87cdbd301dc",
"url": "http://example.com/images/posters/test.pdf",
"filename": "test.pdf",
"mime_type": "application/pdf",
"size": 5846629,
"width": 5000,
"height": 6667,
"dpi": 300,
"status": "ok",
"created": 1390551170,
"thumbnail_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_thumb.png",
"preview_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_preview.png",
"visible": true
}],
"paging": {
"total": 4,
"offset": 0,
"limit": 20
}
}
Add a new file
POST https://api.printful.com/files
Adds a new File to the library by providing URL of the file.
If a file with identical URL already exists, then the original file is returned. If a file does not exist, a new file is created.
Input parameters:
Response format:
| Request body | File | File data | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| code | integer | Response status code 200 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| result | File | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| API key | ||
| Request body | ||
| Execute | ||
Add file to the print file library, file name will be detected from URL. After creation file is not processed instantly.
Request body:
{
"url": "http://www.example.com/files/tshirts/example.psd"
}
Response data:
{
"code": 200,
"result": {
"id": 11816,
"type": "default",
"hash": null,
"url": "http://www.example.com/files/tshirts/example.psd",
"filename": null,
"mime_type": null,
"size": 0,
"width": null,
"height": null,
"dpi": null,
"status": "waiting",
"created": 1390819101,
"thumbnail_url": null,
"preview_url": null,
"visible": true
}
}
Add file to the mockup library, and specify file name manually
Request body:
{
"type": "preview",
"url": "http://www.example.com/files/tshirts/example.png",
"filename": "shirt1.png"
}
Add file to the library, but not show up in the web interface
Request body:
{
"url": "http://www.example.com/files/tshirts/example.psd",
"visible": 0
}
Get file information
GET https://api.printful.com/files/{id}
Returns information about the given file
Input parameters:
Response format:
| id | integer | File ID |
| code | integer | Response status code 200 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| result | File | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| API key | ||
| id | File ID | |
| Execute | ||
Response data:
{
"code": 200,
"result": {
"id": 11802,
"type": "default",
"hash": "756a648308bf49d4b763b87cdbd301dc",
"url": "http://example.com/images/posters/test.pdf",
"filename": "test.pdf",
"mime_type": "application/pdf",
"size": 5846629,
"width": 5000,
"height": 6667,
"dpi": 300,
"status": "ok",
"created": 1390551170,
"thumbnail_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_thumb.png",
"preview_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_preview.png",
"visible": true
}
}
