How to place your first API order

18 October 2026

Interested in joining the world's leading print on demand platform?

Placing an order through Prodigi API v5 involves four steps:

Get an API key
Choose a product
Source an image
Place your order

Let’s walk through each step using a 16” × 24” fine art print as an example.

1. Get an API key

First, create a Prodigi account. This gives you access to our live and sandbox environments.

You can find your live API key in the Prodigi dashboard under Settings > Integrations > API. Click Show API Key to reveal it.

Your API key provides access to your account, so make sure you keep it private.

For testing, we strongly recommend using our sandbox environment rather than placing live orders.

Sandbox and live have separate API keys. To use them with v5, add the appropriate prefix:

Sandbox: Prefix your sandbox API key with sandbox_ for testing.
Live: Prefix your live API key with live_ for real orders.

For example, a live request would use X-API-Key: live_<your-key>.

Both environments use the same v5 API base URL (https://api.prodigi.com/v5), so you don’t need to change endpoints when switching between them.

Requests made without a key prefix will return a 401 error.

For your first order, use your sandbox key with the sandbox_ prefix. You can find more information in our API environments documentation.

2. Choose a product

You can browse products on our website, find them in the Prodigi dashboard, download our product catalogue or use the v5 catalogue endpoints to explore available products and variants.

For this example, we’ll use one of our popular SKUs: a global 16” × 24” fine art print (GLOBAL-FAP-16x24).

We can retrieve information about this product by sending a GET request to /v5/catalogue/variants/GLOBAL-FAP-16x24:

{
  "data": {
    "id": "GLOBAL-FAP-16x24",
    "sku": "GLOBAL-FAP-16x24",
    "name": "EMA, Enhanced Matte Art Paper, 200gsm, 40x60cm / 16x24\"",
    "attributes": {},
    "dimensions": {
      "width": { "mm": 406.4, "cm": 40.64, "in": 16 },
      "height": { "mm": 609.6, "cm": 60.96, "in": 24 }
    },
    "sizeLabel": {
      "metric": "40x60cm",
      "imperial": "16x24\""
    },
    "printAreas": [
      {
        "name": "default",
        "required": true,
        "widthMm": 406.4,
        "heightMm": 609.6,
        "recommendedDpi": 300
      }
    ],
    "shipsTo": ["Worldwide"]
  }
}

This response tells us the product’s dimensions, print area and recommended image resolution, giving us the information we need to prepare our artwork.

3. Source an image

Our chosen print measures 16” × 24”, so we’ll need an image that matches its dimensions and aspect ratio.

Most Prodigi products have a recommended resolution of 300 DPI (dots per inch). For a 16” × 24” print, that means an image measuring 4,800 × 7,200 pixels for optimal print quality:

16” × 300 DPI = 4,800 pixels
24” × 300 DPI = 7,200 pixels

We accept JPEG and PNG images, although some products work better with a particular format. For example, PNG is generally recommended for apparel and phone cases.

There are two ways to supply your artwork through v5:

Use an image URL: Provide the full URL of your image, either publicly accessible or through a private signed URL.
Upload your artwork to Prodigi: Use POST /v5/assets to upload a file directly (up to 100MB), or POST /v5/assets:ingest to import it from a URL. You can then reference the uploaded artwork in your order using its assetId.

When you submit artwork, we’ll download and retain a copy for 30 days to support order processing and fulfilment. After that, the file is automatically removed from our system.

For more information, see our API order process guide, including image requirements and file retention.

4. Place your order

Now that we’ve chosen a product and prepared our image, we’re ready to create an order.

To do this, send a POST request to /v5/orders with your order details in the required JSON format.

v5 lets you create orders as drafts, so you can make changes before submitting them for fulfilment. For this example, we’ll include submit: true to create and submit the order in a single request.

Here’s what the request looks like:

curl --request POST "https://api.prodigi.com/v5/orders" \
  --header "X-API-Key: sandbox_your-sandbox-api-key" \
  --header "Content-Type: application/json" \
  --data '
    {
        "submit": true,
        "shippingMethod": "budget",
        "recipient": {
            "name": "John Testman",
            "email": "jtestman@prodigi.com",
            "address": {
                "line1": "14 test place",
                "line2": "test",
                "postalOrZipCode": "12345",
                "countryCode": "US",
                "townOrCity": "somewhere",
                "stateOrCounty": "somewhereelse"
            }
        },
        "items": [
            {
                "sku": "GLOBAL-FAP-16x24",
                "quantity": 1,
                "sizing": "fillPrintArea",
                "assets": [
                    {
                        "printArea": "default",
                        "url": "https://your-image-url/image.png"
                    }
                ]
            }
        ]
    }'

What happens next?

When you submit the request, v5 returns a 202 Accepted response containing your order details within data, initially with a status of pending_submission.

If everything is successful, the order progresses to in_production. If there’s a problem, you can check the order’s status and issues to understand what needs attention.

For example, an order might move to on_hold with a payment_required issue, or return to draft with a fulfilment_issue.

You can check your order’s progress at any time using GET /v5/orders/{id}.

Testing versus live orders

Because our example uses a sandbox API key, the order won’t be printed or shipped, and you won’t be charged.

When you’re ready to place real orders, use your live API key with the live_ prefix. Prodigi will then process your orders and route them to a suitable print facility for production and fulfilment.