NAV Navbar icon
API v4: alpha release

Introduction

Welcome to the Prodigi API documentation for v4.

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

Sign up for your free API key ↗

Current version

The current version of the API is v4.

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.

Earlier version documentation

If you are using an earlier version, please refer to the v2 and v3 API documentation. For guidance on upgrading to v4, please see the Migration Guide.

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

Getting started

The process of putting an order into our API is as follows:

  1. Acquire an API key
  2. Pick a product
  3. Source an image
  4. Place an order

1. Acquire an API key

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.

4. Place an order

POST /v4.0/orders 
curl "https://api.sandbox.prodigi.com/v4.0/Orders"
  -X POST
  -H "X-API-Key: your-rest-api-key"
  -H "Content-Type: application/json"
  -d '
    {
        "shippingMethod": "Budget",
        "recipient": {
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
            },
            "name": "John Testman",
            "email": "jtestman@prodigi.com"
        },
        "items": [
            {
                "sku": "GLOBAL-FAP-16x24",
                "copies": 1,
                "assets": [
                    {
                        "name": "default",
                        "url": "https://your-image-url/image.png"
                    }
                ]
            }
        ]
    }
  '

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.
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.
callbackUrl string no Your callback URL, where we send callback events.
merchantReference string no Your own reference ID for this order.
idempotencyKey string no Your personal idempotency key.
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.
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
address Address yes Recipient's address
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

Parameter Type Required Description
line1 string yes First line of recipient's address.
line2 string yes 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 yes 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.
totalCost Cost n/a Total of all individual charges. Set by Prodigi.
prodigiInvoiceNumber string n/a Depending on your billing frequency, this will be your Prodigi Invoice Number or null. 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.
cost Cost n/a Cost breakdown for this item. Set by Prodigi.
description string n/a Type of charge. Typically, it's either a SKU or "Shipping". Set by Prodigi.
itemSku string n/a The SKU for the charge, or null for shipping charge items. 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.
merchantItemReference string no Your originally supplied reference for this item, if one was supplied.

Shipment

Parameter Type Required Description
id string n/a Unique ID for this shipment. Set by Prodigi.
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 Items n/a The products in this shipment. Set by Prodigi.

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. Default is crop.
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
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.

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": "myOrderRef1"
        "shippingMethod": "Budget",
        "recipient": {
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
            },
            "name": "John Testman",
            "email": "jtestman@prodigi.com"
        },
        "items": [
            {
                "sku": "GLOBAL-CFPM-16X20-BLA-US1",
                "copies": 1,
                "assets": [
                    {
                        "name": "default",
                        "url": "https://your-image-url.prodigi.com/image.png"
                    }
                ]
            }
        ]
    }
  '
Response 
{
    "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.
orderIds array null Limit to a range Prodigi order IDs.
merchantReferences array null Limit to a range of your order references.

Response

Response 
{
    "orders": [{
        "id":"...",
    }],
    "hasMore": true,
    "nextUrl": "https://sandbox.api.prodigi.com/v4.0/Orders?Top=15&Skip=30"
}

Orders

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.
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"
Response 
{
    "cancel": {
        "isAvailable": "No"
    },
    "changeRecipientDetails": {
        "isAvailable": "No"
    },
    "changeShippingMethod": {
        "isAvailable": "No"
    },
    "changeMetadata": {
        "isAvailable": "Yes"
    }
}

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" }'
Response 
{
  "order": {
    ...
  },
  "updateResults" : [{
    "shipmentId" : "sp_1234",
    "successful" : true,
    "errorCode":"",
    "description":""
  }],
  "result" : "Completed"

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

Response codes

Http Status Code Description
200 Returns an UpdateShipmentMethodResponse object.
400 Failed to update the shipping method, this happens if you use an invalid prodigi_order_id.

Response object

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

ShipmentDetail object

Name Type Description
shipmentId string 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

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": "somewhere",
                      "stateOrCounty": null
                    }
      }'
Response 
{
  "order": {
    ...
  },
  "shipmentResult" : [{
    "shipmentId" : "sp_1234",
    "successful" : true,
    "errorCode":"",
    "description":""
  }],
  "result" : "Completed"

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
Address Address yes Recipient's address
Email string yes Recipient's email
PhoneNumber string yes Recipient's primary contact number

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

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

HTTP status code Description
200 Returns the amended Order object.
400 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' "
        }
    ]
}

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

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.

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.

  • 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).
500 Internal server error: Please contact support.

Migration guide (v3 to v4)

In this guide, we will outline the key differences between v3 and v4, and what is involved in upgrading your applications.

Multi-asset support

v3 image payload for POST to /v3.0/Orders/{orderId}/Images 
{
    "sku" : "GLOBAL-FAP-16X24",
    "url" : "https://www.prodigi.com/sample-media/ProdigiTestImage.png",
    "sizing" : "crop",
    "copies" : 1,
    "attributes": {
        "frameColour":"black"
    }
}
v4 Asset payload equivalent for POST to /v4.0/Orders 
{
    // rest of the payload goes here
    "items": [
    {
        "sku": "GLOBAL-FAP-16X24",
        "sizing": "crop",
        "copies": 1,
        "attributes": {
            "color": "black"
        },
        "assets": [
            {
                "name": "default",
                "md5Hash": "abc",
                "url": "https://www.prodigi.com/sample-media/ProdigiTestImage.png"
            }
        ]
    }],
}

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.

Order creation

In v3, order creation was a 3-step process:

  1. Create the order
  2. Add the products and imagery to the order
  3. Submit the order

API v4 unifies these 3 steps into 1, allowing you to create and submit an order in a single request.

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.

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