Pengine Store API
Guides

Custom items

What a custom item is, and how to put one on an order.

There are two ways to put a line item on an order.

KindUse it when
Product line itemYou built the product in the Pengine app in advance. Name a variant by productVariantId or sku.
Custom line itemThe design is decided at order time. Name a blank, an artwork and where the artwork goes.

A custom item combines a catalog product variant (a blank in one color and size), an artwork (your image), and one or more decorations (where and how to print the artwork). It does not create a saved product, making it suitable for designs generated at order time.

The flow

Find a blank

Catalog products are the blanks available to your store. Each one reports the decoration methods it supports and the areas you can print on.

curl "https://api.pengine.io/store-api/2026-08/stores/$STORE_ID/catalog-products?filter[productType]=shirts&filter[decorationMethod]=direct_to_garment" \
  -H "X-API-Key: $PENGINE_API_KEY"

Use the variant id for the color and size you want. Also record the allowed decorationLocations. See Catalog products.

Upload the artwork

Provide an HTTPS URL that Pengine can use to download the image. The response contains an artwork you can reuse across orders.

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" } }'

Store the artwork id. Uploading the same image twice creates two separate artworks. See Artworks.

Create the order

Set isCustom to true, identify the blank with catalogProductVariantId, and define each placement in decorations.

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-10483" },
    "lineItems": [
      {
        "isCustom": true,
        "catalogProductVariantId": "zt1vz7szjeiv64qezrzakzc8",
        "quantity": 1,
        "decorations": [
          {
            "decorationLocation": "front",
            "decorationMethod": "direct_to_garment",
            "artworkId": "sm22mjuo3dk36g1ejurbawjx",
            "physicalWidth": 10,
            "physicalHeight": 12,
            "horizontalOffsetFromCenter": 0,
            "verticalOffsetFromTop": 2.5
          }
        ]
      }
    ],
    "shippingAddress": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "address": {
        "streetAddress": "1600 Pennsylvania Avenue NW",
        "cityOrTown": "Washington",
        "stateOrProvince": "DC",
        "zipOrPostalCode": "20500",
        "country": "US"
      }
    }
  }'

Custom and product line items can sit on the same order. The shipping address and customStoreOrder work exactly as they do anywhere else. See Orders.

The response uses the standard order shape. Custom line items have isCustom: true and omit productId because they are not based on a saved product.

The decoration object

Prop

Type

Placing the artwork

All four measurements are in inches, matching the print area the catalog product reports for that location. The artwork has to fit inside it:

  • physicalWidth and physicalHeight must each be no larger than the area's own dimensions.
  • verticalOffsetFromTop plus physicalHeight must not exceed the area's height.
  • Half of physicalWidth plus the absolute value of horizontalOffsetFromCenter must not exceed half the area's width.

Set horizontalOffsetFromCenter to 0 to center the artwork. The API does not preserve the source image's aspect ratio automatically, so set a proportional width and height.

Rules for a custom line item

  • isCustom: true requires catalogProductVariantId and at least one decoration.
  • A custom line item cannot carry productVariantId. A product line item cannot carry catalogProductVariantId or decorations.
  • Every decoration on a line item must use the same decorationMethod. To combine methods, split them into separate line items.
  • A location can appear only once per line item.
  • The method has to be supported by the blank, and also allowed at that specific location. Some locations exclude some methods.

Validate custom items before ordering

Validate the catalog variant, artwork, decoration method, location, and placement while your customer is designing. This prevents the order from being rejected at checkout.

The create-order response identifies the affected line item and decoration in error.details. See Create order errors for every status and error code.

Next

On this page