Overview

URLs

All requests should 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.0 or better.

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.

Sandbox API URL

https://sandbox.pwinty.com/v3.0

Live API URL

https://api.pwinty.com/v3.0

Format

Request format

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.

Response format

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.

Error handling

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).

Standard API errors

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.

Error code format

All errors should return a standard JSON object in the response, containing an error message.

{
    "errorMessage": "This is a sample error message"
}

Authentication

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.

Callbacks

Pwinty can make callbacks to a custom URL whenever the status of one of your orders changes.

Setup your callback URL under the Integretions section of the Dashboard.

Pwinty will make an JSON formatted HTTP POST to your chosen URL with the following parameters.

Returned values

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. ShowHide Field Description items An array of item IDs included in the shipment. array status Either InProgress or Shipped. string trackingNumber Tracking number for the shipment where available. string trackingUrl Tracking URL for the shipment where available. string	array

Retries

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.

1. Create an order

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/json" \
    -d countryCode=GB \
    -d recipientName=Mr%20Jones \
    -d address1=The%20Hollies \
    -d addressTownOrCity=Cardiff \
    -d stateOrCounty=Glamorgan \
    -d postalOrZipCode=CF11%201AX \
    -d preferredShippingMethod=Express

2. Add an image to the order

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/json" \
    -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

3. Check the order is valid

Make a GET call to /v3.0/orders/{orderId}/SubmissionStatus 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" \
    -H "Content-Type: application/json"

4. Submit the order

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/json" \
    -d status=Submitted

Get an order

Retrieves information about a single order.

URL

GET /v3.0/orders/{id}

Sample response

{
    "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
}

Returned values

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. ShowHide Orders of multiple product types may be automatically split into separate sub-orders and processed individually. When this is the case we will provide details of all the shipments within a shippingInfo object as an array of shipping objects. ShippingField Description Type price The cost of the entire shipment. integer shipments An array of shipment objects. array	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

Errors

• 404 The order with the specified id was not found.

List orders

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.

URL

GET /v3.0/orders?count=100&offset=0

Parameters

count optional	Number of orders to retrieve. Default 100, max 250.
offset optional	Offset used for paginating order list. Default 0.

Returned values

Order objects. See Orders (GET) for example response.

Errors

• 404 The order with the specified id was not found.

Create an order

URL

POST /v3.0/orders

Parameters

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
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.

Returned values

A JSON order object representing the new order.

Errors

• 400 One of the input parameters was invalid or missing. The error message will indicate which one and why.

Update an order

URL

PUT /v3.0/orders/{id}

Parameters

A JSON object identical to the one used when creating an order.

Returned values

A JSON object representing the updated order.

Errors

• 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.

Validate an order

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.

URL

GET /v3.0/orders/{id}/SubmissionStatus

Parameters

id

Order ID

Sample response

{
    "id": 1065,
    "isValid": false,
    "generalErrors" : [
        "PostalAddressNotSet",
        "ItemsContainingErrors"
    ]
    "photos" : [
        {
           "id" : 5431,
           "errors" : [
            "FileCouldNotBeDownloaded"
           ],
           "warnings" : []
        },
        {
           "id" : 5449
           "errors" : [],
           "warnings" : [
            "PictureSizeTooSmall",
            "CroppingWillOccur"
           ]
        }
    ]
}

Returned values

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. ShowHide Field Description id ID of the image. errors Array of objects containing any errors associated with this image. warnings Array of objects containing any warnings associated with this image.	array
generalErrors	An array of strings, containing any top level errors associated with the order.	array

General errors

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.

Image errors

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.

Image warnings

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.

Errors

• 404 Order with the specified id was not found.

Submit an order / update status

Update the status of an order, for example to submit or cancel it.

URL

POST /v3.0/orders/{id}/status

Parameters

id	Order id (URL parameter).
status	Status to which the order should be updated (POST parameter). Valid values are Cancelled, AwaitingPayment or Submitted.

Returned values

An HTTP status code denoting success or failure.

• 200 The photo was deleted.
• 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.

Cancel an order

To cancel an order you will need to update its status with an appropriate value.

Image object

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. ShowHide AwaitingUrlOrData There are two ways of uploading a file to Pwinty. You can either specify a url or you can POST using a multi-part upload. If you see this status, it means you have yet to do either for this image. NotYetDownloaded You have specified a url associated with the image, but Pwinty hasn't yet downloaded it. There's nothing you need to do about this. Ok We've received your image and verified it is a valid file format. All is ready to go. FileNotFoundAtUrl We tried using the url you specified to grab the image, but we didn't find it there. Invalid You uploaded a file, but it wasn't in a valid format, or we checked the url you specified and didn't find a valid image there.	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

Add an image to an order

URL

POST /v3.0/orders/{orderId}/images

Parameters

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.

Returned values

Information about the created image. See the image object for example response.

Errors

• 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.

Add multiple images to an order

URL

POST /v3.0/orders/{orderId}/images/batch

Parameters

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.

Sample response

{
    "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,
                ...
              },
              ...
            ]
}

Returned values

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

Errors

• 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.

Image resizing

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.

Rotation

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.

The shipment object

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.

List all countries

This returns the list of all countries available in the system.

URL

GET /v3.0/countries

Sample response

[
    {
        "name": "UNITED KINGDOM",
        "isoCode": "GB"
    },
    {
        "name": "UNITED STATES",
        "isoCode": "US"
    },
    ...
]

Returned values

countryCode	Two-letter country code of the country.	string
name	Name of the country.	string

Fetch prices

URL

POST /v3.0/catalogue/prodigi%20direct/destination/{countryCode}/prices

Parameters

countryCode	Two-letter country code where the order will be delivered (in URL).
skus	An array with SKUs of products to check.

Sample response

{
   "prices": [
       {
           "sku": "ART-PRI-HPG-20X28-PRODIGI_GB",
           "price": 2050,
           "currency": "GBP"
       },
       {
           "sku": "ART-FAP-CPP-6X6-PRODIGI_GB",
           "price": 250,
           "currency": "GBP"
       }
   ]
}

Returned values

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

Current version

The latest version of our API is v3.0.

All new clients should ensure they integrate with this version.

Previous versions

For existing clients who are already integrated with our service, documentation for older versions of our API is available below. All new clients should ensure they integrate with the latest version, v3.0.

• v2.2
• v2.3
• v2.5
• v2.6