Pengine Store API
Endpoints

Orders

How to create orders and track their statuses and fulfillment.

Create an order after your customer pays. The order contains line items and one shipping address. Pengine prints and ships the items, then bills your store.

The Store API can create and read orders. Edit, cancel, or hold an order in the Pengine app.

Create an order

POST /store-api/2026-08/stores/:storeId/orders
curl -X POST https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/orders \
  -H "X-API-Key: $PENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customStoreOrder": {
      "externalOrderId": "web-10482",
      "orderedAt": "2026-08-19T12:31:00.000Z"
    },
    "lineItems": [
      { "productVariantId": "ak88bwfjjqn5cjt5jaczmn1n", "quantity": 2 },
      { "sku": "PGN15884420374096221552", "quantity": 1 }
    ],
    "shippingAddress": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phone": "+12025550176",
      "address": {
        "streetAddress": "1600 Pennsylvania Avenue NW",
        "apartmentOrSuite": "Suite 4",
        "cityOrTown": "Washington",
        "stateOrProvince": "DC",
        "zipOrPostalCode": "20500",
        "country": "US"
      }
    }
  }'

Prop

Type

Line item

A line item is either a product you built in advance, or a custom item assembled at order time.

Prop

Type

For a standard line item, send productVariantId or sku. If you send both, they must identify the same variant. A variant can appear in only one line item, so combine duplicate entries by increasing the quantity.

For a custom line item, set isCustom to true and send catalogProductVariantId and decorations. This creates the item at order time without saving a product. Custom and standard line items can appear on the same order.

See Custom items for the decoration fields, the placement rules and the failures they cause.

Shipping address

Prop

Type

Prop

Type

Custom store order

customStoreOrder holds the details of the order as your storefront knows it.

Prop

Type

201 Created
{
  "id": "p948dnb4qbo2d86i2mx67svp",
  "name": "#127505",
  "status": "pending",
  "fulfillmentStatus": "pending",
  "paymentStatus": "due",
  "isTest": false,
  "totalQuantity": 3,
  "subtotalCost": 392.1,
  "shippingCost": 17.85,
  "totalCost": 409.95,
  "customStoreOrder": {
    "externalOrderId": "web-10482",
    "orderedAt": "2026-08-19T12:31:00.000Z"
  },
  "lineItems": [
    {
      "id": "l0x557ng2f08ilidmdvl4cnq",
      "productId": "saryo4m9p6ki3u1558m6h56j",
      "productVariantId": "ak88bwfjjqn5cjt5jaczmn1n",
      "sku": "PGN70872789915240044115",
      "name": "Midweight Hoodie - Black",
      "color": "Black",
      "size": "S",
      "quantity": 2,
      "isCustom": false,
      "unitCost": 130.7,
      "totalCost": 261.4,
      "images": [
        {
          "id": "zkk2lkpxredez88sw0ljgwia",
          "color": "Black",
          "image": {
            "id": "kl1v18gmjnd420uziof6ecv0",
            "url": "https://cdn.pengine.io/files/kl1v18gmjnd420uziof6ecv0/Midweight-Hoodie-Front-Black.png"
          },
          "position": 1
        }
      ],
      "position": 1
    },
    {
      "id": "xgx8w0nrdtloiyol3fy8kdtv",
      "productId": "saryo4m9p6ki3u1558m6h56j",
      "productVariantId": "jluxmo6oeo4lh4xmd82pyazn",
      "sku": "PGN15884420374096221552",
      "name": "Midweight Hoodie - Black",
      "color": "Black",
      "size": "M",
      "quantity": 1,
      "isCustom": false,
      "unitCost": 130.7,
      "totalCost": 130.7,
      "images": [
        {
          "id": "qe3yif5nrilpk5qjcapjfoj6",
          "color": "Black",
          "image": {
            "id": "kl1v18gmjnd420uziof6ecv0",
            "url": "https://cdn.pengine.io/files/kl1v18gmjnd420uziof6ecv0/Midweight-Hoodie-Front-Black.png"
          },
          "position": 1
        }
      ],
      "position": 2
    }
  ],
  "shippingAddress": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "phone": "+12025550176",
    "address": {
      "streetAddress": "1600 Pennsylvania Avenue NW",
      "apartmentOrSuite": "Suite 4",
      "cityOrTown": "Washington",
      "stateOrProvince": "DC",
      "zipOrPostalCode": "20500",
      "country": "US"
    }
  },
  "createdAt": "2026-08-19T12:37:20.897Z",
  "updatedAt": "2026-08-19T12:37:20.932Z"
}

See Create order errors for possible failures.

The order object

Prop

Type

Order line item

Prop

Type

Each entry in images carries a color, a position, and a nested image object holding id and url.

customStoreOrder holds externalOrderId when you sent one, and orderedAt, which is always set: the date you sent, or the time Pengine received the order when you sent none.

Tracking info

Prop

Type

Costs are what Pengine charges you

unitCost, subtotalCost, shippingCost and totalCost are what Pengine charges you, in US dollars. What your customer paid is not in this API. Round to cents in your own code before displaying or storing a total.

Statuses

fulfillmentStatus tracks production progress and only moves forward:

StatusMeaning
pendingReceived, not yet moving.
production_requestedQueued for production, waiting to be sent.
sent_to_productionHanded to the production system.
in_productionBeing printed and packed.
fulfilledShipped. trackingInfo and fulfilledAt are set.

status usually matches fulfillmentStatus but also represents interruptions:

StatusMeaning
on_holdPaused in the app. fulfillmentStatus still holds the stage it was at.
cancellation_requestedA cancellation is waiting on a decision.
canceledCanceled. canceledAt is set and processing stops.

paymentStatus tracks what your store owes Pengine. It does not represent your customer's payment:

StatusMeaning
dueInvoiced, not yet paid.
paidSettled.
failedA payment attempt failed.
refundedRefunded to you.
canceledThe invoice was canceled, usually with the order.

Treat unknown values as 'something else'

New statuses can appear without a new API version. Handle known values and use a neutral fallback for unknown values. See Versioning.

What happens after you create one

An order starts as pending with payment due. Pengine then processes it according to your store settings:

  1. Production starts according to your store's settings: automatically after a delay, or when you approve it in the app.
  2. The order climbs the ladder to in_production, then fulfilled when the carrier takes it.
  3. trackingInfo appears on the order response, with a URL you can send to your customer.

The API does not control these transitions. Use the orders_update webhook to react to changes. See Events.

List orders

GET /store-api/2026-08/stores/:storeId/orders
Parameter
filter[status]One or more order statuses.
filter[fulfillmentStatus]One or more fulfillment statuses.
filter[paymentStatus]One or more payment statuses.
filter[externalOrderId]Exact match on your own order number.
sort[updatedAt]asc or desc.
sort[createdAt]asc or desc. Defaults to desc, and is always applied last as a tiebreak.
page, limitStandard paging. See Lists.
# Everything still in production
curl "https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/orders?filter[fulfillmentStatus]=sent_to_production,in_production&limit=100" \
  -H "X-API-Key: $PENGINE_API_KEY"

# Find the order you created as web-10482
curl "https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/orders?filter[externalOrderId]=web-10482" \
  -H "X-API-Key: $PENGINE_API_KEY"

# What changed since you last looked
curl "https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/orders?sort[updatedAt]=desc&limit=50" \
  -H "X-API-Key: $PENGINE_API_KEY"

Items are full order objects, the same shape POST and GET /orders/:orderId return.

See List order errors for possible failures.

Get one order

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

See Get order errors for possible failures.

Creating orders safely

Always send customStoreOrder.externalOrderId. It prevents retries from creating duplicate orders. After a timeout, retry with the same value: 201 means the first request did not succeed, and 409 means it did.

Check availability before checkout. A draft or archived product, or a discontinued variant, fails at order creation. Validate availability while the customer is browsing.

Validate placement before checkout. For custom items, the print area dimensions are what the order is checked against, so checking them yourself while the customer is still designing avoids a 400 at the end. See Custom items.

Store the ID. Save the Pengine id with your own order. Later API responses and webhook payloads refer to it.

Errors

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

Create order errors

StatusCodeWhen it happens
400validation_failedThe request body is invalid, including missing fields, an invalid address, or an invalid line-item shape.
400line_item_product_variant_not_foundA product variant ID or SKU is not in this store.
400line_item_catalog_product_variant_not_foundA custom item names a catalog product variant that is unavailable to this store.
400line_item_sku_mismatchA variant ID and SKU were both sent, but they identify different variants.
400line_item_duplicateThe same product variant appears in more than one line item.
400line_item_product_not_orderableA product is draft or archived.
400line_item_variant_unavailableA product or catalog product variant is discontinued or out of stock.
400line_item_artwork_not_foundA custom item names an artwork that does not belong to this store.
400line_item_decoration_method_unsupportedThe catalog product does not support the requested decoration method.
400line_item_decoration_location_unsupportedThe catalog product does not have the requested decoration location.
400line_item_decoration_method_unsupported_for_locationThe decoration location does not support the requested method.
400line_item_design_exceeds_decoration_areaThe design is wider or taller than the decoration area.
400line_item_design_outside_decoration_areaThe design offsets place part of it outside the decoration area.
400shipping_destination_unsupportedThe shipping address is outside the configured shipping zones or areas.
409external_order_id_duplicateAn order already exists with this external ID. Fetch the existing order instead.

Line-item failures include details with the zero-based index and relevant identifiers. Artwork failures include artworkId. Decoration failures include decorationMethod and, when relevant, decorationLocation.

See Custom items for the decoration fields and placement rules.

List order errors

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

Get order errors

StatusCodeWhen it happens
404order_not_foundThe order does not exist or belongs to another store.

On this page