Our RESTful API is built using standard HTTP response codes, authentication and verbs. We accept application/json payloads, and return JSON on every response.
While using the v4 API in its alpha state, you may experience some strange or outright broken behaviour. As such, please do not treat the v4 API as production ready (i.e do not send us real orders), and expect the API and documentation to change as we progress through to a Live release.
Changes and Breaking Changes
We will continue to iterate on the Alpha and Beta releases of the API while you're using them, as such we may introduce some changes that would break your current v4 implementation. While we strive to only add new fields, we may have to modify existing ones and cause a breaking change. We may release breaking changes while in Alpha and Beta, but once v4 is live proper, we will ensure that any breaking changes come with a minor version increase.
First, create an account. This will give you access to both our sandbox and live environments.
Your API Key can then be found in your dashboard at Settings > Integrations > API. Click "Show API Key" to reveal your X-API-Key.
This key gives complete access to your API account so keep it private!
2. Pick a product
You can find a full list of our products on our site, by browsing the dashboard, by downloading our product catalogue, or, if you know roughly what you want and are just browsing for variants of a particular product, by using our lookup endpoints.
For this example order, let's use one of our more popular SKUs, a Global 16x24" fine art print: GLOBAL-FAP-16x24.
3. Source an image
The GLOBAL-FAP-16x24 is 16x24 inches in size, and requires an equally large image asset to accompany it. Most of our products have a recommended DPI (dots per inch) of 300, so a 16x24" print requires a 4800x7200px file for the best print quality: 16" x 300px = 4800px; 24" x 300px = 7200px.
We accept jpg and png format images. For some products we may recommend one format over the other (e.g. apparel and device cases work best with png).
You need to include a full URL path to this image asset as part of creating the order, at either a public or a private signed URL.
Now that you have chosen a product and sourced an image, you can create the order by POSTing the data to /v4.0/orders/. The data should be in our Order object format.
The code example uses uses our Sandbox environment, so the item will not be printed nor shipped, and you will not be charged. If you were to submit to Live (api.prodigi.com/), then it is at this point that the order is sent to our print labs for fulfillment.
Orders
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_677258","created":"2020-08-03T17:00:31.897Z","status":{"stage":"Complete","issues":[],"details":{"downloadAssets":"Complete","printReadyAssetsPrepared":"Complete","allocateProductionLocation":"Complete","inProduction":"Complete","shipping":"Complete"}},"charges":[{"id":"chg_364615","totalCost":{"amount":"40.6842","currency":"GBP"},"prodigiInvoiceNumber":null,"items":[{"id":"chi_545153","cost":{"amount":"11.5144","currency":"GBP"},"description":"Shipping","itemSku":null,"shipmentId":"shp_553327","itemId":null,"merchantItemReference":null},{"id":"chi_545154","cost":{"amount":"29.1698","currency":"GBP"},"description":"GLOBAL-CFPM-16X20-BLA-US1","itemSku":"GLOBAL-CFPM-16X20-BLA-US1","shipmentId":null,"itemId":"ori_689902","merchantItemReference":null}]}],"shipments":[{"id":"shp_553327","carrier":{"name":null,"service":null},"tracking":{"number":null,"url":null},"dispatchDate":"2020-08-03T17:19:28.157Z","items":["ori_689902"]}],"callbackUrl":null,"merchantReference":"test order 49","shippingMethod":"Budget","recipient":{"name":"Mr test","address":{"line1":"14 test place","line2":"test","postalOrZipCode":"12345","countryCode":"US","townOrCity":"somewhere","stateOrCounty":null},"email":"matthew.kay@prodigi.com","phoneNumber":"07700 900000"},"items":[{"id":"ori_689902","status":"Ok","merchantReference":null,"sku":"GLOBAL-CFPM-16X20","copies":1,"sizing":"Crop","attributes":{"color":"black"},"assets":[{"id":"ast_12342","status":"Complete","name":"default","md5Hash":"daa1c811c6038e718a23f0d816914b7b","url":"https://domain.com/assets/sample-asset.png"}],"recipientCost":null}],"packingSlip":{"url":null,"status":"None"},"metadata":{"customStringKey":"customValue","customNumberKey":123,"customBooleanKey":false}}
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.
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
name
string
yes
Name of the asset. 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.
{"id":"ord_123456","created":"2020-12-03T13:26:31.897Z","status":{"stage":"Submitted","issues":[],"details":{"downloadAssets":"InProgress","printReadyAssetsPrepared":"InProgress","allocateProductionLocation":"InProgress","inProduction":"InProgress","shipping":"InProgress"}},"charges":[{"id":"chg_155678","totalCost":{"amount":"42.0000","currency":"GBP"},"prodigiInvoiceNumber":null,"items":[{"id":"chi_68892","cost":{"amount":"11.0000","currency":"GBP"},"description":"Shipping","itemSku":null,"shipmentId":"shp_69332","itemId":null,"merchantItemReference":null},{"id":"chi_68893","cost":{"amount":"31.0000","currency":"GBP"},"description":"GLOBAL-CFPM-16X20-BLA-US1","itemSku":"GLOBAL-CFPM-16X20-BLA-US1","shipmentId":null,"itemId":"ori_689762","merchantItemReference":null}]}],"shipments":[],"callbackUrl":null,"merchantReference":"myOrderRef1","shippingMethod":"Budget","recipient":{"name":"John Testman","address":{"line1":"14 test place","line2":"test","postalOrZipCode":"12345","countryCode":"US","townOrCity":"somewhere","stateOrCounty":null},"email":"jtestman@prodigi.com","mobilePhoneNumber":"07700 900000"},"items":[{"id":"ori_689905","status":"Ok","merchantReference":null,"sku":"GLOBAL-CFPM-16X20","copies":1,"sizing":"Crop","attributes":{"color":"black"},"assets":[{"id":"ast_52342","status":"Complete","name":"default","md5Hash":"daa1c811c6038e718a23f0d816914b7b","url":"https://prodigi.com/assets/sample-asset.png"}],"recipientCost":null}],"packingSlip":{"url":null,"status":"None"},"metadata":null}
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.
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
{"id":"ord_677258","created":"2020-08-03T17:00:31.897Z","status":{"stage":"Complete","issues":[],"details":{"downloadAssets":"Complete","printReadyAssetsPrepared":"Complete","allocateProductionLocation":"Complete","inProduction":"Complete","shipping":"Complete"}},"charges":[{"id":"chg_364615","totalCost":{"amount":"40.6842","currency":"GBP"},"prodigiInvoiceNumber":null,"items":[{"id":"chi_545153","cost":{"amount":"11.5144","currency":"GBP"},"description":"Shipping","itemSku":null,"shipmentId":"shp_553327","itemId":null,"merchantItemReference":null},{"id":"chi_545154","cost":{"amount":"29.1698","currency":"GBP"},"description":"GLOBAL-CFPM-16X20-BLA-US1","itemSku":"GLOBAL-CFPM-16X20-BLA-US1","shipmentId":null,"itemId":"ori_689902","merchantItemReference":null}]}],"shipments":[{"id":"shp_553327","carrier":{"name":null,"service":null},"tracking":{"number":null,"url":null},"dispatchDate":"2020-08-03T17:19:28.157Z","items":["ori_689902"]}],"callbackUrl":null,"merchantReference":"test order 49","shippingMethod":"Budget","recipient":{"name":"Mr test","address":{"line1":"14 test place","line2":"test","postalOrZipCode":"12345","countryCode":"US","townOrCity":"somewhere","stateOrCounty":null},"email":"matthew.kay@prodigi.com","mobilePhoneNumber":"07700 900000"},"items":[{"id":"ori_689902","status":"Ok","merchantReference":null,"sku":"GLOBAL-CFPM-16X20","copies":1,"sizing":"Crop","attributes":{"color":"black"},"assets":[{"id":"ast_12345","status":"Complete","name":"default","md5Hash":"daa1c811c6038e718a23f0d816914b7b","url":"https://prodigi.com/assets/sample-asset.png"}],"recipientCost":null}],"packingSlip":{"url":"https://prodigi.com/images/default-packing-slip.png","status":"Success"},"metadata":null}
This endpoint returns an Order for a given Prodigi order ID.
Update order
Name
Description
prodigi_order_id
Prodigi ID of the order to retrieve.
Response
HTTP status code
Description
200
Returns the Order with the given prodigi_order_id.
400
Failed to find the order, probably due to invalid or missing prodigi_order_id. The details of the error will be found in the statusText property of the Error object.
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 0–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.
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.
HTTP status code
Description
200
Returns the orders response detailed above.
400
An error occured preventing a successful response, probably due to invalid parameter names or values. The error details are found in the statusText property of the Error object.
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"
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
HTTP status code
Description
200
Returns the availability of each action for the specified order.
400
Failed to retrieve the available actions, probably due to invalid or missing prodigi_order_id. The error details are in the statusText property of the Error object.
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
{"id":"ord_677258","created":"2020-08-03T17:00:31.897Z","lastUpdated":"2020-08-03T17:15:42.995Z","status":{"stage":"Cancelled","issues":[],"details":{"downloadAssets":"NotStarted","printReadyAssetsPrepared":"NotStarted","allocateProductionLocation":"NotStarted","inProduction":"NotStarted","shipping":"NotStarted"}},"charges":[{"id":"chg_364615","totalCost":{"amount":"40.6842","currency":"GBP"},"prodigiInvoiceNumber":null,"items":[{"id":"chi_545153","cost":{"amount":"11.5144","currency":"GBP"},"description":"Shipping","itemSku":null,"shipmentId":"shp_553327","itemId":null,"merchantItemReference":null},{"id":"chi_545154","cost":{"amount":"29.1698","currency":"GBP"},"description":"GLOBAL-CFPM-16X20-BLA-US1","itemSku":"GLOBAL-CFPM-16X20-BLA-US1","shipmentId":null,"itemId":"ori_689902","merchantItemReference":null}]}],"shipments":[{"id":"shp_553327","fulfillmentLoaction":{"labCode":"prodigi_3","CountryCode":"GB"},"carrier":{"name":null,"service":null},"tracking":{"number":null,"url":null},"dispatchDate":"2020-08-03T17:19:28.157Z","items":["ori_689902"],"cancelled":true}],"callbackUrl":null,"merchantReference":"test order 49","shippingMethod":"Budget","recipient":{"name":"Mr test","address":{"line1":"14 test place","line2":"test","postalOrZipCode":"12345","countryCode":"US","townOrCity":"somewhere","stateOrCounty":null},"email":"matthew.kay@prodigi.com","mobilePhoneNumber":"07700 900000"},"items":[{"id":"ori_689902","status":"Ok","merchantReference":null,"sku":"GLOBAL-CFPM-16X20","copies":1,"sizing":"Crop","attributes":{"color":"black"},"assets":[{"id":"ast_12342","status":"Complete","name":"default","md5Hash":"daa1c811c6038e718a23f0d816914b7b","url":"https://prodigi.com/assets/sample-asset.png"}],"recipientCost":null}],"packingSlip":{"url":null,"status":"None"},"metadata":{"customStringKey":"customValue","customNumberKey":123,"customBooleanKey":false}}
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.
Response
HTTP status code
Description
200
Returns the cancelled order, detailing the order's status as well as individual shipping statuses.
400
Failed to cancel the order. This could be due to number of reasons including: an invalid order id, or the order is at a status where it can no longer be cancelled (e.g. complete). The error details are in the statusText property of the Error object.
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" }'
{"id":"ord_677258","created":"2020-08-03T17:00:31.897Z","status":{"stage":"Complete","issues":[],"details":{"downloadAssets":"Complete","printReadyAssetsPrepared":"Complete","allocateProductionLocation":"Complete","inProduction":"Complete","shipping":"Complete"}},"charges":[{"id":"chg_364615","totalCost":{"amount":"40.6842","currency":"GBP"},"prodigiInvoiceNumber":null,"items":[{"id":"chi_545153","cost":{"amount":"11.5144","currency":"GBP"},"description":"Shipping","itemSku":null,"shipmentId":"shp_553327","itemId":null,"merchantItemReference":null},{"id":"chi_545154","cost":{"amount":"29.1698","currency":"GBP"},"description":"GLOBAL-CFPM-16X20-BLA-US1","itemSku":"GLOBAL-CFPM-16X20-BLA-US1","shipmentId":null,"itemId":"ori_689902","merchantItemReference":null}]}],"shipments":[{"id":"shp_553327","carrier":{"name":null,"service":null},"tracking":{"number":null,"url":null},"dispatchDate":"2020-08-03T17:19:28.157Z","items":["ori_689902"]}],"callbackUrl":null,"merchantReference":"test order 49","shippingMethod":"Budget","recipient":{"name":"Mr test","address":{"line1":"14 test place","line2":"test","postalOrZipCode":"12345","countryCode":"US","townOrCity":"somewhere","stateOrCounty":null},"email":"matthew.kay@prodigi.com","mobilePhoneNumber":"07700 900000"},"items":[{"id":"ori_689902","status":"Ok","merchantReference":null,"sku":"GLOBAL-CFPM-16X20","copies":1,"sizing":"Crop","attributes":{"color":"black"},"assets":[{"id":"ast_12345","status":"Complete","name":"default","md5Hash":"daa1c811c6038e718a23f0d816914b7b","url":"https://prodigi.com/assets/sample-asset.png"}],"recipientCost":null}],"packingSlip":{"url":"https://prodigi.com/images/default-packing-slip.png","status":"Success"},"metadata":{"internalRef":"abdef","templateSize":1,"feedback":{"message":"some message","stars":5}}}
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.
Failed to update the metadata, for example if you use an invalid prodigi_order_id.
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' "}]}
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:
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.
items.assets.FailedToDownloaded An asset failed all 10 download attempts. The name of the failed asset is in the error description text.
description
string
A human-readable description of the error.
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":{"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":"Crop","attributes":{},"assets":[{"id":"ast_116447","status":"InProgress","name":"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.
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.
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).
One of the key new features of v4 is Asset support. We now allow you to order products that require multiple images, broadening our product range going forward and helping to make the ordering of existing products more intuitive.
Images are now specified in an assets array on the Item object.
The asset name for all single-asset products is default, unless specified otherwise in our lookup endpoints. All v2 and v3 customers are in effect using a default asset and url for existing products.
Additionally, v4 removes the concept of Order objects as "baskets" that can be modified before submission. This removes many edge-case errors and helps simplify the process for all involved. What you submit on creation is what you get.
Order updates
API v4 retains the ability to modify the shipping method, recipient address and cancel an order, but since orders are now submitted immediately on creation, the timeframe to do this is smaller. Because of this, we have introduced new Actions endpoints in v4 to show the possible Actions that can be currently run against the order.
Due to the removal of the submission stage, On-hold has been removed as an option in v4. Internal testing has shown that the window to set an order to on-hold is impractically small.
Authentication
v3 authentication headers
curl "https://api.prodigi.com/v3.0/Orders"-X GET
-H"X-Pwinty-Merchant-Id: some-guid"-H"X-Pwinty-REST-API-Key: some-other-guid"
v4 authentication header
curl "https://api.prodigi.com/v4.0/Orders"-X GET
-H"X-API-Key: some-other-guid"
Authentication is simpler in v4 and requires only a single HTTP header on each request. API v4 now uses X-API-Key header instead of X-Pwinty-MerchantId and X-Pwinty-REST-API-Key. Your existing X-Pwinty-REST-API-Key value can slot into X-API-Key and the X-Pwinty-MerchantId can be discarded.
Payloads
Each v4 request will return data in a consistent way. For example, an Order being returned from GET Order By ID will be similar to the Order payload returned after creating an Order via POST.
We've also grouped up data into more logical, nested objects. For example, an Order contains a new Recipient object which contains the recipients name, email and address object.
Callbacks
We need to update your account settings to support v4 callbacks. Please email us support@prodigi.com to initiate this upgrade.
IDs
Example use of v3 order ID in URL
GET /v3.0/Orders/123456
Equivalent in v4
GET /v4.0/Orders/ord_123456
API v4 returns more information in each request than v3, which in turn means more IDs. To aid parsing these IDs, each ID has a 3-letter prefix according to the object type which it identfies. These new IDs are used throughout v4, including in the requests and responses for every endpoint.