Skip to main content

PurchaseOrderDetail

The purchase order returned by the create, update and cancel endpoints, with its line items. It is the response body itself, not wrapped in a purchase_order key as the read endpoints return it. Only is_editable and is_cancellable describe actions an API key can take; the other is_* flags describe what the merchant can do in the Bookkeep app.

uuidstring

The purchase order's unique identifier. Use it in the purchase order paths.

Example: 9a1e3b7c-1e3d-4a3f-9f2e-9c6b6e2a2b11
sequence_idintegernullable

The purchase order number the merchant sees in Bookkeep. Numbers are assigned per store, start at 1001 unless the merchant chose a different starting number, and can have gaps.

Example: 1042
supplier_namestringnullable

Name of the supplier the purchase order is placed with.

Example: Acme Supply
namestringnullable

An optional name the merchant gave the purchase order. Often null.

Example: null
statusstring

One of draft, ordered, partial, received, committed or cancelled, or, for stores that receive stock through Shopify transfers, in_transit, partially_transferred or transferred. See Purchase order statuses in the Inventory API overview for what each means. Purchase orders created through this API start as draft.

Example: draft
destination_location_idstringnullable

The Shopify location the stock is delivered to, as a Shopify location ID (gid://shopify/Location/<id>). You can look these IDs up with the Shopify Admin GraphQL API.

Example: gid://shopify/Location/73986408603
destination_location_namestringnullable

Name of the destination location, as it appears in Shopify. Bookkeep looks it up from destination_location_id. It is null if Bookkeep cannot find the name.

Example: Main Warehouse
payment_termsstringnullable

Payment terms agreed with the supplier. Typically one of prepaid, upon_receipt, net_7, net_15, net_30, net_45, net_60, net_90 or net_120, but it is free text, so older purchase orders can hold other values.

Example: null
estimated_arrivalstring<date>nullable

The date the merchant expects the stock to arrive.

Example: null
order_placed_datestring<date>nullable

The date the order was placed with the supplier.

Example: null
order_shipped_datestring<date>nullable

The date the supplier shipped the order.

Example: null
order_cancelled_datestring<date>nullable

The date the order was cancelled.

Example: null
shipping_carrierstringnullable

The carrier delivering the order.

Example: null
tracking_numberstringnullable

The carrier's tracking number.

Example: null
reference_numberstringnullable

A reference the merchant can add for their own tracking. It also appears on printed purchase orders.

Example: null
supplier_order_referencestringnullable

The supplier's own number for this order.

Example: null
supplier_invoice_numberstringnullable

The number on the supplier's invoice for this order.

Example: null
notestringnullable

A note on the purchase order.

Example: null
tagsstring[]

Tags the merchant uses to group purchase orders.

Example: []
shipping_amountnumber

Shipping cost for the order.

Example: 0
tax_amountnumber

Total tax on the order's lines: the sum of each line's unit_cost times quantity_ordered times its tax_percent / 100. Always calculated by Bookkeep from the lines; you cannot set it.

Example: 4.5
subtotalnumber

Sum of each line's unit_cost times quantity_ordered, before tax. Always calculated by Bookkeep from the lines; you cannot set it.

Example: 45
totalnumber

Order total. For a purchase order created through this API, or whose lines are changed through it, Bookkeep sets it to subtotal plus tax_amount. A purchase order saved in the Bookkeep app keeps the total the app saved, so it can differ from subtotal plus tax_amount.

Example: 49.5
metadataobject

Extra data saved with the purchase order. On create you can send any JSON object here.

Example: {}
sourcestring

Where the purchase order was created, for example bookkeep for the Bookkeep app or partner_api for this API.

Example: partner_api
currencystring

ISO 4217 currency code for all amounts on the purchase order.

Example: USD
is_archivedboolean

Whether the merchant archived the purchase order in Bookkeep.

Example: false
incoming_sync_statusstring

Progress of updating incoming stock in Shopify for this purchase order: pending_sync, syncing, synced or sync_failed. A new draft shows pending_sync; Shopify is only updated once the purchase order leaves draft.

Example: pending_sync
incoming_sync_errorstringnullable

Why the last incoming stock update failed or skipped items, for example a line whose item no longer exists in Shopify. Null when there is nothing to report.

Example: null
bill_statusstring

unbilled, partially_billed or billed: how many of the purchase order's committed receipts are on a bill that is posted to the merchant's accounting platform (none, some or all). Only posted bills count, so a bill that failed to post leaves the purchase order unbilled.

Example: unbilled
bills_countinteger

Number of bills created from this purchase order's receipts, in any state, including bills not yet posted or that failed to post. It can be above zero while bill_status is still unbilled.

Example: 0
receiving_modestring

How stock on this purchase order reaches the store, set from the merchant's Bookkeep settings when the purchase order is created. standard: the merchant records receipts in Bookkeep. shopify_transfers: Bookkeep sends the order to Shopify as one inventory transfer per destination location, and the stores receive it in Shopify (see transfers).

Possible values: [standard, shopify_transfers]

Example: standard
is_editableboolean

True while the status is draft. Only then can you change the line items with PATCH.

Example: true
is_cancellableboolean

True when the purchase order can be cancelled now: a draft or ordered purchase order with no receipts whose incoming stock has not been updated in Shopify, or an in_transit purchase order none of whose transfers has been created in Shopify and whose transfers are not still syncing.

Example: true
is_revertibleboolean

Whether the merchant can move the purchase order back to draft in the Bookkeep app. An API key cannot do this.

Example: false
is_note_editableboolean

Whether the merchant can still edit notes and costs in the Bookkeep app. True for ordered, partial, in_transit and partially_transferred. An API key cannot make this edit.

Example: false
is_cost_editableboolean

Always the same as is_note_editable: one restricted edit in the Bookkeep app covers both notes and costs.

Example: false
is_deletableboolean

Whether the merchant can delete the purchase order in the Bookkeep app. An API key cannot delete purchase orders.

Example: false
catalog_sync_warnings object[]

Present only when one or more line items could not be matched to a product in your Shopify store. The purchase order is still saved; check the listed lines.

  • Array [
    • inventory_item_idstringnullable
    variant_idstringnullable
    errorstring
  • ]
    • line_items object[]
  • Array [
    • idinteger

    The line item's ID. Send it on PATCH to change or remove this line.

    Example: 1
    client_line_idstringnullable

    The identifier you sent for this line, if any. Unique within the purchase order.

    Example: null
    skustringnullable

    The product's SKU in the merchant's Shopify store.

    Example: TSHIRT-BLK-M
    barcodestringnullable

    The item's barcode.

    Example: null
    titlestringnullable

    Product title.

    Example: Widget
    image_urlstringnullable

    The product image from the Shopify store.

    Example: null
    unit_costnumbernullable

    Cost per unit, in the purchase order's currency.

    Example: 4.5
    line_totalnumbernullable

    unit_cost times quantity_ordered, before tax.

    Example: 45
    product_idstringnullable

    The Shopify product ID (gid://shopify/Product/<id>). You can look these IDs up with the Shopify Admin GraphQL API.

    Example: gid://shopify/Product/1
    variant_idstringnullable

    The Shopify product variant ID (gid://shopify/ProductVariant/<id>). You can look these IDs up with the Shopify Admin GraphQL API.

    Example: gid://shopify/ProductVariant/1
    location_idstringnullable

    The Shopify location for this line (gid://shopify/Location/<id>).

    Example: gid://shopify/Location/1
    location_namestringnullable

    Name of the line's location.

    Example: Main Warehouse
    tax_percentstringnullable

    Tax rate for the line as a percentage, returned as a string, for example "8.25" for 8.25%.

    Example: 0.0
    supplier_skustringnullable

    The supplier's own code for this item.

    Example: null
    notestringnullable

    A note on this line.

    Example: null
    variant_titlestringnullable

    The variant's title, for example a size or colour.

    Example: Default Title
    quantity_orderedinteger

    Number of units ordered.

    Example: 10
    inventory_item_idstringnullable

    The Shopify inventory item ID (gid://shopify/InventoryItem/<id>). You can look these IDs up with the Shopify Admin GraphQL API.

    Example: gid://shopify/InventoryItem/1
    positioninteger

    Display order of the line on the purchase order.

    Example: 1
    added_during_receivingboolean

    True when the line was added while receiving stock, not when the order was placed.

    Example: false
    variant_supplier_cost objectnullable

    This item's entry in the supplier's price list in Bookkeep: the supplier's SKU, prices and pack details. Null when none is recorded.

    inventory_item_idstringnullable

    The Shopify inventory item the entry is for, as the number only, without the gid://shopify/InventoryItem/ prefix the line's own inventory_item_id has.

    Example: 46217359098139
    supplier_skustringnullable

    The supplier's code for the item.

    Example: SUP-WIDGET-1
    supplier_pricenumbernullable

    The price on the supplier's price list.

    Example: 4.5
    last_costnumbernullable

    The unit cost most recently paid for the item.

    Example: 4.5
    currencystringnullable

    Currency of supplier_price and last_cost.

    Example: USD
    is_defaultboolean

    Whether this supplier is the item's default supplier.

    Example: true
    pack_sizeintegernullable

    Units per pack when ordering.

    Example: 1
    order_uomstringnullable

    Unit the item is ordered in, for example case.

    Example: each
    case_costnumbernullable

    Cost of one ordering unit.

    Example: 4.5
    base_uomstringnullable

    Unit the item is stocked in.

    Example: each
    sold_bystringnullable

    Unit the item is sold in.

    Example: each
    created_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
    updated_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
  • ]
    • transfers object[]

    The Shopify inventory transfers for a shopify_transfers purchase order, one per destination location. Empty for a standard purchase order, until the merchant sends the order to Shopify, and again if the merchant moves it back to draft.

  • Array [
    • uuidstring

    The transfer's unique identifier.

    Example: 3c2b1a0f-9e8d-4c7b-a6f5-e4d3c2b1a0f9
    destination_location_idstring

    The Shopify location the transfer delivers to.

    Example: gid://shopify/Location/123456789
    destination_location_namestringnullable

    Name of that location. Null when no name was known.

    Example: Main Warehouse
    statusstring

    pending until Shopify has the transfer, then follows it in Shopify: ready_to_ship, in_transit, transferred or cancelled. A transfer cancelled before it reached Shopify goes from pending to cancelled.

    Possible values: [pending, ready_to_ship, in_transit, transferred, cancelled]

    Example: in_transit
    shopify_transfer_gidstringnullable

    The transfer's ID in Shopify. Null until Shopify has the transfer.

    Example: gid://shopify/InventoryTransfer/987654321
    shopify_shipment_gidstringnullable

    The ID of the transfer's shipment in Shopify. Null until there is one.

    Example: null
    sync_errorstringnullable

    Why the last attempt to send or update the transfer in Shopify failed. Null when it succeeded. Free text for display; the wording can change.

    Example: null
    created_atstring<date-time>

    When the transfer was created in Bookkeep.

    Example: 2026-06-01T12:00:00.000Z
    updated_atstring<date-time>

    When the transfer was last changed.

    Example: 2026-06-01T12:00:00.000Z
    line_items object[]

    What was sent to this location and what the store has done with it. One entry per inventory item: quantity_ordered sums the purchase order lines for that item at this location.

  • Array [
    • inventory_item_idstring
    Example: gid://shopify/InventoryItem/44444444444
    quantity_orderedinteger

    Quantity sent to this location.

    Example: 10
    quantity_acceptedinteger

    Quantity the store accepted in Shopify.

    Example: 8
    quantity_rejectedinteger

    Quantity the store rejected in Shopify.

    Example: 1
    quantity_cancelledinteger

    Quantity cancelled in Shopify.

    Example: 0
    quantity_unreceivedinteger

    Quantity still on its way. Zero once the transfer is transferred or cancelled, even if the other quantities do not add up.

    Example: 1
  • ]
  • ]
    • created_atstring<date-time>

    When the purchase order was created.

    Example: 2026-06-01T12:00:00.000Z
    updated_atstring<date-time>

    When the purchase order was last changed.

    Example: 2026-06-01T12:00:00.000Z
    PurchaseOrderDetail
    {
      "uuid": "9a1e3b7c-1e3d-4a3f-9f2e-9c6b6e2a2b11",
      "sequence_id": 1042,
      "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",
      "is_archived": false,
      "incoming_sync_status": "pending_sync",
      "incoming_sync_error": null,
      "bill_status": "unbilled",
      "bills_count": 0,
      "receiving_mode": "standard",
      "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": {
            "inventory_item_id": "46217359098139",
            "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"
        }
      ],
      "transfers": [
        {
          "uuid": "3c2b1a0f-9e8d-4c7b-a6f5-e4d3c2b1a0f9",
          "destination_location_id": "gid://shopify/Location/123456789",
          "destination_location_name": "Main Warehouse",
          "status": "in_transit",
          "shopify_transfer_gid": "gid://shopify/InventoryTransfer/987654321",
          "shopify_shipment_gid": null,
          "sync_error": null,
          "created_at": "2026-06-01T12:00:00.000Z",
          "updated_at": "2026-06-01T12:00:00.000Z",
          "line_items": [
            {
              "inventory_item_id": "gid://shopify/InventoryItem/44444444444",
              "quantity_ordered": 10,
              "quantity_accepted": 8,
              "quantity_rejected": 1,
              "quantity_cancelled": 0,
              "quantity_unreceived": 1
            }
          ]
        }
      ],
      "created_at": "2026-06-01T12:00:00.000Z",
      "updated_at": "2026-06-01T12:00:00.000Z"
    }