Skip to main content

PurchaseOrderDetail

The purchase order object returned by every create, update, and cancel operation. It includes the order's details along with its line items. Money fields (shipping_amount, tax_amount, subtotal, total, and each line item's unit_cost/line_total) are JSON numbers, not strings.

idinteger

Internal id; use uuid for API calls.

Example: 501
uuidstring
Example: 9a1e3b7c-1e3d-4a3f-9f2e-9c6b6e2a2b11
sequence_idintegernullable
Example: 1042
source_system_idinteger

For internal reference only, not usable in API calls.

Example: 7
supplier_idintegernullable
Example: 42
supplier_namestringnullable
Example: Acme Supply
namestringnullable
Example: null
statusstring

One of draft, ordered, partial, received, committed, cancelled (see the create/PATCH contract for which transitions an API key can make)

Example: draft
destination_location_idstringnullable
Example: gid://shopify/Location/73986408603
destination_location_namestringnullable
Example: Main Warehouse
payment_termsstringnullable
Example: null
estimated_arrivalstring<date>nullable
Example: null
order_placed_datestring<date>nullable
Example: null
order_shipped_datestring<date>nullable
Example: null
order_cancelled_datestring<date>nullable
Example: null
shipping_carrierstringnullable
Example: null
tracking_numberstringnullable
Example: null
reference_numberstringnullable
Example: null
supplier_order_referencestringnullable
Example: null
supplier_invoice_numberstringnullable
Example: null
notestringnullable
Example: null
tagsstring[]
Example: []
shipping_amountnumber
Example: 0
tax_amountnumber
Example: 4.5
subtotalnumber
Example: 45
totalnumber
Example: 49.5
metadataobject
Example: {}
sourcestring

Always partner_api for purchase orders created through this API.

Example: partner_api
currencystring
Example: USD
idempotency_keystringnullable

The caller's own Idempotency-Key header from create, echoed back. Only used when creating the purchase order; not returned when you fetch it back (PurchaseOrder).

Example: null
is_archivedboolean
Example: false
incoming_sync_statusstring
Example: pending_sync
incoming_sync_errorstringnullable
Example: null
incoming_sync_detailsobject
Example: {}
bill_statusstring
Example: unbilled
bills_countinteger
Example: 0
is_editableboolean

True only while status is draft.

Example: true
is_cancellableboolean
Example: true
is_revertibleboolean
Example: false
is_note_editableboolean
Example: false
is_cost_editableboolean
Example: false
is_deletableboolean
Example: false
catalog_sync_warningsobject[]

Present only when a Shopify catalog lookup for a line item's SKU failed. Warn-only — the purchase order is still saved.

Example: []
line_items object[]
  • Array [
    • idinteger
    Example: 1
    client_line_idstringnullable

    Caller-supplied idempotency key for this line, used to match a line on a later PATCH.

    Example: null
    skustringnullable
    Example: TSHIRT-BLK-M
    barcodestringnullable
    Example: null
    titlestringnullable
    Example: Widget
    image_urlstringnullable
    Example: null
    unit_costnumbernullable
    Example: 4.5
    line_totalnumbernullable
    Example: 45
    product_idstringnullable
    Example: gid://shopify/Product/1
    variant_idstringnullable
    Example: gid://shopify/ProductVariant/1
    location_idstringnullable
    Example: gid://shopify/Location/1
    location_namestringnullable
    Example: Main Warehouse
    tax_percentstringnullable

    A tax rate, not an amount, so unlike the money fields it is returned as a string rather than a number. Parse it before doing arithmetic with it.

    Example: 0.0
    supplier_skustringnullable
    Example: null
    notestringnullable
    Example: null
    variant_titlestringnullable
    Example: Default Title
    quantity_orderedinteger
    Example: 10
    inventory_item_idstringnullable
    Example: gid://shopify/InventoryItem/1
    positioninteger
    Example: 1
    added_during_receivingboolean
    Example: false
    variant_supplier_cost objectnullable

    The supplier's catalog cost for this line item's variant, when known. Null when no supplier catalog match exists.

    idinteger
    Example: 501
    inventory_item_idstringnullable
    Example: gid://shopify/InventoryItem/1
    product_variant_idintegernullable
    Example: 8801234567
    supplier_idintegernullable
    Example: 42
    supplier_skustringnullable
    Example: SUP-WIDGET-1
    supplier_pricenumbernullable
    Example: 4.5
    last_costnumbernullable
    Example: 4.5
    currencystringnullable
    Example: USD
    is_defaultboolean
    Example: true
    pack_sizeintegernullable
    Example: 1
    order_uomstringnullable
    Example: each
    case_costnumbernullable
    Example: 4.5
    base_uomstringnullable
    Example: each
    sold_bystringnullable
    Example: each
    created_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
    updated_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
  • ]
    • created_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
    updated_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
    PurchaseOrderDetail
    {
      "id": 501,
      "uuid": "9a1e3b7c-1e3d-4a3f-9f2e-9c6b6e2a2b11",
      "sequence_id": 1042,
      "source_system_id": 7,
      "supplier_id": 42,
      "supplier_name": "Acme Supply",
      "name": null,
      "status": "draft",
      "destination_location_id": "gid://shopify/Location/73986408603",
      "destination_location_name": "Main Warehouse",
      "payment_terms": null,
      "estimated_arrival": null,
      "order_placed_date": null,
      "order_shipped_date": null,
      "order_cancelled_date": null,
      "shipping_carrier": null,
      "tracking_number": null,
      "reference_number": null,
      "supplier_order_reference": null,
      "supplier_invoice_number": null,
      "note": null,
      "tags": [],
      "shipping_amount": 0,
      "tax_amount": 4.5,
      "subtotal": 45,
      "total": 49.5,
      "metadata": {},
      "source": "partner_api",
      "currency": "USD",
      "idempotency_key": null,
      "is_archived": false,
      "incoming_sync_status": "pending_sync",
      "incoming_sync_error": null,
      "incoming_sync_details": {},
      "bill_status": "unbilled",
      "bills_count": 0,
      "is_editable": true,
      "is_cancellable": true,
      "is_revertible": false,
      "is_note_editable": false,
      "is_cost_editable": false,
      "is_deletable": false,
      "catalog_sync_warnings": [],
      "line_items": [
        {
          "id": 1,
          "client_line_id": null,
          "sku": "TSHIRT-BLK-M",
          "barcode": null,
          "title": "Widget",
          "image_url": null,
          "unit_cost": 4.5,
          "line_total": 45,
          "product_id": "gid://shopify/Product/1",
          "variant_id": "gid://shopify/ProductVariant/1",
          "location_id": "gid://shopify/Location/1",
          "location_name": "Main Warehouse",
          "tax_percent": "0.0",
          "supplier_sku": null,
          "note": null,
          "variant_title": "Default Title",
          "quantity_ordered": 10,
          "inventory_item_id": "gid://shopify/InventoryItem/1",
          "position": 1,
          "added_during_receiving": false,
          "variant_supplier_cost": {
            "id": 501,
            "inventory_item_id": "gid://shopify/InventoryItem/1",
            "product_variant_id": 8801234567,
            "supplier_id": 42,
            "supplier_sku": "SUP-WIDGET-1",
            "supplier_price": 4.5,
            "last_cost": 4.5,
            "currency": "USD",
            "is_default": true,
            "pack_size": 1,
            "order_uom": "each",
            "case_cost": 4.5,
            "base_uom": "each",
            "sold_by": "each"
          },
          "created_at": "2026-06-01T12:00:00.000Z",
          "updated_at": "2026-06-01T12:00:00.000Z"
        }
      ],
      "created_at": "2026-06-01T12:00:00.000Z",
      "updated_at": "2026-06-01T12:00:00.000Z"
    }