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
  5. Validate
  6. Submit

Photos

  1. List
  2. Get by ID
  3. Create
  4. Create multiple
  5. Resizing
  6. Delete

Shipments

  1. The shipment object

Products

  1. List

Countries

  1. List

Order issues

  1. List
  2. Get by ID
  3. Create
  4. Update

Pwinty API documentation

You are currently viewing documentation for v2.5.
This version is deprecated.

v2.5 is no longer active. All new clients should work towards integrating with v4 of the API.

View v4 documentation

Documentation for v3 is also available for existing clients.

Need an account? Sign up now.

Overview

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/v2.5

Dashboard: https://dashboard.prodigi.com

Sandbox (testing)

API Endpoint:https://sandbox.pwinty.com/v2.5

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

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.

For example if you make a call to /v2.5/Catalogue:

{
    "errorMessage": "This is a sample error message",
    "country": null,
    "countryCode": null,
    "items": null,
    "qualityLevel": null,
    "shippingRates": null
}

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

Client libraries

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)

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

Pwinty will make an HTTP POST to your chosen URL.

Sample request

{
   "id":12456,
   "merchantOrderId" : "your-order-id",
   "environment" : "live",
   "timestamp" : ""2017-07-13T07:22Z",
   "status":"submitted",
   "shipments":[
      {
         "items":[
            14284,
            16983,
            10304
         ],
         "status":"shipped",
         "trackingNumber":"1-UZ-122345",
         "trackingUrl":"https://ashipmentcompany.com/track?id=1-UZ-122345"
      },
      {
         "items":[
            19912,
            14432
         ],
         "status":"inProgress",
         "trackingNumber":null,
         "trackingUrl":null
      }
   ]
}

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.
status Either inprogress or shipped.
trackingNumber Tracking number for the shipment where available.
trackingUrl Tracking URL for the shipment where available.
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 /v2.5/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.5/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

2. Add an image to the order

Make POST calls to /v2.5/Orders/{orderId}/Photos. Either supply a URL to the image, or send it as part of the POST.

curl https://sandbox.pwinty.com/v2.5/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

3. Check the order is valid

Make a GET call to /v2.5/Orders/{orderId}/SubmissionStatus to check the order is valid and ready to be submitted.

curl https://sandbox.pwinty.com/v2.5/Orders/1065/SubmissionStatus
    -H "X-Pwinty-MerchantId: YourMerchantId" \
    -H "X-Pwinty-REST-API-Key: YourAPIKey"

4. Submit the order

Make a POST call to /v2.5/Orders/{orderId}/Status to set the Status to "Submitted".

curl https://sandbox.pwinty.com/v2.5/Orders/6961/Status
    -H "X-Pwinty-MerchantId: YourMerchantId" \
    -H "X-Pwinty-REST-API-Key: YourAPIKey" \
    -d status=Submitted

Orders

Get an order

Retrieves information about a single order.

URL

GET /v2.5/Orders/{id}

Sample response

{
    "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}
                            }
                        ]
                    },
    "preferredShippingMethod" : "CHEAPEST",
    "merchantOrderId" : "ORD-123-456",
    "status" : "NotYetSubmitted",
    "payment" : "InvoiceRecipient",
    "paymentUrl" : "https://checkout.pwinty.com/Pay?paymentRef=12345",
    "qualityLevel" : "Pro",
    "created": "2017-07-28T08:53:16.21",
    "lastUpdated": "2017-07-28T09:06:49.95",
    "photos": [
        {
            ...See Photos (GET) for details
        },
    "invoiceAmountNet" : 0, //used for orders where an invoice amount must be supplied (e.g. to Middle East),
    "invoiceTax": 0, //used for orders where an invoice amount must be supplied (e.g. to Middle East),
    "invoiceCurrency": null //used for orders where an invoice amount must be supplied (e.g. to Middle East),
    ]
}

Returned values

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

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 /v2.5/Orders?count=100&offset=0&orderStatus=Complete

Parameters

count optional Number of orders to retrieve. Default 100, max 250.
offset optional Offset used for paginating order list. Default 0.
orderStatus optional Only return orders with this status.

URL

GET /v2.5/Orders?merchantOrderId={YOUR_REF} (filtered by your reference)

Parameters

merchantOrderId Returns only those orders matching your order reference as supplied through merchantOrderId when creating an order.

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 /v2.5/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.
destinationCountryCode Two-letter country code of the recipient.
countryCode Two-letter country code where the order should be printed.
preferredShippingMethod optional Standard values are CHEAPEST or PRIORITY, contact us for more details.
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, either Pro or Standard.
mobileTelephone Customer's mobile number for shipping updates and courier contact.

* 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 /v2.5/Orders/{id}

Parameters

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

Returned values

A JSON order 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 /v2.5/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 photos in the order.
Field Description
id ID of the photo.
errors Array of objects containing any errors associated with this photo.
warnings Array of objects containing any warnings associated with this photo.
array
generalErrors An array of strings, containing any top level errors associated with the order.

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

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

Photo warnings

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.

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 /v2.5/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.

Errors

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

Photos

Get a photo

Retrieves information about a specific photo.

URL

GET /v2.5/Orders/{orderId}/Photos/{photoId}

Parameters

orderId The ID of the order.
photoId The ID of the photo.

Returned values

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.
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 photo.
NotYetDownloaded You have specified a url associated with the photo, 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 jpg file. All is ready to go.
FileNotFoundAtUrl We tried using the url you specified to grab the image associated with the photo, but we didn't find an image there.
Invalid You uploaded a file, but it wasn't a valid jpg image file, or we checked the url you specified and didn't find a valid jpg image there.
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.

Errors

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

List photos in an order

Retrieve the photos associated with an order.

URL

GET /v2.5/Orders/{id}/Photos

Returned values

Photo objects. See Photos (GET) for example response.

Errors

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

Add a photo to an order

URL

POST /v2.5/Orders/{orderId}/Photos/

Parameters

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.

Returned values

Information about the created photo. See Photos (GET) for example response.

Errors

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

Add multiple photos to an order

Note that you can only add multiple photos by specifying the photo URL, not by POSTing the image data.

URL

POST /v2.5/Orders/{orderId}/Photos/Batch

Parameters

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.

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
items Array of items represented the created photos. See Photos (GET) for all the properties.

Errors

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

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

Delete a photo from an order

Retrieves information about a specific photo.

URL

DELETE /v2.5/Orders/{orderId}/Photos/{photoId}

Parameters

orderId The ID of the order.
photoId The ID of the photo.

Returned values

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.

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

Products

List all products

Retrieves information about the different products available in a given country.

URL

GET /v2.5/Catalogue/{countryCode}/{qualityLevel}

Parameters

countryCode Two-letter country code
qualityLevel Quality level of the catalogue you require, either Pro or Standard.
name Name of the country

Sample response

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

Returned values

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
Item Field Item Description
name Name of the item (serves as the key when adding items to order)
description Description of the item
imageHorizontalSize Horizontal size of the printed part of the item
imageVerticalSize Vertical size of the printed part of the item
fullProductHorizontalSize Horizontal size of the whole item (including any mounting or frame)
fullProductVerticalSize Vertical size of the whole item (including any mounting or frame)
sizeUnits Whether horizontalSize and verticalSize are in inches or cm
priceGBP Price in British pence of the item
priceUSD Price in US cents of the item
recommendedHorizontalResolution Recommended horizontal resolution of source image
recommendedVerticalResolution Recommended vertical resolution of source image
attributes Array of valid attributes for the item. Each attribute item has a name, and an array of valid values.
shippingRates Array of shipping rates available in the catalogue
Shipping rate field Shipping rate description
band Shipping band of the item (e.g. Prints, LargePrints, Canvas, FramedPrints)
description Description of the item
shippingMethod The shipping method code for this rate. Default supported values are cheapest or priority, but contact us for other available methods for your region and products.
priceGBP Price in British pence of the item
priceUSD Price in US cents of the item

Errors

  • 404 Specified country or qualityLevel was not found.

Countries

List all countries

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

URL

GET /v2.5/Country

Example response

An array of countries.

[
    {
        "countryCode": "GB",
        "hasProducts": false,
        "name": "United Kingdom"
    },
    {
        "countryCode" : "US",
        ...
    },
    ...
]

Returned values

countryCode Two-letter country code of the country
hasProducts Boolean indicating whether any products are available in this country
name Name of the country

Order issues

Get issue by ID

Gets issue details for a given order issue.

URL

GET /v2.5/Orders/{orderId}/Issues/{issueId}

Parameters

  • orderId The ID of the order
  • issueId The ID of the issue

Sample response

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

Errors

  • 400 The issue isn't related to the order with the supplied orderId.
  • 404 The issue with the specified issueId was not found.

List all issues

Gets all the issues for a given order

URL

GET /v2.5/Orders/{orderId}/Issues

Parameters

orderId The ID of the order.

Sample response

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

Errors

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

Create an order issue

Create a new issue for a given order

URL

POST /v2.5/Orders/{orderId}/Issues

Parameters

orderId The id of the order.
issue The type of issue.
  • DamagedOrder
  • WrongFrameColour
  • IncompleteOrder
  • LostInPost
  • IncorrectOrientation
  • IncorrectPrints
  • PrintDefects
  • SlowArrival
  • SlowDispatch
  • SubmissionErrors
  • WrongAddress
  • Unspecified
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.

Sample response

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

Errors

  • 400 See the message details for more information.
  • 404 Usually indicates an invalid orderId. See the message detail for more information.

Update an issue

Allows comments to be appended to an issue and allows a merchant to cancel an issue.

URL

PUT /v2.5/Orders/{orderId}/Issues/{issueId}

Parameters

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.

Returned values

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

Errors

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

API versions

Current version

The latest production version of our API is version 4.

All new clients should work towards integrating with this version.

Other versions

For existing clients who are already integrated with our service, documentation for v3 is also available.