Jobs to automate

Sell Prints Anywhere

You sell somewhere we don't integrate with. One API order per sale, we print and ship.

Max Murray Updated on Oct 18, 2026

In short

When the seller’s shop isn’t on Etsy or Shopify (their own site, another marketplace, an app with a “print this” button), you send one POST /api-create-order per sale. We print it on demand and ship it white-label, with no branding, to the buyer.
Each item is one print, named either by a saved product sku or by an image.artwork_url, with a size, and for prints a paper_type. Up to 50 prints per order.
Always send external_order_number. It is the only protection against placing the same order twice, and it makes a retry safe.
The order arrives Pending and nothing is charged until it is paid, by the seller or by auto-pay from the wallet. Once in production it can’t be changed or cancelled.
There are no webhooks. Poll GET /api-get-order for status, then pass the tracking number and courier on to the buyer yourself; we don’t send it anywhere for API orders.

Before you start

An API key (see Get Access) and a quote for the delivery country from GET /api-get-pricing (see Pricing). The pricing response also tells you which sizes and products are offered to that country: a null there means the item can’t be ordered.
Either saved products for everything you sell (the reliable route; see Save Products) or a public HTTPS link to the artwork for each sale.
Know whether auto-pay from wallet is on. If it is, each order you create is paid, printed and shipped after the seller’s delay; if not, the seller pays each one in Create Orders.
A deliverable address from the buyer. The seller is responsible for the address and sizes supplied, and we are not responsible for mistakes in them.

The flow

A sale happens on the seller’s channel. You already quoted the price from GET /api-get-pricing and the seller set their own margin.
You send POST /api-create-order with the buyer’s address and the items. The order appears in the seller’s Create Orders as Pending.
It is paid: by auto-pay from the wallet once it is Ready and has waited the delay, or by the seller by hand. You can’t pay through the API.
Paid orders go into production at 7:30am, 12pm and 3pm UK time. Orders paid before 3pm on a working day start that day; later ones start the next working day.
When the order leaves production it gets a tracking number and its status becomes Shipped. You read it with GET /api-get-order and give it to the buyer.

Build the order

curl -s -X POST "https://api.printshrimp.com/functions/v1/api-create-order" \
  -H "x-api-key: $PS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "external_order_number": "SHOP-1001",
    "gift_message": "Happy birthday, Sam!",
    "customerInfo": {
      "name": "Jane Example",
      "address1": "1 Example Street",
      "address2": "Flat 2",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB",
      "email": "jane@example.com",
      "phone": "07700 900000",
      "shipping": "standard"
    },
    "products": [
      { "sku": "MSP-001", "size": "A4", "paper_type": "Matte" },
      { "sku": "MSP-001", "size": "A4", "paper_type": "Matte" },
      { "sku": "MSP-001", "size": "A3", "type": "Frame", "variant": "Oak" },
      { "sku": "MSP-002", "size": "A3", "type": "FineArt" },
      { "size": "16x20", "paper_type": "Gloss", "image": { "artwork_url": "https://example.com/art-16x20.jpg" } }
    ]
  }'

Top level:

Field	Required	Rules
`external_order_number`	no, but always send it	max 100; your own order reference; a second API order with the same value is refused with 400
`gift_message`	no	max 500 characters
`customerInfo`	yes	the delivery address, below
`products`	yes	1 to 50 prints after bundles are split; one entry is one print, so send a line twice for two copies

customerInfo:

Field	Required	Rules
`name`	yes	max 60
`address1`	yes	max 60
`address2`	no	max 60
`city`	yes	max 60, no digits
`state`	for US, CA and AU	max 60
`zip`	yes	max 20; UK postcodes contain letters and no hyphen; US ZIP codes are digits only
`country`	yes	2-letter ISO code: `GB`, not `UK`. `JE`, `GG` and `IM` are refused; send Jersey, Guernsey and Isle of Man addresses as `GB` with their local postcode
`email`	no	valid format, max 254
`phone`	no	max 30
`shipping`	no	`standard` (default), `tracking upgrade` or `priority`; the last two are UK only, and an order containing a frame or a fine art print always ships standard

Each entry in products:

Field	Required	Rules
`sku`	SKU mode	a saved product SKU or a bundle SKU
`image.artwork_url`	URL mode	HTTPS, JPEG, PNG or PDF, max 50 MB; the file’s shape must fit the size
`size`	yes	any product size, plus `12x16` (= `30x40cm`) and `20x28` (= `50x70cm`)
`type`	no	`Print` (default), `Frame` or `FineArt` (`Fine Art` also works)
`paper_type`	prints	`Matte`, `Satin` or `Gloss`; ignored for frames (always Matte) and fine art
`variant`	frames	`Black`, `White` or `Oak`

Sending both sku and image.artwork_url on one item, or neither, is a 400. The sizes are A5 A4 A3 A2 A1 A0 5x7 6x8 8x10 8.5x11 11x14 11x17 12x18 16x20 16x24 18x24 20x30 24x32 24x36 28x40 30x40 30x40cm 50x70cm 10x10 12x12 14x14 16x16 18x18 20x20, with 8.5x11 for US deliveries only.

SKU mode or URL mode

SKU mode is for products you saved beforehand. We look up exactly product-SKU-size for the size ordered: capitals must match the saved SKU, there is no fallback to another size’s file, and no AI check. A saved file of the wrong shape refuses the order. An unknown SKU does not fail the call: the order is still created, the item’s title comes back null, and it waits as Rejected with “No product found” until the seller adds artwork in the app. So check SKUs with GET /api-get-product before ordering, and after ordering confirm each item with GET /api-get-order, where an unmatched item shows "fulfillable": false and "reason_code": "SKU_NOT_FOUND".

A bundle SKU becomes one print per product in the bundle, each priced as a normal print and each using the type, paper_type and variant you sent; an item with a fixed size in the bundle uses that size instead. Capitals are ignored for bundle SKUs, and a bundle containing a deleted product refuses the order (see Bundles).

URL mode is for one-off artwork, such as an image a buyer just made. The link must be public HTTPS and stay reachable until we have copied the file, usually within minutes. The file’s shape must fit the size within about 2% or the order is refused: A-series and 5:7 artwork fits A0–A5, 5x7, 50x70cm and 28x40; 2:3 fits 11x17, 12x18, 16x24, 20x30 and 24x36; 3:4 fits 6x8, 30x40cm, 18x24, 24x32 and 30x40; 4:5 fits 8x10, 11x14 and 16x20; squares need square files and 8.5x11 needs a letter-shaped file. Only the first page of a PDF is printed, converted at 300 dpi, and a PDF order stays Paid until the conversion is done. Transparent areas print as plain white paper, files are converted to sRGB so CMYK colours may shift, and we don’t block low-resolution files, so check quality before you order.

Prints, frames and fine art

A print is on our Premium paper in the paper_type you choose: Matte (flat, no reflections), Satin (subtle sheen) or Gloss (reflective). All three cost the same.
A frame is "type": "Frame" with a variant of Black, White or Oak: pine, shatter-resistant plexiglass, delivered ready to hang. Framed prints are always matte. Frames come in every size except A0, 6x8, 28x40, 30x40 and the squares. The spec is at printshrimp.com/pages/framed-prints.
Fine art is "type": "FineArt": our 300gsm cotton rag paper, made for the UK, USA, Canada and the EU; paper_type is ignored. The paper is described at printshrimp.com/pages/fine-art-paper.
One order can mix all three, and the same saved product can be ordered as any of them. A mixed order follows the slowest item’s production time.

Shipping

standard is included in the price for the UK, USA, Canada, Australia and every EU country we price; Rest of World orders carry a shipping charge, returned as shipping_cost. Shipping is charged once per order, not per item.
tracking upgrade (UK only) makes small UK prints (A5, A4, 5x7, 6x8, 8x10) fully tracked with proof of delivery, for a small fee. On Standard those sizes go as a Royal Mail letter with no tracking updates until delivery, and we don’t reship or refund them if they arrive late. Orders that already ship tracked are never charged for it.
priority (UK only) is our only express option, a flat charge per order that replaces standard shipping, for orders made up of prints only.
Any order containing a frame or a fine art print ships standard whatever you send, and neither upgrade changes production time or the 3pm cut-off. Sending priority for a non-UK address is a 400.
We choose the courier for each order by destination and size; you can’t pick it.

Response

201, with the order always Pending. Values in angle brackets are placeholders.

{
  "success": true,
  "order": {
    "order_id": "f0f17d46-...",
    "external_order_number": "SHOP-1001",
    "status": "Pending",
    "shipping_type": "Standard",
    "total_price": <number>,
    "shipping_cost": <number>,
    "created_at": "2026-10-19T09:41:10.512+00:00",
    "items": [
      { "id": "a1...", "sku": "MSP-001", "size": "A4", "type": "Print", "variant": null, "paper_type": "Matte", "price": <number>, "title": "Mountain Sunset Print" },
      { "id": "b2...", "sku": "MSP-001", "size": "A3", "type": "Frame", "variant": "Oak", "paper_type": "Matte", "price": <number>, "title": "Mountain Sunset Print" },
      { "id": "c3...", "sku": null, "size": "16x20", "type": "Print", "variant": null, "paper_type": "Gloss", "price": <number>, "title": null }
    ],
    "vat_rate": 0.2,
    "vat_amount": <number>
  }
}

shipping_type is Standard, Tracking Upgrade or Priority.
total_price includes shipping and, for UK deliveries, VAT; vat_amount is inside it, never on top. Deliveries outside the UK carry no UK VAT, and local duties in the destination country are not included and not ours.
A URL-mode item has sku: null and title: null by design; a SKU-mode item with title: null means the SKU wasn’t found.

Errors

All 400 with { "error": "..." }, for example:

Invalid request format. Expected { customerInfo: {...}, products: [...] }
Missing customer information: zip. All of these are required: name, address1, city, zip, country
Country must be a 2-letter ISO code (e.g. "GB", "US", "AU"). Received: "UK"
State/province is required for United States. Please provide a "state" field.
Shipping option "priority" is only available for United Kingdom. Use "standard" for other countries.
Product[0]: Missing required field: paper_type. Accepted values: Matte, Satin, Gloss
Product[1]: Frame orders require a "variant" field. Accepted values: Black, White, Oak
Product[0]: Provide either "sku" (to reference a saved product) or "image.artwork_url" (to provide artwork directly), not both.
An order with external_order_number "SHOP-1001" already exists. This is the safe-retry case: treat it as already placed and look the order up.

Fix the field named and resend. A 400 still counts against the rate limit.

After you’ve placed it

Payment. Nothing is charged until the order is paid. Auto-pay pays Ready API orders from the wallet after the seller’s delay, up to 20 per run, only if the wallet covers the batch; otherwise the seller pays in Create Orders. An unpaid order waits there with no expiry and nothing charged, and the seller can delete it.
Discount. Every print in an order of 3 or more prints to one address is 20% off, automatically, for API orders too. Fine art counts separately (3 or more fine art prints), frames never count and are never discounted, and separate orders don’t combine. One order per sale is still right; just don’t split one sale into several orders.
Follow it. GET /api-get-order?external_order_number=SHOP-1001 returns the order whether paid or not. Poll every 30 to 60 minutes. A pending order has paid: false and per-item fulfillable and reason_code; once paid, status moves through Paid, In Production and Shipped, and tracking and tracking_courier appear when it ships. Shipped doesn’t mean delivered; only some orders move to a delivered state when the courier confirms.
Tell the buyer. API orders aren’t linked to any marketplace, so the tracking number goes nowhere unless you send it. We never email the seller’s buyers. Only the first tracking number is attached automatically; a replacement after a problem gets a new one, listed last.
Timing. Production and delivery days per region, and the “When will my order arrive?” checker, are on printshrimp.com/pages/pricing. Times are working-day estimates, not guarantees.

Changing or cancelling

There is no API call to edit or cancel an order. Before payment, the seller can change anything with Edit Order in Create Orders, or delete the order with nothing charged.
While a paid order still shows Paid, the seller can cancel it in Paid Orders and the full amount goes back to their wallet. A paid order can enter production at the very next send, even minutes after payment, so there is no guaranteed window.
Once in production, nothing can be changed, and an address change isn’t passed on. Shipped orders can’t be cancelled.
Lost or damaged orders are reported by the seller through Report a problem on the order, within 30 days of the estimated delivery date, with photos for damage. Not through the API, and not by you.

Rules and limits

1,000 new orders per account per 24 hours; 2,000 GET /api-get-order calls an hour. Over a limit you get 429 with no Retry-After: wait at least a minute and back off.
external_order_number is checked exactly, after trimming, against all your API orders, paid or unpaid; deleting an unpaid order frees its number.
Up to 50 prints per order; one line per print; up to 500 characters of gift message.
Accounts are for business use. The seller is the seller of record to their buyer and handles their own refunds, returns and customer service; we supply the seller and have no contract with their customers. Change-of-mind returns aren’t accepted, because everything is printed to order.
Rest of World framed orders ship with duties unpaid, so the buyer may be charged on delivery.