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.
Creating an order is a single API request, supplying all of the relevant information. Once the order is in our system, 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. Read more about our IDs.
created
string
n/a
The UTC DateTime the order was created. Set by Prodigi.
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.
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.
Item
Parameter
Type
Required
Description
id
string
n/a
Unique ID for this order item. Set by Prodigi.
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.
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.
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.
url
string
yes
URL of the asset.
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.
{"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 created, it begins the process of fulfillment, so the window for making any updates to the Order is small. See the Order actions section on more information about updating existing orders.
Create order outcomes
In addition to the General outcomes, this endpoint can also return:
Outcome
Status code
Description
created
200
Order created.
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/order/{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.
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.
There are 4 actions you can take against an order:
Cancel
Update shipping method
Update recipient details
Update metadata
Depending on where the order is during the fulfillment process, one or more of these actions may be unavailable.
You can find out which actions are currently valid for an 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.
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.
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.
{"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}},//restoftheorder},"traceParent":"00-e3466ad67db82340aa97a337e5c9ea91-edb742f49fc22c46-00"}
{"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:
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.
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.
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
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.
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.
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.
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.
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"}}}]}
The stage description can be one of the following values:
InProgress The order has been submitted and is now in progress.
Complete All of the orders shipments have been sent.
Cancelled The order production has been cancelled.
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.
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).
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.
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.
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.