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.
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.
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
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 |
{ "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.
Request body | File | File data (url parameter is required) | |||||||||||||||||||||||||||||||||||||||||||||
|
code | integer | Response status code 200 | |||||||||||||||||||||||||||||||||||||||||||||
result | File | ||||||||||||||||||||||||||||||||||||||||||||||
|
API key | ||
Request body | ||
Execute |
{ "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 } }
{ "type": "preview", "url": "http://www.example.com/files/tshirts/example.png", "filename": "shirt1.png" }
{ "url": "http://www.example.com/files/tshirts/example.psd", "visible": 0 }
Get file information
GET https://api.printful.com/files/{id}
id | integer | File ID |
code | integer | Response status code 200 | |||||||||||||||||||||||||||||||||||||||||||||
result | File | ||||||||||||||||||||||||||||||||||||||||||||||
|
API key | ||
id | File ID | |
Execute |
{ "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 } }