Overview

Environments

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.

Production

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

Dashboard: https://beta-dashboard.pwinty.com

Sandbox (testing)

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

Dashboard: https://sandbox-beta-dashboard.pwinty.com

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

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.

Callbacks

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.

Returned values

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

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

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"

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/x-www-form-urlencoded" \
    -d status=Submitted

Can I remove an image from an open order?

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.

Do you support shipping notes?

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.

Why are my orders printed in a different country than their destination?

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.

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

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?limit=100&start=0

Parameters

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

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

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

Sample response

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

Returned values

General errors

Image errors

Image warnings

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

Returned values

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.

Payments requiring authorisation

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://beta-dashboard.pwinty.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.

Cancel an order

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

Image object

Add an image to an order

URL

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

Parameters

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

The body of the HTTP request should contain an array of objects with the following structure.

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

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.

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

* 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

Fetch prices

URL

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

Parameters

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

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