Navigation

Overview

Your first order

  1. Create an order
  2. Add an image
  3. Validate
  4. Submit

Reference

Orders

  1. Get
  2. List
  3. Create
  4. Update order
  5. Validate
  6. Submit
  7. Cancel

Images

  1. Image object
  2. Add image
  3. Add multiple images
  4. Resizing

Shipments

  1. The shipment object

Countries

  1. List

Catalogue

  1. Fetch prices

Pwinty API documentation

This is the documentation for the current version of our API, v3.0.

All new clients should integrate with this version. Documentation for previous versions is also available for existing clients.

Need an account? Sign up now.

Overview

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

Your first order

It's really easy to get up and running with Pwinty. Follow our step by step guide below.

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

Orders

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) or county (UK) of recipient address. string
postalOrZipCode Postal/Zipcode of recipient address. string
countryCode Country Code of where the order will be printed. 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.
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 Country code of the country where the order should be printed.
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.
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.

Images

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.
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": {
                                "frame_colour" : "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

Images you upload may not fit the size you specify exactly, so Here we discuss how Pwinty (and you) can deal with that.

When you add an image you can specify a sizing parameter. This has three possible values.

Crop The image you upload will be cropped until it exactly fits the aspect ratio (height divided by width) of the printing area of the product you chose.
ShrinkToFit The image you upload will be shrunk until all the image fits on the printing area of the product. This can lead to white bars at the edges. Think of a widescreen movie on an old 4:3 TV.
ShrinkToExactFit The image you upload will be resized until all of the image exactly fits all of the on the printing area of the product. This means that if the aspect ratio of the image and the printing area do not match, the image will be stretched or squashed to fit the size.

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.

Shipments

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.

Countries

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 The two letter country code of the country. string
name Name of the country. string

Catalogue

Fetch prices

URL

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

Parameters

countryCode Country code of the country 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

API versions

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.