NAV Navbar icon

Welcome to the Prodigi API reference documentation for v4

Sign up for your free API key

Introduction

Our RESTful API is built using standard HTTP response codes, authentication and verbs. We accept application/json payloads, and return JSON on every response.

Getting started

Our guide to placing your first order walks through our order process, from authentication to submitting an order to our print network.

Environments

We have two environments: Sandbox and Live. Creating a new account on the Live Dashboard will automatically set up both a Sandbox and Live account.

Sandbox

Sandbox is our testing environment. It will not fulfil your orders, and you will not be charged for using it.

Live

Live is our production environment. Any orders that are placed here will be produced and shipped.

Authentication

Using the authentication header 
curl "https://api.prodigi.com/v4.0/Orders" \
  -X GET \
  -H "X-API-Key: your-api-key"

Each request to our API requires the use of an authentication header: X-API-Key.

You can obtain an API key by signing up for a free Prodigi account.

Orders

Creating an order is a single API request, supplying all of the relevant information. Once the order is in our system, we will process it according to your account settings, taking into account any configured pause window. Otherwise, we will start to fulfill it immediately.

Order object

Order object 
{
    "id": "ord_840796",
    "created": "2021-03-11T14:31:23.41Z",
    "lastUpdated": "2021-03-11T14:31:23.4931606Z",
    "callbackUrl": null,
    "merchantReference": "MyMerchantReference1",
    "shippingMethod": "Overnight",
    "idempotencyKey": null,
    "status": {
        "stage": "InProgress",
        "issues": [],
        "details": {
            "downloadAssets": "NotStarted",
            "printReadyAssetsPrepared": "NotStarted",
            "allocateProductionLocation": "NotStarted",
            "inProduction": "NotStarted",
            "shipping": "NotStarted"
        }
    },
    "charges": [],
    "shipments": [],
    "recipient": {
        "name": "Mr test",
        "email": null,
        "phoneNumber": null,
        "address": {
            "line1": "14 test place",
            "line2": "test",
            "postalOrZipCode": "12345",
            "countryCode": "US",
            "townOrCity": "somewhere",
            "stateOrCounty": null
        }
    },
    "items": [
        {
            "id": "ori_926886",
            "status": "NotYetDownloaded",
            "merchantReference": "item #1",
            "sku": "GLOBAL-CFPM-16X20",
            "copies": 1,
            "sizing": "fillPrintArea",
            "attributes": {
                "color": "black"
            },
            "assets": [
                {
                    "id": "ast_114059",
                    "printArea": "default",
                    "md5Hash": "daa1c811c6038e718a23f0d816914b7b",
                    "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                    "status": "InProgress"
                }
            ],
            "recipientCost": {
                "amount": "10.74",
                "currency": "GBP"
            }
        }
    ],
    "packingSlip": null,
    "metadata": {
        "mycustomkey": "some-guid",
        "someCustomerPreference": {
            "preference1": "something",
            "preference2": "red"
        },
        "sourceId": 12345
    }

The Order object contains all the information you need to manage your order. Once created, most of the order remains static, while areas like Status and Shipments change as the order progresses.

Top level

Parameter Type Required Description
id string n/a The order's unique ID. Set by Prodigi.
created string n/a The UTC DateTime the order was created. Set by Prodigi.
callbackUrl string no Your callback URL, where we send callback events.
merchantReference string no Your own reference ID for this order.
shippingMethod string yes Your requested shipping method: either Budget, Standard,Express or Overnight. See shipping for more information about these methods, and how they map to real-world couriers.
idempotencyKey string no Your personal idempotency key.
status Status n/a The overall status of the order. Set by Prodigi.
charges array of Charges n/a Charges for this order. Set by Prodigi.
shipments array of Shipments n/a Courier and service shipment details per item, if available. Set by Prodigi.
recipient Recipient yes Shipping name and address.
items array of Items yes Items to be fulfilled (products + assets).
packingSlip PackingSlip no Packing slip.
metadata hashtable no A custom json object containing keys and values of your choice. Up to 2000 characters.

Recipient

Parameter Type Required Description
name string yes Recipient's name. Very long name strings may be truncated to suit courier guidelines.
email string no Recipient's email address
phoneNumber string no Recipient's mobile phone number
address Address yes Recipient's address.

Address

Parameter Type Required Description
line1 string yes First line of recipient's address.
line2 string no Second line of recipient's address.
postalOrZipCode string yes Postcode or zip code of recipient's address.
countryCode string yes Two-letter ISO country code of recipient's address.
townOrCity string yes Town or city of recipient's address.
stateOrCounty string no State or county for the recipient's address.

Charge

Parameter Type Required Description
id string n/a Unique ID for this charge. Set by Prodigi.
chargeType string n/a The type of charge record provided this could be one of the following: Item, Shipping, Refund or Other.
prodigiInvoiceNumber string n/a Depending on your billing frequency, this will be your Prodigi Invoice Number or null. Set by Prodigi.
totalCost Cost n/a Total of all individual charges. Set by Prodigi.
items array of ChargeItems n/a Individual items associated with this charge. Set by Prodigi.

Cost

A generic field that represents the debit or credit for a given item.

Parameter Type Required Description
amount string n/a Amount charged. Positive is debit, negative is credit. Set by Prodigi.
currency string n/a Three-letter ISO currency code for this amount. Set by Prodigi.

Charge item

Parameter Type Required Description
id string n/a Unique ID for this charge item. Set by Prodigi.
shipmentId string n/a Shipment ID for the charge item, or null for product charge items. Set by Prodigi.
itemId string n/a Item ID, corresponding to the array of items at the top of the order. Null for shipping charge items. Set by Prodigi.
cost Cost n/a Cost breakdown for this item. Set by Prodigi.

Shipment

Parameter Type Required Description
id string n/a Unique ID for this shipment. Set by Prodigi.
status string n/a A status indicator for the shipment expected values are: Processing The shipment has yet to be shipped, Cancelled the shipment has been cancelled and Shipped The shipment has been shipped.
carrier carrier n/a Carrier for this shipment. Set by Prodigi.
tracking tracking n/a Tracking information for this shipment. Only be set if an shipment can be tracked. Set by Prodigi.
dispatchDate datetime n/a When the lab despatched this shipment. Set by Prodigi.
items array of Shipment Items n/a Helps identify the items in this shipment. Set by Prodigi.
tracking tracking n/a Url and number of tracking information.
fulfillmentLocation fulfillmentLocation n/a Country and lab fulfilling the shipment.

Shipment Item

Parameter Type Required Description
itemId string n/a Unique ID for the item that is included as part of the shipment. Set by Prodigi.

Fulfillment location

Parameter Type Required Description
countryCode string n/a The two-letter ISO country code from where the items will be fulfilled.
labCode string n/a The identifying code of the lab fulfilling the items.

Tracking

Parameter Type Required Description
url string n/a A Url that will provide shipment status via a 3rd party tracking service.
number string n/a The shipment carriers tracking number.

Item

Parameter Type Required Description
id string n/a Unique ID for this order item. Set by Prodigi.
status string n/a A status indicator for the item expected values are: Ok nothing wrong with this item, Invalid one or more assets have failed to download and NotYetDownloaded the assets associated with this item are yet to be downloaded.
merchantReference string no Your personal reference for this item.
sku string yes The Prodigi SKU of the product. Use the lookups endpoints to find out more information on each SKU.
copies integer yes Quantity of items
sizing string yes The sizing strategy for us to use. The value should be one of fillPrintArea, fitPrintArea or stretchToPrintArea. More information can be found in our image resizing section.
recipientCost Cost no The price you charged the recipient for these items. While not required, it's highly recommended if you have international orders as it aids shipping companies with customs issues.
attributes hashtable no Product attributes, such as a frame colour. Use the lookups endpoints to find a product's available attributes.
assets array of Assets yes File assets for this order item, i.e. the image file(s).

Asset

An Asset is an image belonging to a product. Our products support zero, one or many images per item, and the item's assets array determines the location of each image on the product. For a full list of which assets a given product supports, use the product lookup endpoint.

Parameter Type Required Description
printArea string yes Name of the assets print area. Default value is default. Examples of other print areas include spine (for photobooks) and lid (for jigsaws).
status string n/a The status of the asset in terms of availability to be processed in production. Values are complete the asset has been downloaded for production, inProgress the asset is yet to be downloaded and error there has been a problem downloading the asset.
url string yes URL of the asset.
thumbnailUrl string yes URL of the item asset. Please not this may not be present until after the asset has been downloaded and the item allocated a shipment.
md5Hash string no If supplied then the image file will be used to generate a corresponding hash that must match this.

Packing slip

Parameter Type Required Description
url string no URL of the packing slip file
status string no Status of the packing slip. Set by Prodigi.

Idempotency key

TheidempotencyKey is an optional property that can help us determine if your order is a duplicate of an earlier order. If not supplied, the order will not be checked for duplicates.

Most merchants can guarantee that we will only receive one request for one order, so the idempotency key would not be required. For others who may be running distributed systems where it can be harder to guarantee a single request for a single order, the use of the idempotencyKey is recommended: a string that is unique to this order.

While the idempotency key can be a simple string, we recommended that you use a GUID of some form to avoid clashes. We remember all your idempotency keys indefinitely, so you need a key of sufficient complexity.

Internally, the idempotency key is scoped to your account, so another merchant's key will never conflict with yours.

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.

Sizing mode Default? Description
fillPrintArea yes 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.
fitPrintArea no 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.
stretchToPrintArea no 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.

Create order

POST/v4.0/orders 
curl "https://api.sandbox.prodigi.com/v4.0/Orders" \
  -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '
    {
        "merchantReference": "MyMerchantReference1",
        "shippingMethod": "Overnight",
        "recipient": {
            "name": "Mr Testy McTestface",
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": null
            }
        },
        "items": [
            {
                "merchantReference": "item #1",
                "sku": "GLOBAL-CFPM-16X20",
                "copies": 1,
                "sizing": "fillPrintArea",
                "attributes": {
                    "color": "black"
                },
                "recipientCost": {
                    "amount": "15.00",
                    "currency": "USD"
                },
                "assets": [
                    {
                        "printArea": "default",
                        "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                        "md5Hash": "daa1c811c6038e718a23f0d816914b7b"
                    }
                ]
            }
        ],
        "metadata": {
            "mycustomkey":"some-guid",
            "someCustomerPreference": {
                "preference1": "something",
                "preference2": "red"
            },
            "sourceId": 12345
        }
    }
  '
Response 
{
    "outcome": "Created",
    "order": {
        "id": "ord_840797",
        "created": "2021-03-11T14:40:05.12Z",
        "lastUpdated": "2021-03-11T14:40:05.2018442Z",
        "callbackUrl": null,
        "merchantReference": "MyMerchantReference1",
        "shippingMethod": "Overnight",
        "idempotencyKey": null,
        "status": {
            "stage": "InProgress",
            "issues": [],
            "details": {
                "downloadAssets": "NotStarted",
                "printReadyAssetsPrepared": "NotStarted",
                "allocateProductionLocation": "NotStarted",
                "inProduction": "NotStarted",
                "shipping": "NotStarted"
            }
        },
        "charges": [],
        "shipments": [],
        "recipient": {
            "name": "Mr Test",
            "email": null,
            "phoneNumber": null,
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": null
            }
        },
        "items": [
            {
                "id": "ori_926887",
                "status": "NotYetDownloaded",
                "merchantReference": "item #1",
                "sku": "GLOBAL-CFPM-16X20",
                "copies": 1,
                "sizing": "fillPrintArea",
                "attributes": {
                    "color": "black"
                },
                "assets": [
                    {
                        "id": "ast_114059",
                        "printArea": "default",
                        "md5Hash": "daa1c811c6038e718a23f0d816914b7b",
                        "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                        "status": "InProgress"
                    }
                ],
                "recipientCost": {
                    "amount": "10.74",
                    "currency": "GBP"
                }
            }
        ],
        "packingSlip": null,
        "metadata": {
            "mycustomkey": "some-guid",
            "someCustomerPreference": {
                "preference1": "something",
                "preference2": "red"
            },
            "sourceId": 12345
        }
    },
    "traceParent": "00-f68685c43545e048bc44d9bc8239d59a-967255597477ac40-00"
}

POSTing to the /orders endpoint submits and creates your order in Prodigi.

Once an order is submitted and any configured order pause window expires, it begins the process of fulfillment.

Where an order has been submitted and is paused only the order ID is returned in the initial response, with the order status being set to "on hold". For orders in this state, you can continue to make updates to the order via the Prodigi dashboard. Once the pause window expires, a web-hook is triggered containing the full order details.

Please refer to the Order actions section on more information about updating existing orders. Once an order passes into fulfilment, it can no longer be changed or cancelled.

Create order outcomes

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
created 200 Order created.
onHold 200 Order created on hold due to order edit window preference.
createdWithIssues 200 Order created but contains issues that need fixing.
alreadyExists 200 Order with the same idempotency key already exists. The new order has not been created, and we have returned the existing order.

Get order by ID

GET/v4.0/orders/{prodigi_order_id} 
curl "https://api.sandbox.prodigi.com/v4.0/orders/ord_677258" \
  -X GET \
  -H "X-API-Key: your-api-key"
Response 
{
    "outcome": "Ok",
    "order": {
        "id": "ord_840797",
        "created": "2021-03-11T14:40:05.12Z",
        "lastUpdated": "2021-03-11T14:40:05.203Z",
        "callbackUrl": null,
        "merchantReference": "MyMerchantReference1",
        "shippingMethod": "Overnight",
        "idempotencyKey": null,
        "status": {
            "stage": "InProgress",
            "issues": [],
            "details": {
                "downloadAssets": "NotStarted",
                "printReadyAssetsPrepared": "NotStarted",
                "allocateProductionLocation": "NotStarted",
                "inProduction": "NotStarted",
                "shipping": "NotStarted"
            }
        },
        "charges": [],
        "shipments": [],
        "recipient": {
            "name": "Mr Test",
            "email": null,
            "phoneNumber": null,
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": null
            }
        },
        "items": [
            {
                "id": "ori_926887",
                "status": "NotYetDownloaded",
                "merchantReference": "item #1",
                "sku": "GLOBAL-CFPM-16X20",
                "copies": 1,
                "sizing": "fillPrintArea",
                "attributes": {
                    "color": "black"
                },
                "assets": [
                    {
                        "id": "ast_114059",
                        "printArea": "default",
                        "md5Hash": "daa1c811c6038e718a23f0d816914b7b",
                        "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                        "status": "InProgress"
                    }
                ],
                "recipientCost": {
                    "amount": "10.74",
                    "currency": "GBP"
                }
            }
        ],
        "packingSlip": null,
        "metadata": {
            "mycustomkey": "some-guid",
            "someCustomerPreference": {
                "preference1": "something",
                "preference2": "red"
            },
            "sourceId": 12345
        }
    },
    "traceParent": "00-ef2d62064c7b224690a9578e84f4c617-150bbac7b6406e46-00"
}

This endpoint returns an Order for a given Prodigi order ID where the order has been submitted for fulfilment and any configured pause window has expired.

Get Order by ID Outcomes

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
ok 200 The request was understood and a relevant response was returned.

Get orders

GET/v4.0/orders 
curl "https://api.sandbox.prodigi.com/v4.0/orders" \
  -X GET \
  -H "X-API-Key: your-api-key"

This endpoint returns a list of Orders for the given filtering options.

All of these options are optional. If none are provided, their defaults will be used. Results are sorted by Prodigi order ID (descending).

Name Type Default Description
top int 10 Number of orders to return. Must be 1–100.
skip int 0 Number of records to skip before the next top worth of orders. Must be greater than or equal to 0.
createdFrom datetime null Limit to orders placed after this date/time (UTC). Can be used without createdTo.
createdTo datetime null Limit to orders placed before this date/time (UTC). Can be used without createdFrom.
status string null Limit to a particular status. Valid status values are draft, awaitingPayment, inProgress, complete, cancelled.
orderIds array null Limit to a list of Prodigi order IDs.
merchantReferences array null Limit to a range of your order references.

Response

Response 
{
    "outcome": "Ok",
    "orders": [
        {
            "id": "ord_840797",
            // rest of the order
        },
        {
            "id": "ord_839555",
            // rest of the order
        },
        {
            "id": "ord_838659",
            // rest of the order
        },
        {
            "id": "ord_838055",
            // rest of the order
        }
    ],
    "hasMore": true,
    "nextUrl": "https://api.sandbox.prodigi.com/v4.0/Orders?Skip=10",
    "traceParent": "00-cb879e84d8c70a45b5742d34be5f3a6d-4535bc8797a33c49-00"
}
Name Type Description
orders array of Orders Each order is identical to that returned by Get Order by ID.
hasMore boolean True if there are more results available.
nextUrl string If HasMore is true, contains the full URL to the next page of orders.

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
ok 200 The request was understood and a relevant response was returned.

Order actions

Get actions

GET/v4.0/orders/{prodigi_order_id}/actions 
curl "https://api.sandbox.prodigi.com/v4.0/Orders/ord_123456/actions" \
  -X GET \
  -H "X-API-Key: your-api-key"
Response 
{
    "outcome": "Ok",
    "cancel": {
        "isAvailable": "Yes"
    },
    "changeRecipientDetails": {
        "isAvailable": "Yes"
    },
    "changeShippingMethod": {
        "isAvailable": "Yes"
    },
    "changeMetaData": {
        "isAvailable": "Yes"
    },
    "traceParent": "00-e5bcd15ebc235043bf43b6fb209de64e-72320d4625a34a40-00"
}

There are 4 actions you can take against an order before it is in fulfilment:

  • Cancel
  • Update shipping method
  • Update recipient details
  • Update metadata

You can find out which actions are currently valid for a given order by sending a GET request to the order's actions endpoint: Orders/{prodigi_order_id}/actions.

Request parameters

Parameter Description
prodigi_order_id The Prodigi ID of the order.

Response

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
ok 200 The request was understood and a relevant response was returned.

Cancel an order

POST/v4.0/orders/{prodigi_order_id}/actions/cancel 
curl "https://api.sandbox.prodigi.com/v4.0/orders/ord_123456/actions/cancel" \
  -X POST \
  -H "X-API-Key: your-api-key"
Response 
{
    "outcome": "Cancelled",
    "order": {
        "id": "ord_840797",
        "created": "2021-03-11T14:40:05.12Z",
        "lastUpdated": "2021-03-11T15:04:08.0923435Z",
        "callbackUrl": null,
        "merchantReference": "MyMerchantReference1",
        "shippingMethod": "Overnight",
        "idempotencyKey": null,
        "status": {
            "stage": "Cancelled",
            "issues": [],
            "details": {
                "downloadAssets": "NotStarted",
                "printReadyAssetsPrepared": "NotStarted",
                "allocateProductionLocation": "NotStarted",
                "inProduction": "NotStarted",
                "shipping": "NotStarted"
            }
        },
        "charges": [],
        "shipments": [],
        "recipient": {
            "name": "Mr Test",
            "email": null,
            "phoneNumber": null,
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": null
            }
        },
        "items": [
            {
                "id": "ori_926887",
                "status": "NotYetDownloaded",
                "merchantReference": "item #1",
                "sku": "GLOBAL-CFPM-16X20",
                "copies": 1,
                "sizing": "fillPrintArea",
                "attributes": {
                    "color": "black"
                },
                "assets": [
                    {
                        "id": "ast_114059",
                        "printArea": "default",
                        "md5Hash": "daa1c811c6038e718a23f0d816914b7b",
                        "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                        "status": "InProgress"
                    }
                ],
                "recipientCost": {
                    "amount": "10.74",
                    "currency": "GBP"
                }
            }
        ],
        "packingSlip": null,
        "metadata": {
            "mycustomkey": "some-guid",
            "someCustomerPreference": {
                "preference1": "something",
                "preference2": "red"
            },
            "sourceId": 12345
        }
    },
    "traceParent": "00-fd6711a9793bd648b0f83300e73dcd10-0eefc6d035357d42-00"
}

Sending a POST request to the actions/cancel endpoint for a specific prodigi_order_id attempts to cancel the entire order.

Where an order is not yet in fulfilment, the full order will be refunded. Once an order is in fulfilment, and any configured pause window has expired, the shipping charge will be refunded, in line with our terms and conditions.

If all of the items in the order are cancelled, the resulting returned order will have a status of cancelled and all of its shipments will likewise show cancelled: true.

If, however, we are only able to cancel some of the items, the resulting order will not have a cancelled status and the uncancelled shipments will have cancelled: false.

Request parameters

Parameter Description
prodigi_order_id The Prodigi ID of the order to cancel.

Cancel order outcomes

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
cancelled 200 Order successfully cancelled.
failedToCancel 200 We could not cancel the order. It could be already in production and too late to cancel.
actionNotAvailable 200 Order cannot be cancelled at this time.

Pause an order

By default all orders submitted via the Print API will be submitted and sent to fulfilment immediately.

Through the Prodigi dashboard you can configure a pause window for all orders to adhere to, either by setting an amount of time for all orders to be paused, or you can configure orders to be paused indefinitely, requiring orders to then be submitted manually through the dashboard.

Once a configured pause window expires, the order will submit for fulfilment and a callback will be sent informing you of this.

Update shipping method

POST/v4.0/orders/{prodigi_order_id}/actions/updateShippingMethod 
curl "https://api.sandbox.prodigi.com/v4.0/Orders/ord_123456/actions/updateShipping" \
  -X POST \
  -H "X-API-Key: your-api-key" \
  -d '{ "shippingMethod": "Budget" }'
Response 
{
    "outcome": "Updated",
    "shippingUpdateResults": [],
    "order": {
        "id": "ord_840799",
        "created": "2021-03-11T15:06:40.697Z",
        "lastUpdated": "2021-03-11T15:06:46.2816154Z",
        "callbackUrl": null,
        "merchantReference": "MyMerchantReference1",
        "shippingMethod": "Express",
        "idempotencyKey": null,
        "status": {
            "stage": "InProgress",
            "issues": [],
            "details": {
                "downloadAssets": "NotStarted",
                "printReadyAssetsPrepared": "NotStarted",
                "allocateProductionLocation": "NotStarted",
                "inProduction": "NotStarted",
                "shipping": "NotStarted"
            }
        },
        "charges": [],
        "shipments": [],
        "recipient": {
            "name": "Mr Testy McTestface",
            "email": null,
            "phoneNumber": null,
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": null
            }
        },
        "items": [
            {
                "id": "ori_926889",
                "status": "NotYetDownloaded",
                "merchantReference": "item #1",
                "sku": "GLOBAL-CFPM-16X20",
                "copies": 1,
                "sizing": "fillPrintArea",
                "attributes": {
                    "color": "black"
                },
                "assets": [
                    {
                        "id": "ast_114059",
                        "printArea": "default",
                        "md5Hash": "daa1c811c6038e718a23f0d816914b7b",
                        "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                        "status": "InProgress"
                    }
                ],
                "recipientCost": {
                    "amount": "10.74",
                    "currency": "GBP"
                }
            }
        ],
        "packingSlip": null,
        "metadata": {
            "mycustomkey": "some-guid",
            "someCustomerPreference": {
                "preference1": "something",
                "preference2": "red"
            },
            "sourceId": 12345
        }
    },
    "traceParent": "00-a80b88df69bd0e45a923cc4d9f858978-5eaad925e38cd348-00"
}

Request parameters

Name Type Required Description
prodigi_order_id string yes Prodigi ID of the order you wish to update.
shipping_method string yes One of Budget, Standard, Express, Overnight.

Response object

Name Type Description
order Order The amended order.
shipmentUpdateResults array of ShipmentDetails An array of ShipmentDetails objects.

ShipmentDetail object

Name Type Description
shipmentId string Shipment identifier.
successful boolean Whether the update succeeded.

Update shipping method Outcomes

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
updated 200 Shipping method updated against the order and all shipments.
partiallyUpdated 200 Shipping method updated against the order and some shipments, but at least one shipment could not be updated.
failedToUpdate 200 No shipments could be updated, so the order has not been updated.
actionNotAvailable 200 We are no longer able to update any shipments, so this action is unavailable.

Update recipient

POST/v4.0/orders/{prodigi_order_id}/actions/updateRecipient 
curl "https://api.sandbox.prodigi.com/v4.0/Orders/ord_123456/actions/updateRecipient" \
  -X POST \
  -H "X-API-Key: your-api-key" \
  -d '{
        "name": "Mr. Jeff Testing",
        "email": "jeff.testing@test.co.uk",
        "phoneNumber": "123456780",
        "address" : {
                      "line1": "14 test place",
                      "line2": "test",
                      "postalOrZipCode": "12345",
                      "countryCode": "US",
                      "townOrCity": "MyTown",
                      "stateOrCounty": null
                    }
      }'
Response 
{
    "outcome": "Updated",
    "shipmentUpdateResults": [],
    "order": {
        "id": "ord_840799",
        "recipient": {
            "name": "Mr. Jeff Testing",
            "email": "jeff.testing@test.co.uk",
            "phoneNumber": "123456780",
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "MyTown",
                "stateOrCounty": null
            }
        },
        // rest of the order
    },
    "traceParent": "00-e3466ad67db82340aa97a337e5c9ea91-edb742f49fc22c46-00"
}

Request parameters

Name Type Required Description
prodigi_order_id string yes Prodigi ID of the order to update.
recipient Recipient yes Amended recipient details.

Recipient object

Parameter Type Required Description
Name string yes Full name of the recipient
Email string yes Recipient's email
PhoneNumber string yes Recipient's primary contact number
Address Address yes Recipient's address

Recipient Address object

Parameter Type Required Description
line1 string yes First line of recipient's address.
line2 string yes Second line of recipient's address.
townOrCity string yes Town or city of recipient's address.
stateOrCounty string yes State or county of the recipient's address.
postalOrZipCode string yes Postcode or zip code of recipient's address.
countryCode string yes Two-letter ISO country code of recipient's address.

Response

HTTP status code Description
200 Returns an UpdateRecipientResponse object.
400 Failed to update the recipient, most likely because of an invalid prodigi_order_id.

UpdateRecipientResponse object

Name Type Description
order Order The amended order.
shipmentResult array of ShipmentDetails An array of ShipmentDetail objects.
result string One of completed, partiallyComplete, failed.

ShipmentDetail object

Name Type Description
shipmentId string The shipment identifier.
successful boolean Whether the update succeeded.
errorCode string One of order.shipments.updateFailed, order.shipments.invalid, order.shipments.notAvailable.
description string Error code description.

Update recipient outcomes

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
updated 200 Recipient updated in the order and all shipments.
partiallyUpdated 200 Recipient updated in the order and some shipments, but at least one shipment could not be updated.
failedToUpdate 200 No shipments could be updated so the order has not been updated.
actionNotAvailable 200 We are no longer able to update any shipments, so this action is unavailable.

Update metadata

POST/v4.0/orders/{prodigi_order_id}/actions/updatemetadata 
curl "https://api.sandbox.prodigi.com/v4.0/Orders/ord_123456/actions/updateMetadata" \
  -X POST \
  -H "X-API-Key: your-api-key" \
  -d '{ 
        "metadata" : { 
            "internalRef" : "abdef",
            "templateSize" : 1,
            "feedback" : {
                "message": "some message",
                "stars": 5
            }
        }
      }'
Response 
{
    "outcome": "Updated",
    "order": {
        "id": "ord_840799",
        "created": "2021-03-11T15:06:40.697Z",
        "lastUpdated": "2021-03-11T15:14:28.9200361Z",
        "callbackUrl": null,
        "merchantReference": "MyMerchantReference1",
        "shippingMethod": "Express",
        "idempotencyKey": null,
        "status": {
            "stage": "InProgress",
            "issues": [],
            "details": {
                "downloadAssets": "NotStarted",
                "printReadyAssetsPrepared": "NotStarted",
                "allocateProductionLocation": "NotStarted",
                "inProduction": "NotStarted",
                "shipping": "NotStarted"
            }
        },
        "charges": [],
        "shipments": [],
        "recipient": {
            "name": "Mr Test",
            "email": null,
            "phoneNumber": null,
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": null
            }
        },
        "items": [
            {
                "id": "ori_926889",
                "status": "NotYetDownloaded",
                "merchantReference": "item #1",
                "sku": "GLOBAL-CFPM-16X20",
                "copies": 1,
                "sizing": "fillPrintArea",
                "attributes": {
                    "color": "black"
                },
                "assets": [
                    {
                        "id": "ast_114059",
                        "printArea": "default",
                        "md5Hash": "daa1c811c6038e718a23f0d816914b7b",
                        "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                        "status": "InProgress"
                    }
                ],
                "recipientCost": {
                    "amount": "10.74",
                    "currency": "GBP"
                }
            }
        ],
        "packingSlip": null,
        "metadata": {
            "internalRef": "abdef",
            "templateSize": 1,
            "feedback": {
                "message": "some message",
                "stars": 5
            }
        }
    },
    "traceParent": "00-0229c7d0a6e3814b98806af95599c00d-c6ba62fadb84e346-00"
}

Updating an order's metadata replaces the existing metadata on the order entirely.

You can update an order's metadata at any time in order process, including after completion.

Request parameters

Name Type Required Description
prodigi_order_id string yes Prodigi ID of the order to update.
metadata json yes Data to replace the current metadata.

Response

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
updated 200 Metadata updated successfully.

Quotes

The Quote endpoint allows you to get pricing and shipping information about a given set of products without creating an order. It returns how the order will be fulfilled, including:

  • The fulfillment location
  • The cost of the products
  • The cost of shipping
  • The couriers of each shipment

Quote object

Quote object 
{
    "outcome": "Ok",
    "quotes": [
        {
            "shipmentMethod": "Budget",
            "costSummary": {
                "items": {
                    "amount": "7.50",
                    "currency": "GBP"
                },
                "shipping": {
                    "amount": "1.50",
                    "currency": "GBP"
                }
            },
            "shipments": [
                {
                    "carrier": {
                        "name": "royalmail",
                        "service": "Standard"
                    },
                    "fulfillmentLocation": {
                        "countryCode": "GB",
                        "labCode": "uk6"
                    },
                    "cost": {
                        "amount": "1.50",
                        "currency": "GBP"
                    },
                    "items": [
                        "qit_cf79d209cf3e40ff8a56861f50d8937a"
                    ]
                }
            ],
            "items": [
                {
                    "id": "qit_cf79d209cf3e40ff8a56861f50d8937a",
                    "sku": "GLOBAL-TECH-IP11P-FC-CP",
                    "copies": 1,
                    "unitCost": {
                        "amount": "7.50",
                        "currency": "GBP"
                    },
                    "attributes": {},
                    "assets": [
                        {
                            "printArea": "default"
                        }
                    ]
                }
            ]
        }
    ]
}

The Quote endpoint returns an array of Quotes.

Each Quote provides pricing information for products and shipments based on a specific shipping method.

If a shippingMethod is specified for a Quote, only that shipping method is returned. If a shippingMethod is not specified, a Quote for each of the four shipping methods is returned: budget, standard, express and overnight.

Top level

Property Type Description
quotes array of Quotes One quote for each shipping method.

Quote

Property Type Description
shipmentMethod string Shipping method for this quote. One of budget,standard,express or overnight.
costSummary CostSummary Summary of total costs.
shipments array of Shipments Expected courier details, cost and included items.
items array of Items The order items, with an id matching the item in each shipment.

Cost summary

Property Type Description
items Cost Total cost of the items in the quote.
shipping Cost Total cost of the shipping in the quote.

Shipment

Property Type Description
carrier Carrier The carrier and service.
fulfillmentLocation fulfillmentLocation Country and lab fulfilling the shipment.
cost Cost Cost of the shipment.
items array of strings The Item IDs that make up the shipment.

Carrier

Property Type Description
name string The name of the carrier.
service string The name of the carrier service.

Fulfillment location

Property Type Description
countryCode string The two-letter ISO country code from where the items will be fulfilled.
labCode string The identifying code of the lab fulfilling the items.

Item

The Item object is the same as the request Item object except it has the addition of an id property. This is to help identify the items that belong to each shipment.

Property Type Description
id string ID of the Item, referenced in the shipment object.
sku string Prodigi SKU of the product. Use the Product Details endpoint for full SKU information.
copies integer Number of copies/quantity.
unitCost Cost Cost of each individual item.
attributes hashtable Product attributes, such as a frame colour. The Product Details endpoint returns a SKU's available attributes.
assets array of Assets Expected assets. Some additional assets may incur additional costs.

Cost

Property Type Description
amount string Cost value. A decimal value as a string.
currency string The ISO currency code of this amount.

Issues

The issues array contains the details of any order issues.

Value Type Description
errorCode string A code that indicates the type the error:
  • destinationCountryCode.UsSalesTaxWarning
    A warning that indecates that the prices may be subject to US sales tax.
description string A human-readable description of the error.

Create Quote

POST/v4.0/quotes 
curl "https://api.sandbox.prodigi.com/v4.0/quotes" \
  -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '
    {
        "shippingMethod": "Budget",
        "destinationCountryCode": "GB",
        "currencyCode":"GBP",
        "items": [
            {
                "sku": "GLOBAL-CAN-10x10",
                "copies": 5,
                "attributes": { "wrap":"ImageWrap" },
                "assets" : [
                    { "printArea" : "default" }
                ]
            },
            {
                "sku": "GLOBAL-FAP-10x10",
                "copies": 1,
                "attributes": { },
                "assets" : [
                    { "printArea" : "default" }
                ]
            }
        ]
    }
  '
Response 
{
    "outcome": "Created",
    "quotes": [
        {
            "shipmentMethod": "Budget",
            "costSummary": {
                "items": {
                    "amount": "79.35",
                    "currency": "GBP"
                },
                "shipping": {
                    "amount": "19.46",
                    "currency": "GBP"
                }
            },
            "shipments": [
                {
                    "carrier": {
                        "name": "Mixed",
                        "service": "Mixed"
                    },
                    "fulfillmentLocation": {
                        "countryCode": "US",
                        "labCode": "us11"
                    },
                    "cost": {
                        "amount": "17.96",
                        "currency": "GBP"
                    },
                    "items": [
                        "qit_f1c1f62b8fd0486da831c9438e89bc25"
                    ]
                },
                {
                    "carrier": {
                        "name": "royalmail",
                        "service": "Standard"
                    },
                    "fulfillmentLocation": {
                        "countryCode": "GB",
                        "labCode": "uk6"
                    },
                    "cost": {
                        "amount": "1.50",
                        "currency": "GBP"
                    },
                    "items": [
                        "qit_a904222e1c964440870f3400bd2d5973"
                    ]
                }
            ],
            "items": [
                {
                    "id": "qit_f1c1f62b8fd0486da831c9438e89bc25",
                    "sku": "GLOBAL-CAN-10X10",
                    "copies": 5,
                    "unitCost": {
                        "amount": "14.37",
                        "currency": "GBP"
                    },
                    "attributes": {
                        "wrap": "ImageWrap"
                    },
                    "assets": [
                        {
                            "printArea": "default"
                        }
                    ]
                },
                {
                    "id": "qit_a904222e1c964440870f3400bd2d5973",
                    "sku": "GLOBAL-TECH-IP11P-FC-CP",
                    "copies": 1,
                    "unitCost": {
                        "amount": "7.50",
                        "currency": "GBP"
                    },
                    "attributes": {},
                    "assets": [
                        {
                            "printArea": "default"
                        }
                    ]
                }
            ]
        }
    ]
}

Requests to the Quote endpoint use a stripped-down structure similar to the Order object.

Top level

Property Type Required Description
shippingMethod string no Your requested shipping method: either budget, standard,express or overnight.
destinationCountryCode string yes Two-letter ISO country code country code of the destination country.
currencyCode string no Three-letter ISO currency code. If not provided, the currency code specified within your merchant settings is used.
items array of Items yes The items to be quoted.

Item

Parameter Type Required Description
sku string yes Prodigi SKU of the product. The Product Details endpoint returns a SKU's available attributes.
copies integer yes Number of copies.
attributes hashtable no Product attributes, such as a frame colour. The Product Details endpoint returns a SKU's available attributes.
assets array of Assets yes Expected assets. Some assets may incur an additional cost.

Assets

Parameter Type Required Description
printArea string yes Available print areas.

Create quote outcomes

In addition to the General outcomes, this endpoint can also return:

Outcome Status code Description
created 200 Quote created.
createdWithIssues 200 Quote created but contains issues that should be noted.

Product details

The Product Details endpoint returns all available data for a SKU, such as price, attributes, and its required assets and dimensions.

Product Details object

Product Details Object 
{
    "sku": "GLOBAL-CAN-10X10",
    "description": "Standard canvas on quality stretcher bar, 25x25cm",
    "productDimensions": {
        "width": 10.0000,
        "height": 10.0000,
        "units": "in"
    },
    "attributes": {
        "wrap": [
            "Black",
            "ImageWrap",
            "MirrorWrap",
            "White"
        ]
    },
    "printAreas": {
        "default": {
            "required": true
        }
    },
    "variants": [
        {
            "attributes": {
                "wrap": "Black"
            },
            "shipsTo": [
                "IM",
                "LU",
                "ID",
                "CI",
                "GR",
                "FK",
                "AL",
                "LA",
                "KY"
            ],
            "printAreaSizes": {
                "default": {
                    "horizontalResolution": 1522,
                    "verticalResolution": 1522
                }
            }
        },
        {
            "attributes": {
                "wrap": "ImageWrap"
            },
            "shipsTo": [
                "IM",
                "LU",
                "ID",
                "CI",
                "GR",
                "FK",
                "AL",
                "LA",
                "KY"
            ],
            "printAreaSizes": {
                "default": {
                    "horizontalResolution": 2137,
                    "verticalResolution": 2137
                }
            }
        },
        {
            "attributes": {
                "wrap": "MirrorWrap"
            },
            "shipsTo": [
                "IM",
                "LU",
                "ID",
                "CI",
                "GR",
                "FK",
                "AL",
                "LA",
                "KY"
            ],
            "printAreaSizes": {
                "default": {
                    "horizontalResolution": 1522,
                    "verticalResolution": 1522
                }
            }
        },
        {
            "attributes": {
                "wrap": "White"
            },
            "shipsTo": [
                "IM",
                "LU",
                "ID",
                "CI",
                "GR",
                "FK",
                "AL",
                "LA",
                "KY"
            ],
            "printAreaSizes": {
                "default": {
                    "horizontalResolution": 1522,
                    "verticalResolution": 1522
                }
            }
        }
    ]
}

The Product Details object contains all the information about each product you've requested

Top level

Property Type Description
sku string Our stock-keeping unit identifer for the product.
description string Full name & description of the product.
productDimensions ProductDimensions Size of the product.
attributes hashtable of Attributes Attributes (name and values) applicable to the product.
print areas hashtable of PrintAreas Available printable areas for the product.
variants array of Variants Available variants for the product.

Product dimensions

Property Type Description
width decimal Width of the product.
height decimal Height of the product.
units string Units of measurement of the width and height.

Attribute

Property Type Description
name string Attribute name. e.g. color, mountColor, size, wrap, etc.
values array of strings Possible values for this attribute.

Print Area

Property Type Description
required boolean Whether an asset must be supplied for this print area.

Variant

Property Type Description
attributes hashtable of Attributes The specific attribute name and value for this variant.
shipsTo array of strings an array of country codes
printAreaSizes hashtable of PrintAreaDimensions a dictionary keyed on print area name containing the dimensions for the specific variant

Print area dimensions

Property Type Description
horizontalResolution long the recommended horizontal size of the print area in pixels
verticalResolution long the recommended vertical size of the print area in pixels

Get Product Details

GET/v4.0/products 
curl "https://api.sandbox.prodigi.com/v4.0/products/GLOBAL-CAN-10x10" \
  -X GET \
  -H "X-API-Key: your-api-key"
Response 
{
    "outcome": "Ok",
    "product": {
        "sku": "GLOBAL-CAN-10X10",
        "description": "Standard canvas on quality stretcher bar, 25x25cm",
        "productDimensions": {
            "width": 10.0000,
            "height": 10.0000,
            "units": "in"
        },
        "attributes": {
            "wrap": [
                "Black",
                "ImageWrap",
                "MirrorWrap",
                "White"
            ]
        },
        "printAreas": {
            "default": {
                "required": true
            }
        },
        "variants": [
            {
                "attributes": {
                    "wrap": "Black"
                },
                "shipsTo": [
                    "IM",
                    "LU",
                    "ID",
                    "CI",
                    "GR",
                    "FK",
                    "AL",
                    "LA",
                    "KY"
                ],
                "printAreaSizes": {
                    "default": {
                        "horizontalResolution": 1522,
                        "verticalResolution": 1522
                    }
                }
            },
            {
                "attributes": {
                    "wrap": "ImageWrap"
                },
                "shipsTo": [
                    "IM",
                    "LU",
                    "ID",
                    "CI",
                    "GR",
                    "FK",
                    "AL",
                    "LA",
                    "KY"
                ],
                "printAreaSizes": {
                    "default": {
                        "horizontalResolution": 2137,
                        "verticalResolution": 2137
                    }
                }
            },
            {
                "attributes": {
                    "wrap": "MirrorWrap"
                },
                "shipsTo": [
                    "IM",
                    "LU",
                    "ID",
                    "CI",
                    "GR",
                    "FK",
                    "AL",
                    "LA",
                    "KY"
                ],
                "printAreaSizes": {
                    "default": {
                        "horizontalResolution": 1522,
                        "verticalResolution": 1522
                    }
                }
            },
            {
                "attributes": {
                    "wrap": "White"
                },
                "shipsTo": [
                    "IM",
                    "LU",
                    "ID",
                    "CI",
                    "GR",
                    "FK",
                    "AL",
                    "LA",
                    "KY"
                ],
                "printAreaSizes": {
                    "default": {
                        "horizontalResolution": 1522,
                        "verticalResolution": 1522
                    }
                }
            }
        ]
    }
}

This endpoint returns the Product Details for the requested SKU.

Get photobook spine details

POST/v4.0/products/spine 
curl "https://api.prodigi.com/v4.0/products/spine" \
  -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '
    {
        "sku": "BOOK-A4-L-HARD-M",
        "destinationCountryCode": "US",
        "state": "CA",
        "numberOfPages": 50
    }
Response 
{
    "success": true,
    "message": "Spine info retrieved (or appropriate error message)",
    "spineInfo": {
        "widthMm": 25.4
    }
}

This endpoint returns the required width of the book spine required for a book with the provided number of pages going to a particular destination country.

Callbacks

Sample callback 
{
    "specversion": "1.0",
    "type": "com.prodigi.order.status.stage.changed#InProgress",
    "source": "http://api.prodigi.com/v4.0/Orders/",
    "id": "evt_305174",
    "time": "2020-08-14T11:51:01.55Z",
    "datacontenttype": "application/json",
    "data": {
      "order": {
        "id": "ord_1469466",
        "created": "2020-08-14T11:50:54.557Z",
        "status": {
          "stage": "InProgress",
          "issues": [],
          "details": {
            "downloadAssets": "InProgress",
            "printReadyAssetsPrepared": "NotStarted",
            "allocateProductionLocation": "NotStarted",
            "inProduction": "NotStarted",
            "shipping": "NotStarted"
          }
        },
        "charges": [],
        "shipments": [],
        "merchantReference": "1",
        "shippingMethod": "Budget",
        "recipient": {
          "name": "Pwinty Test Order",
          "address": {
            "line1": "123 Test Street",
            "line2": "TESTERTON",
            "postalOrZipCode": "TE5 7IN",
            "countryCode": "US",
            "townOrCity": "TEST CITY",
            "stateOrCounty": "TESTSHIRE"
          },
          "email": "mike.hole@prodigi.com",
          "mobilePhoneNumber": "07987654321"
        },
        "items": [
          {
            "id": "ori_1430070",
            "status": "NotYetDownloaded",
            "sku": "GLOBAL-PHO-12X16-PRO-LUS-UK1",
            "copies": 1,
            "sizing": "fillPrintArea",
            "attributes": {},
            "assets": [
              {
                "id": "ast_116447",
                "status": "InProgress",
                "printArea": "default",
                "url": "https://pwintytest.blob.core.windows.net/sample-media/mike/TestCard.png"
              }
            ],
            "recipientCost": {
              "amount": "543.21",
              "currency": "USD"
            }
          }
        ],
        "packingSlip": {
          "url": "https://pwintytest.blob.core.windows.net/sample-media/mike/PackingSlip.png",
          "status": "NotYetDownloaded"
        }
      }
    },
    "subject": "ord_1469466"
  }

We can send callbacks to your chosen endpoint when an order's stage changes or when a shipment is made (see Status for details of the Status and Shipments objects).

A callback requires a public url, which can be given globally as a setting in your merchant settings in the dashboard, or on a per-order basis by setting the callbackUrl in the Order object.

Each callback is in the form of a CloudEvent following the CloudEvents specification.

Properties

source URI-reference

The source identifies the context in which an event happened. This is a URI that points at the host environment that has produced the callback and the API endpoint that can be used to access the particular source object.

For example for sandbox this would be:

https://api.sandbox.prodigi.com/v4.0/Orders/

And the live api:

https://api.prodigi.com/v4.0/Orders/

View the CloudEvents spec ↗

id string

The identifier for the event. Each event ID is unique and starts with the evt_ prefix.

View the CloudEvents spec ↗

type string

The type property starts with the com.prodigi reverse DNS name. This is then followed by the high-level object that is responsible for generating the callback, which in most cases is the Order object followed by the path to the nested object that has changed. Finally, the new value is given as part of a fragment (followed by the # character).

For example:

com.prodigi.order.status.stage.changed#InProgress

This shows a change to the order stage: the change is to the order status and it has changed to InProgress.

View the CloudEvents spec ↗

Callback Payload 
 "data": {
      "id": "ord_1469466",
      "created": "2020-08-14T11:50:54.557Z",
      "status": {
        "stage": "InProgress"
      }
 }

subject string

Used to identify the particular object that produced the callback. In the case of the Prodigi API's callbacks this will be the order id.

dataContentType String

Always application/json.

time timestamp

The datetime the event was generated, in RFC3339 time format. Please note that this time may differ from the actual delivery time of the event because callbacks are queued for delivery.

View the CloudEvents spec ↗

specversion string

The version of the CloudEvents specification which the event uses. In our case this is version 1.0.

View the CloudEvents spec ↗

data json

Data object of the complete order object at the point the callback was created.

ID format

To aid parsing, all Prodigi-assigned IDs in the API have a 3-letter prefix according to the object type which it identfies.

Name Prefix Example in v3 Example in v4
Order ord_ 1234567 ord_1234567
OrderItem ori_ 1234567 ori_1234567
Charge chg_ 345345 chg_345345
ChargeItem chi_ 123123 chi_123123
Shipment shp_ 456456 shp_456456
Asset ast_ 12341234 ast_12341234

Outcomes

Outcome & object in a given response 
{
    "outcome": "Created",
    "order": {
        "id": "ord_840796",
        "created": "2021-03-11T14:31:23.41Z",
        "lastUpdated": "2021-03-11T14:31:23.4931606Z",
        "callbackUrl": null,
        "merchantReference": "MyMerchantReference1",
        "shippingMethod": "Overnight",
        "idempotencyKey": null,
        "status": {
            "stage": "InProgress",
            "issues": [],
            "details": {
                "downloadAssets": "NotStarted",
                "printReadyAssetsPrepared": "NotStarted",
                "allocateProductionLocation": "NotStarted",
                "inProduction": "NotStarted",
                "shipping": "NotStarted"
            }
        },
        "charges": [],
        "shipments": [],
        "recipient": {
            "name": "Mr test",
            "email": null,
            "phoneNumber": null,
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": null
            }
        },
        "items": [
            {
                "id": "ori_926886",
                "status": "NotYetDownloaded",
                "merchantReference": "item #1",
                "sku": "GLOBAL-CFPM-16X20",
                "copies": 1,
                "sizing": "fillPrintArea",
                "attributes": {
                    "color": "black"
                },
                "assets": [
                    {
                        "id": "ast_114059",
                        "printArea": "default",
                        "md5Hash": "daa1c811c6038e718a23f0d816914b7b",
                        "url": "https://pwintyimages.blob.core.windows.net/samples/stars/test-sample-grey.png",
                        "status": "InProgress"
                    }
                ],
                "recipientCost": {
                    "amount": "10.74",
                    "currency": "GBP"
                }
            }
        ],
        "packingSlip": null,
        "metadata": {
            "mycustomkey": "some-guid",
            "someCustomerPreference": {
                "preference1": "something",
                "preference2": "red"
            },
            "sourceId": 12345
        }
    },
    "traceParent": "00-65e25206c6b1e34dbdcea1a7051f85bd-f6885faf442b6041-00"
}

The outcome helps you understand what is happening with your order, and what has happened as a result of each request.

This is especially useful with larger orders, when a change across the whole order (like updating shipping, or cancelling the order) may have impacted your individual shipments.

This field is available on every request.

General outcomes

The range of returned outcome values varies between endpoints, but the general list of possible outcomes is as follows

Outcome Status code Description
validationFailed 400 We were unable to validate your request. This could be down to incorrect Order ID format, incorrect JSON (fields or malformed) in the body, or missing data.
entityNotFound 404 The endpoint was correct but the API could not find the given entity.
endpointDoesNotExist 404 The API does not recognise the endpoint.
methodNotAllowed 405 Request used an HTTP Method that the endpoint does not support.
invalidContentType 415 The Content-Type header is missing or indicates an unsupported content type. We only accept application/json.
internalServerError 500 An unexpected error occurred while processing your request. These are never intentional, so please let us know.
timedOut 500 We failed to process the request in under a minute and aborted the request.

Status

Each order object provided by the API has an associated Status object that provides a rich description of the order's fulfilment process and its current stage.

Status object

Status object 
{
    "stage":"InProgress",
    "details" : {
        "downloadAssets":"InProgress",
        "printReadyAssetsPrepared":"NotStarted",
        "allocateProductionLocation ": "NotStarted",
        "inProduction":"NotStarted",
        "shipping":"NotStarted"
    },
    "issues":[
        {
            "objectId": "ori_12345",
            "errorCode" : "items.assets.NotDownloaded",
            "description" : "Warning: Download attempt 1 of 10 failed for 'default' asset on item 'ori_12345' at location 'http://source.url' "
        },
        {
            "objectId": "ord_829398",
            "errorCode": "RequiresPaymentAuthorisation",
            "description": "Payment authorisation required for 'ord_829398' (195.02USD) please use the following URL to make payment: https://beta-dashboard.pwinty.com/payment/97323",
            "authorisationDetails": {
                "authorisationUrl": "https://beta-dashboard.pwinty.com/payment/97323",
                "paymentDetails": {
                    "amount": "195.02",
                    "currency": "USD"
                }
            }
        }
    ]
}

Top level

Value Type Description
stage string Current stage the order.
details Details The process involved in order production, and the state of each.
issues Issues Any order issues.

Stage

The stage description can be one of the following values:

  • InProgress The order has been submitted and is now in fulfilment.
  • Complete All of the orders shipments have been sent.
  • Cancelled The order production has been cancelled.

Please note: an order that has been submitted but is currently paused will not return a status until the pause window has expired and the order is submitted to fulfilment.

Details

The Details object lists the stages the order goes through during processing, and the status of the order within each of these stages.

Value Type Description
downloadAssets string Download of the image assets from your source URLs to Prodigi.
allocateProductionLocation string Allocation of the order items to the most appropriate lab(s).
printReadyAssetsPrepared string Transformation of an asset into a print-ready file for submission to the lab(s).
inProduction string Submission to the lab(s).
shipping string Despatch of the item to the customer

Each of these details stages has one of the following values:

  • NotStarted None of the items have been processed for this stage.
  • InProgress The process has started. One or more items have been processed but there are some outstanding items.
  • Complete All of the items have completed this stage of the process.
  • Error There has been an issue with one or more items. Issues will be present within the Issues collection.

Further details of the production process can be found in the Process section.

Issues

The issues array contains the details of any order issues.

Value Type Description
objectId string The object that is in error. This could refer to the order itself (an ID prefixed with ord_) or one of the order items (prefixed with ori_).
errorCode string A code that indicates the type the error:
  • order.items.assets.NotDownloaded
    An asset has failed a download attempt. We attempt to download an asset 10 times. The name of the failed asset is in the error description text.
  • order.items.assets.FailedToDownloaded
    An asset failed all 10 download attempts. The name of the failed asset is in the error description text.
  • order.items.ItemUnavailable
    A SKU has been marked as currently unavailable. This may be due to a lack of stock and is usually temporary. Customer services will need to be contacted regarding this issue.
description string A human-readable description of the error.
authorisationDetails AuthorisationDetails If an order requires payment authorization details are provided here.

Authorisation Details

Value Type Description
authorisationUrl string The url where authorisation of the payment can be carried out.
paymentDetails Cost The amount and currency of the required payment.

Errors

Base error object

All errors returned from authenticated requests will have the same basic structure.

Error Response 
{
    "statusText": "Something went wrong",
    "statusCode": 400,
    "data": {
    },
    "traceParent": "00-2c42dcf1952d634ab2d5d1ab49e8bdf9-c20ae99b6e950049-00"
}
Parameter Type Description
statusText string Human-readable description of the error.
statusCode integer HTTP status code.
data object JSON object containing additional details about the error where applicable. The structure will depend on the cause of the error.
traceParent string Unique identifier for the request.

TraceParent

Every request is assigned a unique identifier which can be used to aid support queries. This identifier is returned as the response header traceParent in every request, and is also included in base Error object for convenience.

Generic errors

Error code Meaning
400 Bad request: the request is malformed in some manner.
401 Unauthorised: your credentials are missing or incorrect.
404 Not found: the resource does not exist (or does not exist in your account).
500 Internal server error: Please contact support.

The order process

Understanding how we process and fulfill orders will help you understand our API.

Our order process consists of the following steps:

  1. Order creation
  2. Assets download
  3. Lab allocation
  4. Asset preparation
  5. Lab submission
  6. Production
  7. Shipping
  8. Order completion

During the order's lifecycle, we can send you callbacks with information on how the order is progressing. We can send callbacks when the following events occur:

  • After the "Create order" stage
  • After the "Shipments made" stage
  • After the "Order completed" stage

1. Order creation

The order is created by POSTing to the /orders endpoint. Once any pre-configured pause window has expired, it moves into fulfilment.

  • Order stage: In progress
  • Callback available: no
Task Stage
Download assets Not started
Print-ready assets prepared Not started
Allocate production location Not started
In production Not started
Shipping Not started

2. Assets download

We download your assets from your source URIs. We ensure that they are available for processing, and are available should the order need to be resubmitted or checked for quality.

For details of how long we keep the original and transformed images see image retention below.

  • Order stage: In progress
  • Callback available: yes, once complete
Task Stage
Download assets In progress
Allocate production location Not started
Print-ready assets prepared Not started
In production Not started
Shipping Not started

3. Lab allocation

When allocating your order, we allocate to the most cost-effective lab based on the chosen products, destination and shipping method. This may require us to split the order into multiple shipments.

Once this process has been completed, the order that is returned by the API shows the allocated shipments for the order items.

  • Order stage: In progress
  • Callback available: no
Task Stage
Download assets Complete
Allocate production location In progress
Print-ready assets prepared Not started
In production Not started
Shipping Not started

4. Asset preparation

We prepare each image asset file according to the requirements of the ordered product/lab (e.g. format or orientation).

  • Order stage: In progress
  • Callback available: no
Task Stage
Download assets Complete
Allocate production location Completed
Print-ready assets prepared In progress
In production Not started
Shipping Not started

5. Lab submission

Each shipment is sent to their respective lab.

  • Order stage: In progress
  • Callback available: no
Task Stage
Download assets Complete
Allocate production location Completed
Print-ready assets prepared Complete
In production In progress
Shipping Not started

6. Production

Each lab prints the items that they have been allocated.

  • Order stage: In progress
  • Callback available: no
Task Stage
Download assets Completed
Print-ready assets prepared Completed
Allocate production location Completed
In production In progress
Shipping Not started

7. Shipping

Once the items are produced, each lab notifies us and provides details of the shipment, including the specific shipping method used and the shipping reference where available.

  • Order stage: In progress
  • Callback available: yes, once complete
Task Stage
Download assets Completed
Print-ready assets prepared Completed
Allocate production location Completed
In production In progress
Shipping In progress

8. Order completion

When all items have received a shipping notification the whole order is marked as complete.

  • Order stage: Complete
  • Callback available: Yes
Task Stage
Download assets Complete
Print-ready assets prepared Complete
Allocate production location Complete
In production Complete
Shipping Complete

Image retention

When an order is submitted, we immediately save copies of the order's image assets. We retain these for 30 days, after which they are deleted automatically.

This 30-day period is in case we need to resubmit your order at any point, for example to a different lab.

Help & support

Contact

Our API team is always on hand for any support queries — please contact us at support@prodigi.com.

Guides

Versions

The current version of the API is v4.

Earlier versions

All earlier versions of the API have been discontinued and are no longer available. For guidance on upgrading to v4 please see the Migration Guide.

Changes & breaking changes

We consider a breaking change to be one where we need to remove fields or values. We will not roll out any breaking changes in a given version, instead favouring a minor version increase. We may release additional fields or endpoints without a version bump as we don't consider these breaking changes.