Start

Quickstart

Your first calls. Three reads that cost nothing, one product save, then why create-order is real.

Max Murray Updated on Oct 18, 2026

In short

Three calls are free, read-only and safe to repeat: GET /api-get-pricing, GET /api-get-templates and GET /api-get-product. Start with them.
Saving a product with POST /api-create-product costs nothing and uses no credits. It is the first write to make, because every order and listing hangs off a product SKU.
POST /api-create-order creates a real order. There is no sandbox. With auto-pay on it is paid from the seller’s wallet, printed and shipped, and once in production it cannot be cancelled or changed.
Always send external_order_number, check SKUs with GET /api-get-product before ordering, and make the first real order a print to the seller’s own address.
Every call is JSON over HTTPS to https://api.printshrimp.com/functions/v1 with the key in x-api-key. Errors always come back as { "error": "..." }.

Before you start

An API key in your secret store (see Get Access). The examples read it from $PS_API_KEY. Keys look like psk_live_ followed by 32 characters.
Know whether Settings → Order Automation → Auto-pay from wallet is on for this account. It decides whether step 4 ends in a pending order or a printed one.
One artwork file on a public HTTPS URL: JPEG or PNG, under 50 MB, in A-series shape (A4 at 300 dpi is 2480 × 3508 pixels).

Every request below uses the same base URL and header. POST and PUT bodies are JSON with Content-Type: application/json.

Base URL:  https://api.printshrimp.com/functions/v1
Header:    x-api-key: $PS_API_KEY      (or Authorization: Bearer $PS_API_KEY)

Step 1: check the key and read prices

The pricing call proves the key works and returns what an order would be charged for one delivery country. Prices are set per country and kept current on our side, so fetch them from this call rather than copying them into your code.

curl -s "https://api.printshrimp.com/functions/v1/api-get-pricing?country=GB" \
  -H "x-api-key: $PS_API_KEY"

country is required: a 2-letter ISO code (GB, not UK) or a full country name. The response has this shape. Values in angle brackets are placeholders; real numbers only ever come from the live call.

{
  "success": true,
  "country": "United Kingdom",
  "currency": "GBP",
  "sizes": [
    {
      "size": "A3",
      "label": "A3",
      "print":    { "price": <number>, "shipping": <number>, "vat_rate": 0.2, "vat_amount": <number>, "net_price": <number> },
      "frame":    { ... same fields ... },
      "fine_art": { ... same fields ... }
    },
    {
      "size": "30x40cm",
      "label": "12x16\" (30x40cm)",
      "print":    { ... },
      "frame":    null,
      "fine_art": null
    }
  ]
}

print is a print on our Premium paper, frame a framed print, fine_art a print on our Fine Art cotton rag paper.
Prices are always in GBP, whatever the country. Converting to the seller’s selling currency is your job.
null means that product isn’t offered in that size to that country. Sizes not offered at all are left out.
Use size, not label, when you order.
shipping is charged once per order, on the first item, not per print.
For the UK, price includes VAT and vat_amount is the part of it that is VAT, never an extra on top. Every other country has vat_rate 0.
A country with no prices of its own gets Rest of World prices.

A 200 means the key works. A 401 means it is missing, wrong or revoked (see Get Access). A 400 means country was missing or unknown, and a 404 means we have no pricing for that country.

Step 2: read the seller’s listing templates

Templates live in the Listing Hub and are made by the seller; you can only read them. You need one to create listing drafts (see List Artwork), and this call tells you which artwork shapes the seller is set up for.

curl -s "https://api.printshrimp.com/functions/v1/api-get-templates" \
  -H "x-api-key: $PS_API_KEY"

{
  "success": true,
  "default_template_id": "3f6c1e2a-...",
  "templates": [
    {
      "template_id": "3f6c1e2a-...",
      "name": "Botanical",
      "ratio": "A",
      "ratio_label": "A-series",
      "mode": "easy",
      "sizes": ["A4", "A3", "A2"],
      "mockups": { "scenes": 6, "photos": 2 },
      "print_files": true,
      "is_default": true,
      "created_at": "2026-08-02T09:41:10.512+00:00",
      "updated_at": "2026-09-20T16:03:44.031+00:00"
    }
  ]
}

ratio is A, 2:3, 3:4 or 4:5. A draft’s artwork must match its template’s ratio within 2%.
print_files: false is a mockup-only template; drafts made with it never become PrintShrimp products.
More than 6 scenes means each draft costs 2 credits instead of 1.
An empty templates list means the seller hasn’t made one yet. Ask them to create one in Bulk List → Templates; you can’t.

Step 3: save one product

A product is a name, one SKU and one print file per size. The SKU is what every order and listing later points at (see SKUs). This call copies the artwork from your link to our storage; it charges nothing and uses no credits.

curl -s -X POST "https://api.printshrimp.com/functions/v1/api-create-product" \
  -H "x-api-key: $PS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Mountain Sunset Print",
    "sku": "MSP-001",
    "variants": [
      { "size": "A4", "image_url": "https://example.com/sunset-a4.jpg" }
    ]
  }'

Field	Required	Rules
`name`	yes	max 200 characters
`sku`	yes	letters, numbers, `-` and `_`; max 50; unique on the account and not a bundle SKU
`variants`	no	max 22 per call; add more later with `PUT /api-update-product`
`variants[].size`	yes	one of the sizes below, case-sensitive (`A4`, not `a4`); each size once per call
`variants[].image_url`	yes	HTTPS, JPEG or PNG, max 50 MB; the file’s shape must fit the size within 2%
`variants[].type`	no	leave it out: the order decides print, frame or fine art

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

Response 201:

{
  "success": true,
  "product": {
    "id": "f0f17d46-...",
    "name": "Mountain Sunset Print",
    "sku": "MSP-001",
    "type": "poster",
    "created_at": "2026-10-19T09:41:10.512+00:00",
    "variants": [
      { "id": "232171d7-...", "sku": "MSP-001-A4", "size": "A4", "type": "Print", "image_url": "https://...", "thumbnail_url": null }
    ]
  },
  "warning": "Product created, but one or more thumbnails could not be generated yet."
}

Each size gets its own SKU, always {sku}-{size}: here MSP-001-A4.
warning only appears while the artwork is still being copied. That finishes in the background, and image_url may still be your URL until then.
This response says id; GET /api-get-product calls the same values product_id and variant_id.

Errors are 400 for a missing name or sku, a SKU over 50 characters, more than 22 variants, an invalid or duplicated size, an image_url that fails the checks (the message says why), or an account at its 25,000-product limit; and 409 if the SKU already exists or belongs to a bundle. A 409 on a retry means the first attempt worked.

Now read it back:

curl -s "https://api.printshrimp.com/functions/v1/api-get-product?sku=MSP-001" \
  -H "x-api-key: $PS_API_KEY"

{
  "success": true,
  "product": {
    "product_id": "f0f17d46-...",
    "name": "Mountain Sunset Print",
    "sku": "MSP-001",
    "thumbnail_url": "https://...",
    "created_at": "2026-10-19T09:41:10.512+00:00",
    "variants": [
      {
        "variant_id": "232171d7-...",
        "sku": "MSP-001-A4",
        "size": "A4",
        "type": "Print",
        "image_url": "https://api.printshrimp.com/storage/v1/object/public/...",
        "thumbnail_url": "https://...",
        "created_at": "2026-10-19T09:41:10.512+00:00"
      }
    ]
  }
}

Once every variant’s image_url is on our storage (api.printshrimp.com/storage/...), we hold our own copy and the original link can be taken down. Without sku the call lists products 25 per page, with page from 1. To remove the test product, DELETE /api-delete-product?sku=MSP-001 deletes it; that can’t be undone, though orders already placed keep their own copy of the artwork. Everything about products is on Save Products.

Step 4: why create-order is real

There is no test mode and no sandbox key. POST /api-create-order creates a real order on the seller’s account every time. It arrives with status Pending and nothing is charged until it is paid, but what happens next depends on one setting:

Auto-pay from wallet off: the order waits unpaid in Create Orders until the seller pays it by hand. The seller can delete it there, and nothing is charged.
Auto-pay from wallet on: once the order is Ready and has waited the seller’s delay, it is paid from the wallet (if the wallet covers the batch), goes into production, and is printed and shipped. Once in production it cannot be cancelled or changed.

So before the first order: confirm which case you are in, check every SKU exists with GET /api-get-product, always send an external_order_number, and send the first real order to the seller’s own address. It is ordered and paid like any other order and gives them a print to check.

The smallest valid order is one A4 print of the product from step 3, to a UK address. Running this creates a real 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": "TEST-0001",
    "customerInfo": {
      "name": "Jane Example",
      "address1": "1 Example Street",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB",
      "shipping": "standard"
    },
    "products": [
      { "sku": "MSP-001", "size": "A4", "paper_type": "Matte" }
    ]
  }'

Response 201; status is always Pending at this point:

{
  "success": true,
  "order": {
    "order_id": "f0f17d46-...",
    "external_order_number": "TEST-0001",
    "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" }
    ],
    "vat_rate": 0.2,
    "vat_amount": <number>
  }
}

external_order_number (max 100 characters) is your only protection against duplicates. A second order with the same value is refused with 400 An order with external_order_number "TEST-0001" already exists., so after a timeout or a lost response, resend with the same number: either it goes through, or it tells you it already has and you look it up.
An unknown SKU still creates the order, and the response looks normal except that title is null. That item can’t be paid until the seller adds artwork, which is why you check SKUs first.
total_price includes shipping and, for the UK, VAT; vat_amount is inside it, not on top.
Prints need paper_type (Matte, Satin or Gloss); frames need "type": "Frame" and a variant (Black, White or Oak); fine art is "type": "FineArt". Every field and rule is on Sell Prints Anywhere.

Then follow it. There are no webhooks, so you poll:

curl -s "https://api.printshrimp.com/functions/v1/api-get-order?external_order_number=TEST-0001" \
  -H "x-api-key: $PS_API_KEY"

A pending order comes back with paid: false, the tracking and vat_* fields null, and each item carrying fulfillable (true or false) and a reason_code such as SKU_NOT_FOUND. Once paid, status moves through Paid, In Production and Shipped, and tracking and tracking_courier appear when it ships. Poll every 30 to 60 minutes, not more often. What each status means is on Orders.

Rules and limits

Limits are per account and per endpoint over a rolling hour, shared by all the account’s keys: 2,000 for get-pricing, get-product, get-templates and get-order; 1,000 for create-product; and 1,000 new orders per 24 hours. A call that fails with 400 still counts.
Over a limit you get 429 { "error": "Rate limit exceeded" } with no Retry-After header. Wait at least a minute, then back off further.
401 is Missing or invalid API key (no key, or the wrong prefix) or Invalid API key (unknown or revoked). 405 is the wrong HTTP method. 500 is our error, and a read is safe to retry.
Steps 1 to 3 are free and leave the seller’s wallet untouched. Step 4 is the only call on this page that can cost money.