Save Products

In short

• A product is a name, one SKU and one print file per size. POST /api-create-product saves it with up to 22 sizes in one call; PUT /api-update-product adds sizes, replaces a file or renames it; GET /api-get-product reads it; DELETE /api-delete-product removes it.
• The same file is used whether the order is a print, a framed print or a fine art print. The order decides; you never save three products for one design.
• One file fits every size of its shape family, so one A-series file can be the image_url for A5 through A0 in a single call. A file of the wrong shape for a size is refused.
• Files are JPEG or PNG on a public HTTPS link, up to 50 MB. We copy them once; when GET /api-get-product shows every image_url on our storage, the original can be taken down.
• Saving, updating, reading and deleting products costs nothing and uses no credits.

Before you start

• An API key (see Get Access) and a SKU scheme (see SKUs).
• The list of sizes the design will sell, so you save a file for each of them. Which sizes are offered to which country comes from GET /api-get-pricing.
• One print-ready file per shape family on a public HTTPS link, kept online until we have copied it.
• Decide who creates the product. Listing a draft from the Listing Hub creates the product itself, and POST /api-bulk-list refuses a SKU that already belongs to a product; so for designs you will list through the Listing Hub, let the listing create the product and add any missing sizes afterwards, and use POST /api-create-product for designs sold elsewhere.

Which file fits which size

Every size needs artwork of its own shape, checked to within 2%. Portrait or landscape doesn’t matter. Export one file per family at 300 dpi and reuse it for every size in that family.

We don’t block low-resolution files: a small file is enlarged to the print size, so check quality before saving. Files over 50 MB hold more data than printing can use; re-export at a lower resolution or as a JPEG, which doesn’t reduce print quality. Our top sellers keep print files under 10 MB.

File rules

• Public HTTPS link to a JPEG or PNG, max 50 MB. PDF is accepted for order artwork sent by URL, not for product files.
• No WebP. We check the file’s actual contents, so renaming the extension doesn’t help; convert to PNG or JPEG.
• Transparent PNGs are kept as they are and transparent areas print as plain white paper. Other images may be re-saved as a high-quality JPEG when that makes them smaller.
• Files are converted to sRGB when resized, so RGB artwork gives the most predictable colours and CMYK colours may shift. Colours can differ slightly from a screen in any case.
• A wrong-shape file is refused when you save a product and on API orders. Imported orders with wrong-shape artwork still print, enlarged to fill the sheet with the overhang trimmed.
• The link must stay reachable until we have copied the file, usually within minutes. A file that fails to download is an error on the call, not a silent gap.

Create a product

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-a.jpg" },
      { "size": "A3", "image_url": "https://example.com/sunset-a.jpg" },
      { "size": "A2", "image_url": "https://example.com/sunset-a.jpg" },
      { "size": "50x70cm", "image_url": "https://example.com/sunset-a.jpg" }
    ]
  }'

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. Use 30x40cm and 50x70cm here; 12x16 and 20x28 are accepted only as aliases on orders.

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": "https://..." },
      { "id": "8c2e19a0-...", "sku": "MSP-001-A3", "size": "A3", "type": "Print", "image_url": "https://...", "thumbnail_url": null }
    ]
  },
  "warning": "Product created, but one or more thumbnails could not be generated yet."
}

• Every size gets the SKU {sku}-{size}. variants is missing when none were sent.
• warning appears only while the artwork is still being copied; copying finishes in the background and image_url may still be your URL until then.
• This response uses id; the read, update and delete calls use product_id and variant_id for the same values.

Errors: 400 Missing required field: name or sku · 400 SKU must be 50 characters or less. · 400 Too many variants. Maximum 22 variants per request. · 400 variants[1]: Invalid size "a4". Accepted values: ... · 400 variants[0]: Duplicate size "A4". ... · 400 variants[0]: Invalid image_url: <reason> · 400 when the account has reached 25,000 products · 409 SKU "MSP-001" already exists · 409 SKU "X" belongs to a bundle. .... A 409 on a retry means the first attempt worked; read the product back instead of creating it again.

Add sizes, replace a file or rename

curl -s -X PUT "https://api.printshrimp.com/functions/v1/api-update-product" \
  -H "x-api-key: $PS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "sku": "MSP-001",
    "variants": [
      { "size": "A4", "image_url": "https://example.com/sunset-a-v2.jpg" },
      { "size": "24x36", "image_url": "https://example.com/sunset-2to3.jpg" }
    ]
  }'

Response 200:

{
  "success": true,
  "sku_updated": false,
  "updated_variants": 1,
  "created_variants": 1,
  "product": {
    "product_id": "f0f17d46-...",
    "name": "Mountain Sunset Print",
    "sku": "MSP-001",
    "thumbnail_url": "https://...",
    "created_at": "2026-10-19T09:41:10.512+00:00",
    "updated_at": "2026-10-19T11:02:44.020+00:00",
    "variants": [
      { "variant_id": "232171d7-...", "sku": "MSP-001-A4", "size": "A4", "type": "Print", "image_url": "https://...", "thumbnail_url": "https://...", "created_at": "...", "updated_at": "..." },
      { "variant_id": "5d0e8b11-...", "sku": "MSP-001-24x36", "size": "24x36", "type": "Print", "image_url": "https://...", "thumbnail_url": null, "created_at": "...", "updated_at": null }
    ]
  }
}

• variants in the response lists every size the product has, not only the ones you sent. It may carry warning while copying finishes.
• Replacing a size’s file affects orders placed from then on; orders already placed keep their own copy of the artwork.
• Adding a size fills any orders waiting for that SKU and size automatically.
• Renaming with new_sku renames the size SKUs too, and every listing still carrying the old SKU stops matching until it is updated.

Read products

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

With sku, one product: { "success": true, "product": { "product_id", "name", "sku", "thumbnail_url", "created_at", "variants": [ { "variant_id", "sku", "size", "type", "image_url", "thumbnail_url", "created_at" } ] } }. Without sku, a list: { "success": true, "products": [ ...same shape... ], "page": 1, "total_products": 142 }, 25 per page with page from 1. A 404 means no product has that SKU.

When every variant’s image_url starts with https://api.printshrimp.com/storage/, we hold our own copy of each file and the originals can be deleted. Until then, keep them online.

Delete a product or a size

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

# one size
curl -s -X DELETE "https://api.printshrimp.com/functions/v1/api-delete-product?sku=MSP-001&size=A4" \
  -H "x-api-key: $PS_API_KEY"

Selectors: sku or product_id for the whole product; sku plus size, or variant_sku, or variant_id for one size. They are also accepted as a JSON body, and POST works as an alias for clients that can’t send a DELETE body. The response is { "success": true, "deleted": { "product_id", "sku", "name", "variants": [...] } }; deleting one size adds "remaining_variants" and lists only that size under deleted.variants.

• Deleting can’t be undone. The files are removed after 30 days. Orders already placed keep their own copy of the artwork.
• Future orders for a deleted SKU show “No product found”, and a bundle that contains the product can’t be ordered until it is rebuilt.
• Errors: 400 for no selector or a size that isn’t on that product; 404 not found; 409 when the product is in use by other records.

A clean way to do it

1. Decide the sizes the design will sell, and which families they fall in.
2. Export one file per family at 300 dpi and put each on a public HTTPS link.
3. Create the product with every size it sells, pointing each size at the file for its family. Up to 22 sizes per call; use PUT /api-update-product for any beyond that.
4. Read it back and compare variants[].size with the sizes on sale.
5. Put the SKU on the listing or in your catalogue, and only then start selling it.
6. Once GET /api-get-product shows every image_url on our storage, take the originals down if you want to.

Rules and limits

• Rate limits per account per rolling hour: 1,000 creates; 500 updates and 500 deletes; 2,000 reads. Calls that fail with 400 still count.
• 22 sizes per call; 200-character names; 50-character SKUs; 25,000 products per account.
• POST /api-create-product is not idempotent: a repeat with the same SKU is a 409, which is safe, so on a timeout read the product back before creating again.
• Products made in the app (My Print Files, Bulk Upload, Bulk Add Sizes) and products made by listing from the Listing Hub are the same products, readable and editable through the API.
• Sellers keep all rights in their artwork and must own or be licensed to use everything they upload; we may refuse or remove content we believe is unlawful or infringing (see Rules).

What this page doesn’t cover

• Designing SKUs and how orders match them: SKUs.
• Grouping products into sets: Bundles.
• Making listings that create products for you: List Artwork.
• Ordering a saved product: Sell Prints Anywhere.

Next

Previous: SKUs · Next: Bundles · Back to the hub: PrintShrimp for AI agents

Last updated 19 October 2026.