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
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
{
"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:
| Status | Meaning |
|---|---|
pending | Received, not yet moving. |
production_requested | Queued for production, waiting to be sent. |
sent_to_production | Handed to the production system. |
in_production | Being printed and packed. |
fulfilled | Shipped. trackingInfo and fulfilledAt are set. |
status usually matches fulfillmentStatus but also represents interruptions:
| Status | Meaning |
|---|---|
on_hold | Paused in the app. fulfillmentStatus still holds the stage it was at. |
cancellation_requested | A cancellation is waiting on a decision. |
canceled | Canceled. canceledAt is set and processing stops. |
paymentStatus tracks what your store owes Pengine. It does not represent your customer's payment:
| Status | Meaning |
|---|---|
due | Invoiced, not yet paid. |
paid | Settled. |
failed | A payment attempt failed. |
refunded | Refunded to you. |
canceled | The 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:
- Production starts according to your store's settings: automatically after a delay, or when you approve it in the app.
- The order climbs the ladder to
in_production, thenfulfilledwhen the carrier takes it. trackingInfoappears 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
| 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, limit | Standard 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
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
| Status | Code | When it happens |
|---|---|---|
400 | validation_failed | The request body is invalid, including missing fields, an invalid address, or an invalid line-item shape. |
400 | line_item_product_variant_not_found | A product variant ID or SKU is not in this store. |
400 | line_item_catalog_product_variant_not_found | A custom item names a catalog product variant that is unavailable to this store. |
400 | line_item_sku_mismatch | A variant ID and SKU were both sent, but they identify different variants. |
400 | line_item_duplicate | The same product variant appears in more than one line item. |
400 | line_item_product_not_orderable | A product is draft or archived. |
400 | line_item_variant_unavailable | A product or catalog product variant is discontinued or out of stock. |
400 | line_item_artwork_not_found | A custom item names an artwork that does not belong to this store. |
400 | line_item_decoration_method_unsupported | The catalog product does not support the requested decoration method. |
400 | line_item_decoration_location_unsupported | The catalog product does not have the requested decoration location. |
400 | line_item_decoration_method_unsupported_for_location | The decoration location does not support the requested method. |
400 | line_item_design_exceeds_decoration_area | The design is wider or taller than the decoration area. |
400 | line_item_design_outside_decoration_area | The design offsets place part of it outside the decoration area. |
400 | shipping_destination_unsupported | The shipping address is outside the configured shipping zones or areas. |
409 | external_order_id_duplicate | An 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
| Status | Code | When it happens |
|---|---|---|
404 | order_not_found | The order does not exist or belongs to another store. |