You are currently viewing documentation for v2.3.
This version is deprecated.
v2.3 is no longer active. All new clients should work towards integrating with v4 of the API.
Documentation for v3 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/v2.3
Dashboard: https://dashboard.prodigi.com
API Endpoint:https://sandbox.pwinty.com/v2.3
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.
For example if you make a call to /v2.3/Catalogue
:
{ "errorMessage": "This is a sample error message", "country": null, "countryCode": null, "items": null, "qualityLevel": null, "shippingRates": null }
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 |
We supply the following libraries to get you up and running quickly in your chosen language
Ruby | Ruby Client Library (GitHub) |
iOS | iOS Client Library (GitHub) |
Java | Java Client Library (with thanks to Matt Burns) |
.NET | .NET Client Library |
PHP | PHP Client Library (thanks to Dan Huddart) |
Python | Python Client Library (with thanks to Sam Willis of Posterhaste) |
Node.js | Node.js Client Library (with thanks to Matt Tortolani of Miniprints) |
Pwinty can make callbacks to a custom URL whenever the status of one of your orders changes.
Setup your callback URL under the My Details section of the Dashboard. Pwinty will make an JSON formatted HTTP POST to your chosen URL
Pwinty will make an 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 |
eventData | For orderStatusChanged events, the new order status can be NotYetSubmitted , AwaitingPayment , PaidAwaitingImageUpload , Submitted , Complete or Cancelled . | string |
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 /v2.3/Orders
. Get back the order ID, which you will need for adding photos 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/v2.3/Orders \ -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey" \ -d countryCode=GB \ -d qualityLevel=Pro \ -d recipientName=Mr%20Jones \ -d address1=The%20Hollies \ -d addressTownOrCity=Cardiff \ -d stateOrCounty=Glamorgan \ -d postalOrZipCode=CF11%201AX
Make POST calls to /v2.3/Orders/{orderId}/Photos
. Either supply a URL to the image, or send it as part of the POST.
curl https://sandbox.pwinty.com/v2.3/Orders/1065/Photos \ -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey" \ -d type=8x12 \ -d url=http%3A%2F%2Fwww.testserver.com%2Faphoto.jpg \ -d md5Hash="79054025255fb1a26e4bc422aef54eb4" -d copies=2 \ -d sizing=Crop
Make a GET call to /v2.3/Orders/
to check the order is valid and ready to be submitted.
curl https://sandbox.pwinty.com/v2.3/Orders/1065/SubmissionStatus -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey"
Make a POST call to /v2.3/Orders/{orderId}/Status
to set the Status to "Submitted".
curl https://sandbox.pwinty.com/v2.3/Orders/6961/Status -H "X-Pwinty-MerchantId: YourMerchantId" \ -H "X-Pwinty-REST-API-Key: YourAPIKey" \ -d status=Submitted
Retrieves information about a single order.
GET /v2.3/Orders/{id}
{ "id": 1065, "recipientName": "Tom Smith", "address1": "14 Acacia Avenue", "address2": "", "addressTownOrCity": "Cardiff", "stateOrCounty": "Glamorgan", "postalOrZipCode": "CF11 1AB", "countryCode": "GB", "destinationCountryCode": "GB", "price": 1292, "shippingInfo" : { "price" : 12, "shipments" : [ { "shipmentId" : 321, "trackingNumber" : "123456", "trackingUrl" : "http://www.ups.com/track?123456", "isTracked" : true, "earliestEstimatedArrivalDate" : "2015-02-19T12:50:59.175116Z", "latestEstimatedArrivalDate" : "2015-02-24T12:50:59.175116Z", "carrier" : "", "photoIds" : {3456, 3457} } ] } "status" : "NotYetSubmitted", "payment" : "InvoiceRecipient", "paymentUrl" : "https://checkout.pwinty.com/Pay?paymentRef=12345", "qualityLevel" : "Pro" "photos": [ { ...See Photos (GET) for details } ] }
Field | Description | Type | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
id | The ID of the order | integer | ||||||||
recipientName | To whom the order will be addressed | string | ||||||||
address1 | First line of recipient address | |||||||||
address2 | Second line of recipient address | |||||||||
addressTownOrCity | Town/city of recipient address | |||||||||
stateOrCounty | State (US), county (UK) or region of recipient address | |||||||||
postalOrZipCode | Postal/Zipcode of recipient address | |||||||||
destinationCountryCode | Two-letter country code of the recipient. | |||||||||
countryCode | Two-letter country code where the order should be printed. | |||||||||
price | How much Pwinty will charge you for this order | |||||||||
status | Status of order. Can be NotYetSubmitted , Submitted ,AwaitingPayment , Complete or Cancelled | |||||||||
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.
| |||||||||
payment | Payment option for order, can be either InvoiceMe or InvoiceRecipient | |||||||||
paymentUrl | If payment is set to InvoiceRecipient then the URL the customer should be sent to to complete payment | |||||||||
qualityLevel | Quality level for the order, can be either Pro or Standard | |||||||||
photos | An array of objects representing the photos in the order. |
404
The order with the specified id was not foundRetrieves all your orders.
GET /v2.3/Orders
Order objects. See Orders (GET) for example response.
404
The order with the specified id was not foundPOST /v2.3/Orders
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. |
destinationCountryCode | Country code of the recipient. |
countryCode | Country code of the country where the order should be printed. |
mobileTelephone optional ** | Mobile number for shipping SMS updates (where supported). |
useTrackedShipping optional | Whether to upgrade to a tracked shipping service when available. |
payment | Payment option for order, either InvoiceMe or InvoiceRecipient . |
qualityLevel | Quality Level for order, ceither Pro or Standard . |
* Although these are optional for order creation, they are required when submitting your order.
** In certain cases we will require that mobileTelephone
be set so that it can be passed on to the carrier. If this field is required for a given country/product combination then we will flag it in the order submission response if it hasn't been supplied. If it isn't required and you supply it, we may still attempt to pass it on to our fulfillers but there is no guarantee that it will be used.
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 /v2.3/Orders/{id}
id | The id of the order to update (in URL) |
recipientName | Who the order should be addressed to |
address1 | 1st line of recipient address |
address2 optional | 2nd line of recipient address |
addressTownOrCity | Town or City in the address |
stateOrCounty | State or County in the address |
postalOrZipCode | Postal code or Zip code of recipient |
A JSON order 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 /v2.3/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 photos in the order.
| array | ||||||||
generalErrors | An array of strings, containing any top level errors associated with the order. |
AccountBalanceInsufficient | You cannot submit any more orders until you have paid off the balance outstanding on your account. |
ItemsContainingErrors | One or more of the photos in the order has errors- see the photos object for more information. |
NoItemsInOrder | The order has no photos associated with it, so cannot be submitted. |
PostalAddressNotSet | The postal address fields on the order were not properly set. |
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 is not a valid jpg file. |
PostalAddressNotSet | The recipient address fields on the order were not properly set. You must supply at least address1 , addressTownOrCity , postalOrZipCode and destinationCountryCode . |
CroppingWillOccur | The image supplied does not match the aspect ratio of the photo size. We'll need to crop or resize it to fit it on the photo. |
PictureSizeTooSmall | The image supplied is below the recommended resolution for a photo of this size. |
CouldNotValidateImageSize | You've supplied a photo with a URL, and submitted it before the photo has been downloaded. This means we can't yet check the image size. |
CouldNotValidateAspectRatio | You've supplied a photo with a URL, and submitted it before the photo has been downloaded. This means we can't yet check the aspect ratio. |
404
Order with the specified id was not found.Update the status of an order, for example to submit or cancel it.
POST /v2.3/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 . |
404
Order with the specified id was not found.400
One or more of the input parameters was invalid.403
The order cannot be transitioned to the supplied status from its current status.Retrieves information about a specific photo.
GET /v2.3/Orders/{orderId}/
orderId | The ID of the order. |
photoId | The ID of the photo. |
Field | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
id | Unique integer identifying the photo. | ||||||||||
type | Type of photo. | ||||||||||
url | If photo is to be downloaded by Pwinty, the photo's URL. | ||||||||||
status | Current status of the photo.
| ||||||||||
copies | Number of copies of the photo to include in the order. | ||||||||||
sizing | How the image should be resized when printing. | ||||||||||
price | The amount (in cents/pence) that Pwinty will charge you for this item. | ||||||||||
priceToUser | If payment is set to InvoiceRecipient then the price (in cents/pence) you want to charge for this item. | ||||||||||
md5Hash | The md5 hash of the image file (when available). | ||||||||||
previewUrl | A URL to photo image after cropping. | ||||||||||
thumbnailUrl | A URL that will serve up a thumbnail of the image after cropping. | ||||||||||
attributes | An object containing all the attributes set on the object. Refer to the product list for valid attributes for each product. |
404
The photo with the specified id was not found.Retrieve the photos associated with an order.
GET /v2.3/Orders/{id}/Photos
Photo objects. See Photos (GET) for example response.
400
Bad or missing input parameter. See error for more details.403
The order is in a state where photos cannot be added, e.g. Complete
.404
The order with the specified orderId was not found.POST /v2.3/Orders/{orderId}/Photos/
orderId | The ID of the order (in URL). |
type | Type of photo. |
url optional | If photo is to be downloaded by Pwinty, the photo's URL. |
copies | Number of copies of the photo to include in the order. |
sizing | How the image should be resized when printing. |
priceToUser | 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 | An MD5 hash of the file which we'll check before processing. |
file optional | If you have the image file, then make this request as a multipart/form-data with the file included. |
attributes optional | An object with properties representing the attributes for the photo. For valid attributes see the product list. |
Information about the created photo. See Photos (GET) for example response.
400
Bad or missing input parameter- see error for more details.403
The order is in a state where photos cannot be added, e.g. Complete
.404
The order with the specified orderId was not found.Note that you can only add multiple photos by specifying the photo URL, not by POSTing the image data.
POST /v2.3/Orders/{orderId}/Photos/Batch
orderId | The ID of the order (in URL). |
type | Type of photo. |
url | The photo's URL. |
copies | Number of copies of the photo to include in the order. |
sizing | How the image should be resized when printing. |
priceToUser | If payment is set to InvoiceRecipient then the price (in cents/pence) you want to charge for each copy. you'd like to charge for each copy. Only available if your payment option is InvoiceRecipient . |
md5Hash | An MD5 hash of the file which we'll check before processing. |
attributes optional | An object with properties representing the attributes for the photo. For valid attributes see the product list. |
{ "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 |
items | Array of items represented the created photos. See Photos (GET) for all the properties. |
400
Bad or missing input parameter- see error for more details.403
The order is in a state where photos 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.
Retrieves information about a specific photo.
DELETE /v2.3/Orders/{orderId}/
orderId | The ID of the order. |
photoId | The ID of the photo. |
An HTTP status code denoting success or failure
200
The photo was deleted.403
Order is not in a valid state to remove photos. A photo can only be removed when state is NotYetSubmitted
.404
The photo with the specified id was not found.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 photo IDs in the top-level photos 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
Retrieves information about the different products available in a given country.
GET /v2.3/Catalogue/{countryCode}/
countryCode | Two-letter country code |
qualityLevel | Quality level of the catalogue you require, either Pro or Standard . |
{ "country": "United Kingdom", "countryCode": "GB", "qualityLevel" : "Pro", "items" : [ { description : "10x12 Print", imageHorizontalSize: 10, imageVerticalSize: 12, fullProductHorizontalSize: 10, fullProductVerticalSize: 12, name: "10x12", priceGBP: 150, priceUSD: 350, recommendedHorizontalResolution : 1500, recommendedVerticalResolution : 1800, sizeUnits: "inches", shippingBand : "Prints", attributes : [ { name : "finish", validValues : ["matte","glossy"] } ] }, { ... } ], shippingRates : [ { band : "Canvas", description: "Canvas tracked- UPS", isTracked: true, priceGBP: 700, priceUSD: 1100 }, { ... } ] }
countryCode | Two-letter country code of the catalogue | ||||||||||||||||||||||||||
country | Name of the country | ||||||||||||||||||||||||||
qualityLevel | Quality Level of the catalogue, either Pro or Standard | ||||||||||||||||||||||||||
items | Array of items available in the catalogue
| ||||||||||||||||||||||||||
shippingRates | Array of shipping rates available in the catalogue
|
404
Specified country or qualityLevel was not found.This returns the list of all countries available in the system.
GET /v2.3/Country
An array of countries.
[ { "countryCode": "GB", "hasProducts": false, "name": "United Kingdom" }, { "countryCode" : "US", ... }, ... ]
countryCode | Two-letter country code of the country |
hasProducts | Boolean indicating whether any products are available in this country |
name | Name of the country |
Gets issue details for a given order issue.
GET /v2.3/Orders/{orderId}/Issues/{issueId}
orderId
The ID of the orderissueId
The ID of the issue{ "id":"5", "issue":"WrongFrameColour", "issueDetail":"It wasn't pink!", "action":"Reprint", "actionDetail":"Needs to be PINK!", "orderId":"23", "affectedImages":["1","2","3","4","5","6","7"], "issueState":"ClosedResolved", "commentary":"[13/11/2014 @@ 15:09 : Pink I tell you!],[13/11/2014 @@ 15:10 : OK, OK, Pink it is then!],[13/11/2014 @@ 15:10 : [State change from Open to InProgress]],[13/11/2014 @@ 15:11 : [State change from InProgress to ClosedResolved]]" }
400
The issue isn't related to the order with the supplied orderId.404
The issue with the specified issueId was not found.Gets all the issues for a given order
GET /v2.3/Orders/{orderId}/Issues
orderId | The ID of the order. |
{ "Issues": [ { "id":"7", "issue":"DamagedOrder", "issueDescription":"Damaged Order", "issueDetail":"Broken! Noes!", "action":"Reprint", "actionDescription":"Reprint", "actionDetail":"Today!", "orderId":"23", "affectedImages":[], "issueState":"ClosedResolved", "commentary":"[13/11/2014 @@ 15:10 - Issue Opened]" }, { "id":"5", "issue":"WrongFrameColour", "issueDetail":"It wasn't pink!", "action":"Reprint", "actionDetail":"Needs to be PINK!", "orderId":"23", "affectedImages":["1","2","3","4","5","6","7"], "issueState":"ClosedResolved", "commentary":"[13/11/2014 @@ 15:09 : Pink I tell you!],[13/11/2014 @@ 15:10 : OK, OK, Pink it is then!],[13/11/2014 @@ 15:10 : [State change from Open to InProgress]],[13/11/2014 @@ 15:11 : [State change from InProgress to ClosedResolved]]" } ] }
404
The order with the specified orderId was not found.Create a new issue for a given order
POST /v2.3/Orders/{orderId}/Issues
orderId | The id of the order. |
issue | The type of issue.
|
issueDetail optional | A description of the issue providing additional information where necessary. |
action | The required action. One of Refund , Reprint , NoAction or Other . |
actionDetail optional | A description of the required action providing additional information where necessary. |
affectedImages optional | A a comma separated list or JSON array of the ids of the images affected, where relevant. |
{ "id":"5", "issue":"WrongFrameColour", "issueDetail":"It wasn't pink!", "action":"Reprint", "actionDetail":"Needs to be PINK!", "orderId":"23", "affectedImages":["1","2","3","4","5","6","7"], "issueState":"ClosedResolved", "commentary":"[13/11/2014 @@ 15:09 : Pink I tell you!],[13/11/2014 @@ 15:10 : OK, OK, Pink it is then!],[13/11/2014 @@ 15:10 : [State change from Open to InProgress]],[13/11/2014 @@ 15:11 : [State change from InProgress to ClosedResolved]]" }
400
See the message details for more information.404
Usually indicates an invalid orderId. See the message detail for more information.Allows comments to be appended to an issue and allows a merchant to cancel an issue.
PUT /v2.3/Orders/{orderId}/Issues/{issueId}
issueId | The id of the issue. |
newState optional | The new state for the issue. Only cancelled is supported at this time. |
comment optional | A comment. This will be appended to the issue's comments. |
{ "id":"5", "issue":"WrongFrameColour", "issueDetail":"It wasn't pink!", "action":"Reprint", "actionDetail":"Needs to be PINK!", "orderId":"23", "affectedImages":["1","2","3","4","5","6","7"], "issueState":"ClosedResolved", "commentary":"[13/11/2014 @@ 15:09 : Pink I tell you!],[13/11/2014 @@ 15:10 : OK, OK, Pink it is then!],[13/11/2014 @@ 15:10 : [State change from Open to InProgress]],[13/11/2014 @@ 15:11 : [State change from InProgress to ClosedResolved]]" }
400
Attempting to set the issue state to be the same as the current state.404
The issue with the specified issueId was not found.The latest production version of our API is version 4.
All new clients should work towards integrating with this version.
For existing clients who are already integrated with our service, documentation for v3 is also available.