This is the documentation for the current production release of our API, v3.0.
We recommend that all new clients should integrate with v4, which will become the primary version of our API in March 2021. The v4 Prodigi API documentation is available on prodigi.com.
Documentation for other versions is also available for existing clients.
Need an account? Sign up now.
There are two environments available: production and sandbox. Testing and development should be done against the sandbox API. This is an environment where you can create, and submit orders without incurring any costs. All orders submitted to the production environment will be processed and charged.
Requests should always be made over HTTPS. Connections cannot be made via HTTP. Please note that support for SSL 3.0 has been disabled and we recommend using TLS 1.2 or better.
API Endpoint:https://api.pwinty.com/v3.0
Dashboard: https://dashboard.prodigi.com
API Endpoint:https://sandbox.pwinty.com/v3.0
Dashboard: https://sandbox-beta-dashboard.pwinty.com/
Requests should be made using either JSON or HTTP form data.
The Content-type
header should be set accordingly to either Content-type: application/json
or application/x-www-form-urlencoded
.
Please note that responses are formatted according to the accept
http header. At present, we recommend that you supply an value of accept: application/json
at this time. We can and do provide responses in XML but the schema isn't presently stable.
Errors are returned using standard HTTP status codes. Pwinty will return an empty version of the expected item, with an errorMessage parameter (this makes deserialization easier in some languages).
Code | Description |
---|---|
400 | Bad or missing input parameter- see error for more details. |
403 | Forbidden. The request is not valid for the resource in its current state. |
404 | Resource not found. |
All errors should return a standard JSON object in the response, containing an error message.
{ "errorMessage": "This is a sample error message" }
Pwinty uses custom HTTP headers for authentication, with the MerchantID and API key you received when signing up.
Header | Description |
---|---|
X-Pwinty-MerchantId | Your MerchantID. |
X-Pwinty-REST-API-Key | Your API key. |
Pwinty can make callbacks to a custom URL whenever the status of one of your orders changes.
Setup your callback URL under the Integrations section of the Dashboard.
Pwinty will make an JSON formatted HTTP POST to your chosen URL with the following parameters.
Parameter | Description | Data type | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
orderId | The Pwinty ID of the order. | integer | ||||||||||||||
environment | The environment from which the callback originated, either LIVE or SANDBOX . | string | ||||||||||||||
timestamp | The time the change took place. | datetime | ||||||||||||||
status | The current status of the order. One of NotYetSubmitted , Submitted , Complete , or Cancelled . | string | ||||||||||||||
shipments | Each shipment in the order. Note that this can be empty if the shipments have not yet been allocated, and it may change. You will receive a callback each time a new shipment is created, or a shipment status changes.
| array |
Pwinty will continue to try and make the callback until it receives an OK (200) Status code response from your server, or until the callback has failed 15 times. The time between each callback retry attempt will increase each time there is a failure.
It's really easy to get up and running with Pwinty. Follow our step by step guide below.
Make a POST call to /v3.0/orders
. Get back the order ID, which you will need for adding images to the order. If you don't have the address don't worry — create the order without the address parameters, and update it later in the process.
curl https://sandbox.pwinty.com/v3.0/orders \ -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d countryCode=GB \ -d recipientName=Mr%20Jones \ -d address1=The%20Hollies \ -d addressTownOrCity=Cardiff \ -d stateOrCounty=Glamorgan \ -d postalOrZipCode=CF11%201AX \ -d preferredShippingMethod=Express
Make POST calls to /v3.0/orders/{orderId}/images
.
curl https://sandbox.pwinty.com/v3.0/orders/1065/images \ -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d sku=ART-PRI-HPG-20X28-PRODIGI_GB \ -d url=http%3A%2F%2Fwww.testserver.com%2Faphoto.jpg \ -d md5Hash="79054025255fb1a26e4bc422aef54eb4" \ -d copies=2 \ -d sizing=Crop
Make a GET call to /v3.0/orders/
to check the order is valid and ready to be submitted.
curl https://sandbox.pwinty.com/v3.0/orders/1065/SubmissionStatus \ -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey"
Make a POST call to /v3.0/orders/{orderId}/status
to set the Status to "Submitted".
curl https://sandbox.pwinty.com/v3.0/orders/6961/status \ -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d status=Submitted
Once an order has been created, the images cannot be removed. If there is a problem with the images on an order, we recommend creating a new order and cancelling the original if it has already been submitted.
Yes we support shipping notes via the API. Although product and production facility coverage of this feature is continuing to expand, it may not be available for all orders. If you would like to confirm the availability of shipping notes for your typical orders, please get in touch.
When deciding where to print your orders, we take many elements into account including the cost, shipping speed and availability of the products. We will always look to print your orders at the cheapest available cost, ensuring we stay within the expected shipping times, passing those savings on to you.
Retrieves information about a single order.
GET /v3.0/orders/{id}
{ "data": { "id": 1065, "address1": "14 Acacia Avenue", "address2": "", "postalOrZipCode": "CF11 1AB", "countryCode": "GB", "addressTownOrCity": "Cardiff", "recipientName": "Tom Smith", "stateOrCounty": "Glamorgan", "status": Complete "payment": "InvoiceMe", "paymentUrl": null, "price": 0, "shippingInfo": { "price": 299, "shipments": [ { "carrier": "RoyalMail", "photoIds": [ 520151 ], "shipmentId": "506332", "trackingNumber": "XYZ123456ABC", "trackingUrl": "http://www.royalmail.com/portal/rm/track?trackNumber=XYZ123456ABC", "isTracked": false, "earliestEstimatedArrivalDate": "2018-08-16T00:00:00", "latestEstimatedArrivalDate": "2018-08-18T23:59:59", "shippedOn": "2018-08-15T15:34:59" } ] }, "images": [ { "id": 520151, "sku": "RT-PRI-HPG-20X28", "url": "url": "https://prodigi-uploads/mp1ht9.jpg" "status": "Ok", "copies": 1, "sizing": Crop "priceToUser": 200, "price": 40, "md5Hash": "70e8b246527f88131a5ea00ac3eced84" "previewUrl": "https://pwintyimages/1b90a95&sp=rw", "thumbnailUrl": "https://pwintyimages/47845&sp=rw", "attributes": { "substrateWeight": "400gsm", "frame": "gbp", "edge": "19mm", "paperType": "hmc", "frameColour": "gold" }, "errorMessage": null } ], "merchantOrderId": "ORD-123-456", "preferredShippingMethod": "Standard", "mobileTelephone": null, "created": "2018-08-14T08:54:35.213", "lastUpdated": "2018-08-14T09:38:28.57", "canCancel": true, "canHold": true, "canUpdateShipping": true, "canUpdateImages": false, "errorMessage": null, "invoiceAmountNet": 0, "invoiceTax": 0, "invoiceCurrency": null }, "statusTxt": "OK", "statusCode": 200 }
Field | Description | Type | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
id | The ID of the order. | integer | |||||||||
canCancel | Whether the order can be cancelled (depends on fulfilment partner and status of the order). | boolean | |||||||||
canHold | Whether the order can be placed on hold (depends on fulfilment partner and status of the order). | boolean | |||||||||
canUpdateShipping | Whether the order shipping address/method can be udpated (depends on fulfilment partner and status of the order). | boolean | |||||||||
canUpdateImages | Whether the images in the order are updateable (depends on fulfilment partner and status of the order). | boolean | |||||||||
recipientName | To whom the order will be addressed. | string | |||||||||
address1 | First line of recipient address. | string | |||||||||
address2 | Second line of recipient address. | string | |||||||||
addressTownOrCity | Town/city of recipient address. | string | |||||||||
stateOrCounty | State (US), county (UK) or region of recipient address. | string | |||||||||
postalOrZipCode | Postal/Zipcode of recipient address. | string | |||||||||
countryCode | Two-letter country code of the recipient. | string | |||||||||
mobileTelephone | Recipient's phone number. | string | |||||||||
price | How much Pwinty will charge you for this order. | integer | |||||||||
status | Status of order. Can be NotYetSubmitted , Submitted ,AwaitingPayment , Complete , or Cancelled . | string | |||||||||
shippingInfo | Shipping object showing how the order will be shipped. Orders of multiple product types may be automatically split into separate sub-orders and processed individually.
| object | |||||||||
payment | Payment option for order, can be either InvoiceMe or InvoiceRecipient . | string | |||||||||
paymentUrl | If payment is set to InvoiceRecipient then the URL the customer should be sent to to complete payment. | string | |||||||||
images | An array of objects representing the images in the order. | array | |||||||||
merchantOrderId | Your order reference. | string | |||||||||
preferredShippingMethod | Shipping method selected when creating an order. Can be Budget , Standard , Express , or Overnight . | string | |||||||||
created | The time the order was created. | datetime | |||||||||
lastUpdated | The time the order was updated for the last time. | datetime | |||||||||
errorMessage | Detail about any error on the request. | string | |||||||||
invoiceAmountNet | Used for orders where an invoice amount must be supplied (e.g. to Middle East). | integer | |||||||||
invoiceTax | Used for orders where an invoice amount must be supplied (e.g. to Middle East). | integer | |||||||||
invoiceCurrency | Used for orders where an invoice amount must be supplied (e.g. to Middle East). | string |
404
The order with the specified id was not found.Retrieves multiple orders, most recent first.
Note that calls that return potentially more than one result may omit shipping information from the results if the order hasn't yet been processed.
GET /v3.0/orders?limit=100&start=0
limit optional | Number of orders to return. Default 100, max 250. |
start optional | Start position used for paginating order list. Default 0. |
Order objects. See Orders (GET) for example response.
404
The order with the specified id was not found.POST /v3.0/orders
merchantOrderId optional | Your identifier for this order. |
recipientName | Recipient name. |
address1 optional * | First line of recipient address. |
address2 optional | Second line of recipient address. |
addressTownOrCity optional * | Town or city of the recipient. |
stateOrCounty optional | State, county or region of the recipient. |
postalOrZipCode optional * | Postal or zip code of the recipient. |
countryCode | Two-letter country code of the recipient. |
preferredShippingMethod | Possible values are Budget , Standard , Express , and Overnight . |
payment optional | Payment option for order, either InvoiceMe or InvoiceRecipient . Default InvoiceMe |
packingSlipUrl optional † | URL to a packing slip file. PNG format, A4 size recommended. |
mobileTelephone optional | Customer's mobile number for shipping updates and courier contact. |
telephone optional | Customer's non-mobile phone number for shipping updates and courier contact. |
email optional | Customer's email address. |
invoiceAmountNet optional | Used for orders where an invoice amount must be supplied (e.g. to Middle East). |
invoiceTax optional | Used for orders where an invoice amount must be supplied (e.g. to Middle East). |
invoiceCurrency optional | Used for orders where an invoice amount must be supplied (e.g. to Middle East). |
* Although these are optional for order creation, they are required when submitting your order.
† Not all production facilities support shipping notes. Please contact us to confirm availability for your typical product range.
A JSON order object representing the new order.
400
One of the input parameters was invalid or missing. The error message will indicate which one and why.PUT /v3.0/orders/{id}
A JSON object identical to the one used when creating an order.
A JSON object representing the updated order.
400
One of the input parameters was invalid or missing, error message should indicate which one and why.403
Only orders in state NotYetSubmitted
can be updated.404
No order with that id was found.Before submitting an order, you can validate it to make sure it's good to go, or we can tell you why it isn't.
GET /v3.0/orders/{id}/SubmissionStatus
id | Order ID |
{ "id": 1065, "isValid": false, "generalErrors" : [ "PostalAddressNotSet", "ItemsContainingErrors" ] "photos" : [ { "id" : 5431, "errors" : [ "FileCouldNotBeDownloaded" ], "warnings" : [] }, { "id" : 5449 "errors" : [], "warnings" : [ "PictureSizeTooSmall", "CroppingWillOccur" ] } ] }
Field | Description | Type | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
id | ID of the order | integer | ||||||||
isValid | Whether the order is valid. Submission will it succeed if you submit it. | boolean | ||||||||
photos | Invalid images in the order.
| array | ||||||||
generalErrors | An array of strings, containing any top level errors associated with the order. | array |
AccountBalanceInsufficient | You cannot submit any more orders until you have paid off the balance outstanding on your account. |
ItemsContainingErrors | One or more of the images in the order has errors- see the photos object for more information. |
NoItemsInOrder | The order has no images associated with it, so cannot be submitted. |
PostalAddressNotSet | The recipient address fields on the order were not properly set. You must supply at least address1 , addressTownOrCity , postalOrZipCode and countryCode . |
FileCouldNotBeDownloaded | We could not download an image from the supplied URL, after multiple attempts. |
NoImageFile | You haven't submitted an image URL nor have you POSTed an image. |
InvalidImageFile | Image file format is not valid. |
ZeroCopies | Number of copies of the image has been set to zero. |
CroppingWillOccur | The image supplied does not match the aspect ratio of the printing area of the product. We will need to crop or resize it. |
PictureSizeTooSmall | The image supplied is below the recommended resolution. |
CouldNotValidateImageSize | You've supplied an image with a URL, but we haven't downloaded it yet. This means we can't check the image size at the moment. |
CouldNotValidateAspectRatio | You've supplied an image with a URL, but we haven't downloaded it yet. This means we can't check the aspect ratio at the moment. |
AttributeNotValid | One of the product attributes set on the image is invalid. |
404
Order with the specified id was not found.Update the status of an order, for example to submit or cancel it.
POST /v3.0/orders/{id}/status
id | Order id (URL parameter). |
status | Status to which the order should be updated (POST parameter). Valid values are Cancelled , AwaitingPayment or Submitted . |
An HTTP status code denoting success or failure.
200
The photo was deleted.400
One or more of the input parameters was invalid.402
Payment requires authorisation.403
The order cannot be transitioned to the supplied status from its current status.404
Order with the specified id was not found.Due to recent Strong Customer Authentication updates, for orders placed within the European Economic Area (EEA), additional authorisation may be required for payments made online. If your order requires authorisation by your bank or card provider, we will return a status of 402
. The body of this response will follow this format:
{ "data": { "url": "https://dashboard.prodigi.com/payment/{authorisation-id}", "paymentRequest": 52 }, "statusTxt": "Payment Authorization Required", "statusCode": 402 }
The URL provided in the response body should be used to provide authorisation for the payment before the order will be processed for fulfilment. Until authorisation is made, the order will remain as AwaitingPayment
.
To cancel an order you will need to update its status with an appropriate value.
Field | Description | Type | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
id | Unique integer identifying the image. | integer | ||||||||||
url | If image is to be downloaded by Pwinty, the image's URL. | string | ||||||||||
status | Current status of the image.
| string | ||||||||||
copies | Number of copies of the image to include in the order. | integer | ||||||||||
sizing | How the image should be resized when printing. | string | ||||||||||
price | The amount (in cents/pence) that Pwinty will charge you for this item. | integer | ||||||||||
priceToUser | If payment is set to InvoiceRecipient then the price (in cents/pence) you want to charge for this item. | integer | ||||||||||
md5Hash | The md5 hash of the image file (when available). | string | ||||||||||
previewUrl | A URL to image after cropping. | string | ||||||||||
thumbnailUrl | A URL that will serve up a thumbnail of the image after cropping. | string | ||||||||||
sku | An identification code of the product associated with this image. | string | ||||||||||
attributes | An object containing all the attributes set on the object. | object | ||||||||||
errorMessage | Detail about any error on the request. | string |
POST /v3.0/orders/{orderId}/images
orderId | The ID of the order (in URL). |
sku | An identification code of the product for this image. |
url | The image's URL. |
copies | Number of copies of the image to include in the order. |
sizing | How the image should be resized when printing. |
priceToUser optional | If payment is set to InvoiceRecipient then the price (in cents/pence) you want to charge for each copy. Only available if your payment option is InvoiceRecipient . |
md5Hash optional | An MD5 hash of the image file. |
attributes optional | An object with properties representing the attributes for the image. |
Information about the created image. See the image object for example response.
400
Bad or missing input parameter- see error for more details.403
The order is in a state where images cannot be added, e.g. Complete
.404
The order with the specified orderId was not found.POST /v3.0/orders/{orderId}/images/batch
orderId | The ID of the order (in URL). |
The body of the HTTP request should contain an array of objects with the following structure.
sku | An identification code of the product for this image. |
url | The image's URL. |
copies | Number of copies of the image to include in the order. |
sizing | How the image should be resized when printing. |
priceToUser optional | If payment is set to InvoiceRecipient then the price (in cents/pence) you want to charge for each copy. Only available if your payment option is InvoiceRecipient . |
md5Hash optional | An MD5 hash of the image file. |
attributes optional | An object with properties representing the attributes for the image. |
{ "errorMessage": null, "items": [ { "id": 3456, "type": "4x6", "url": "http://www.flickr.com/mytestphoto.jpg", "status": "NotYetDownloaded", "copies": "4", "sizing": "Crop", "priceToUser" : 214, "price" : 199, "md5Hash" : "79054025255fb1a26e4bc422aef54eb4", "previewUrl" : "http://s3.amazonaws.com/anexampleurl", "thumbnailUrl" : "http://s3.amazonaws.com/anexamplethumbnailurl", "attributes": { "frameColour" : "silver" } }, { "id" : 4567, ... }, ... ] }
Field | Description | |
---|---|---|
errorMessage | Detail about any error on the request. | string |
items | An array of objects representing the created images. See the image object for more information. | array |
400
Bad or missing input parameter- see error for more details.403
The order is in a state where images cannot be added, e.g. Complete
.404
The order with the specified orderId was not found.If your image does not fit the product size, by default we will crop your image centrally. We print the image as large as possible, removing the top/bottom or left/right parts of the image that go beyond the print area.
However, you can also specify a sizing
parameter to change this behaviour.
Crop default | Your image will be centred and cropped so that it exactly fits the aspect ratio (height divided by width) of the printing area of the product you chose. Your image will cover all of the product print area. |
ShrinkToFit | Your image will be shrunk until the whole image fits within the print area of the product, whilst retaining the aspect ratio of your image. This will usually mean there is white space at the top/bottom or left/right edges. |
ShrinkToExactFit | Your image will be resized so that it completely fills the print area of the product. If the aspect ratio of your image is different to that of the printing area, your image will be stretched or squashed to fit. |
Pwinty will automatically try to rotate your images so that they need the least possible resizing to fit the product size. For example, if you are creating a 10 x 15 photo, and upload an image that is 4500px x 3000px, then Pwinty will flip it round so it is 3000px x 4500px and thus fits the photo perfectly.
Field | Description | Type |
---|---|---|
shipmentId | The unique identifier for this shipment. Null if order hasn't been submitted. | string |
isTracked | Whether the order will be tracked. | boolean |
trackingNumber | Tracking number, when available. | string |
trackingUrl | Tracking URL, when available. | string |
earliestEstimatedArrivalDate | Estimated earliest arrival of shipment. * | datetime |
latestEstimatedArrivalDate | Estimated latest arrival of shipment. * | datetime |
shippedOn | The shipping date. Null if the order hasn't been shipped. | datetime |
carrier | The shipping carrier used once a shipment has been dispatched: RoyalMail , RoyalMailFirstClass , RoyalMailSecondClass , FedEx , FedExUK , FedExIntl , Interlink , UPS , UpsTwoDay , UKMail , TNT , ParcelForce , DHL , UPSMI , DpdNextDay , EuPostal , AuPost , AirMail , NotKnown . | string |
photoIds | The IDs in the top-level image object. | array |
* Arrival estimates are beyond our control and are based on typical seasonal processing times and published shipping times for the shipment method relevant to the order.
This returns the list of all countries available in the system.
GET /v3.0/countries
[ { "name": "UNITED KINGDOM", "isoCode": "GB" }, { "name": "UNITED STATES", "isoCode": "US" }, ... ]
countryCode | Two-letter country code of the country. | string |
name | Name of the country. | string |
POST /v3.0/catalogue/prodigi%20direct/destination/{countryCode}/prices
countryCode | Two-letter country code where the order will be delivered (in URL). |
skus | An array with SKUs of products to check. |
{ "prices": [ { "sku": "ART-PRI-HPG-20X28-PRODIGI_GB", "price": 2050, "currency": "GBP" }, { "sku": "ART-FAP-CPP-6X6-PRODIGI_GB", "price": 250, "currency": "GBP" } ] }
sku | An identification code of the product. | string |
price | The amount (in cents/pence) that Pwinty will charge you for this product. | integer |
currency | Currency code in which product is priced. | string |
The latest production version of our API is v3.0.
All new clients should work towards integrating with v4 of the API, due for production release in March 2021.