Pengine Store API
Endpoints

Artworks

How to upload your artwork and reuse it across orders.

An artwork is an image stored in your Pengine store for use on a custom item. Upload it once, then reference its ID across orders.

Provide an HTTPS URL for the image. Pengine downloads and stores its own copy.

Create an artwork

POST /store-api/2026-08/stores/:storeId/artworks
curl -X POST https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/artworks \
  -H "X-API-Key: $PENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northbound",
    "image": { "url": "https://cdn.example.com/art/northbound.png" }
  }'

Prop

Type

201 Created
{
  "id": "sm22mjuo3dk36g1ejurbawjx",
  "name": "Northbound",
  "image": {
    "id": "gskts87l21rh1g4lsrmqmcuz",
    "url": "https://cdn.pengine.io/files/gskts87l21rh1g4lsrmqmcuz/Northbound.png"
  },
  "createdAt": "2026-08-19T13:02:55.410Z",
  "updatedAt": "2026-08-19T13:02:55.410Z"
}

Store the returned id and send it as artworkId in a decoration.

Rules for the URL

Rule
SchemeHTTPS only.
CredentialsThe URL must not carry a username or password.
HostMust resolve to a public address. Private ranges and loopback are refused.
RedirectsNot followed. Point at the file itself.
FormatsPNG and JPEG.
SizeUp to 50 MB.
TimeoutThe download gives up after 30 seconds.

The URL must be available when you create the artwork. After Pengine stores its copy, the source URL can go offline.

See Create artwork errors for possible failures.

Creating an artwork is not idempotent

There is no equivalent of customStoreOrder.externalOrderId for artworks. Retrying after a timeout can create a second artwork with a different ID. Store the returned ID and check for it before re-uploading.

The artwork object

Prop

Type

List artworks

GET /store-api/2026-08/stores/:storeId/artworks
Parameter
sort[name]asc or desc.
sort[createdAt]asc or desc. Defaults to desc, and is always applied last as a tiebreak.
page, limitStandard paging. See Lists.

There are no filters on this endpoint.

curl "https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/artworks?sort[createdAt]=desc&limit=50" \
  -H "X-API-Key: $PENGINE_API_KEY"

Items are full artwork objects in the standard list envelope.

See List artwork errors for possible failures.

Get one artwork

GET /store-api/2026-08/stores/:storeId/artworks/:artworkId
curl https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/artworks/sm22mjuo3dk36g1ejurbawjx \
  -H "X-API-Key: $PENGINE_API_KEY"

See Get artwork errors for possible failures.

Working with artworks

Upload once, use many times. An artwork is not consumed by an order. Reuse the same ID across line items, orders and decoration locations.

Store the ID with your design record. Artwork names are not unique, so do not use them for reconciliation.

Artworks cannot be deleted through this API. Manage them in the Pengine app.

Errors

Authentication, rate-limit, validation, and server errors use the shared error format. See Errors.

Create artwork errors

StatusCodeWhen it happens
400validation_failedThe request body is invalid, including a missing image, an invalid name, or an image URL that is malformed or not HTTPS.
400url_invalidThe URL carries credentials, or its host cannot be resolved.
400url_not_allowedThe host resolves to a private or reserved address.
400artwork_image_download_failedThe download fails, times out, exceeds the size limit, or redirects.
415file_format_unsupportedThe downloaded file is not a PNG or JPEG.

List artwork errors

This endpoint has no artwork-specific errors. Invalid query parameters return validation_failed.

Get artwork errors

StatusCodeWhen it happens
404artwork_not_foundThe artwork does not exist or belongs to another store.

On this page