Skip to main content

Migrating from v3 to v4 of the Prodigi print API

Migrating from v3 to v4 of the Prodigi print API
18 March 2021

Version 4 represents the largest update of our print API to date, and adds new functionality and improved data consistency.

As a major version release, v4 does include many breaking changes over v3. Many objects have been re-engineered from the ground-up and we advise any merchants who are currently using v3 to familiarise themselves with our v4 documentation before starting any existing integration upgrades.

This new version includes:

  • New authentication header
  • Multi-asset support
  • Simplified order process
  • Improved payload consistency
  • ID formats

Authentication

Authentication is simpler in v4 and requires only a single HTTP header on each request.

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

Old (v3)

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"

New (v4)

curl "https://api.prodigi.com/v4.0/Orders"
  -X GET
  -H "X-API-Key: some-other-guid"

Multi-asset support

One of the key new features of v4 is Asset support. We now support products that require multiple images, broadening our product range and helping to make the ordering of existing products more intuitive.

Images are now specified in an assets array on the Item object.

Old (v3)

POST payload 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"
    }
}

New (v4)

Asset payload equivalent, within a POST to /v4.0/Orders:

{
    // rest of the payload goes here
    "items": [
    {
        "sku": "GLOBAL-FAP-16X24",
        "sizing": "fillPrintArea",
        "copies": 1,
        "attributes": {
            "color": "black"
        },
        "assets": [
            {
                "printArea": "default",
                "md5Hash": "abc",
                "url": "https://www.prodigi.com/sample-media/ProdigiTestImage.png"
            }
        ]
    }],
}

The asset print area 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.

All of our existing products support the use of the default asset print area (or front for apparel) and are orderable through v4.

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.

On hold status

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.

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.

ID formatting

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.

Old (v3)

GET /v3.0/Orders/123456

New (v4)

GET /v4.0/Orders/ord_123456

The list of IDs with their new prefixes in v4 is as follows:

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

In summary

We're really excited about this version, and we can't wait to see what new applications and businesses you create. Some of the v4 enhancements have been on our wishlist for a while (and we know they've been on some of yours!) and we're pleased to be able to share them.

For more advice in upgrading from a previous version, please contact us, or read about some of the new features of our print API.

Whether you are just starting out or looking to upgrade your print API, check out our v4 API documentation and API guides, or please contact us for more assistance.

Further reading