Skip to main content

PurchaseOrder

The purchase order returned by the purchase order read endpoints, as a plain JSON object with no data/included envelope.

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
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. These are also the values filter[status_eq] accepts.

Example: ordered
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: 0
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: 0
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: 0
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: bookkeep
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
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
line_items object[]

Present only when include=line_items was requested.

  • Array [
    • idinteger

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

    Example: 31842
    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: WIDGET-1
    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
    created_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
    updated_atstring<date-time>
    Example: 2026-06-01T12:00:00.000Z
  • ]
    • receipts object[]

    Present only when include=receipts was requested (requires purchase_order_receipts:read).

  • Array [
    • uuidstring
    Example: 3f2a9c1e-2b3d-4c5e-8f6a-1b2c3d4e5f60
    namestringnullable
    Example: Receipt 1
    statusstring
    Example: committed
    received_atstring<date-time>nullable
    Example: 2026-06-03T09:00:00.000Z
    invoice_numberstringnullable
    Example: null
    voided_atstring<date-time>nullable
    Example: null
    void_reasonstringnullable
    Example: null
    created_atstring<date-time>
    Example: 2026-06-03T09:00:00.000Z
    updated_atstring<date-time>
    Example: 2026-06-03T09:00:00.000Z
  • ]
    • supplier objectnullable

    Present only when include=supplier was requested.

    uuidstring

    The supplier's unique identifier, the same uuid the Suppliers endpoints return.

    Example: 6d1f2a3b-4c5d-4e7f-8091-a2b3c4d5e6f7
    namestringnullable
    Example: Acme Supply
    company_namestringnullable
    Example: Acme Supply Co.
    currency_codestringnullable
    Example: USD
    websitestringnullable
    Example: null
    payment_termsstringnullable
    Example: null
    price_liststringnullable
    Example: null
    supplier_tax_typestringnullable
    Example: null
    is_hiddenboolean
    Example: false
    created_atstring<date-time>
    Example: 2026-01-01T00:00:00.000Z
    updated_atstring<date-time>
    Example: 2026-01-01T00:00:00.000Z
    PurchaseOrder
    {
      "uuid": "9a1e3b7c-1e3d-4a3f-9f2e-9c6b6e2a2b11",
      "sequence_id": 1042,
      "name": null,
      "status": "ordered",
      "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": 0,
      "subtotal": 0,
      "total": 0,
      "metadata": {},
      "source": "bookkeep",
      "currency": "USD",
      "is_archived": false,
      "incoming_sync_status": "pending_sync",
      "incoming_sync_error": null,
      "bill_status": "unbilled",
      "bills_count": 0,
      "created_at": "2026-06-01T12:00:00.000Z",
      "updated_at": "2026-06-01T12:00:00.000Z",
      "line_items": [
        {
          "id": 31842,
          "client_line_id": null,
          "sku": "WIDGET-1",
          "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,
          "created_at": "2026-06-01T12:00:00.000Z",
          "updated_at": "2026-06-01T12:00:00.000Z"
        }
      ],
      "receipts": [
        {
          "uuid": "3f2a9c1e-2b3d-4c5e-8f6a-1b2c3d4e5f60",
          "name": "Receipt 1",
          "status": "committed",
          "received_at": "2026-06-03T09:00:00.000Z",
          "invoice_number": null,
          "voided_at": null,
          "void_reason": null,
          "created_at": "2026-06-03T09:00:00.000Z",
          "updated_at": "2026-06-03T09:00:00.000Z"
        }
      ],
      "supplier": {
        "uuid": "6d1f2a3b-4c5d-4e7f-8091-a2b3c4d5e6f7",
        "name": "Acme Supply",
        "company_name": "Acme Supply Co.",
        "currency_code": "USD",
        "website": null,
        "payment_terms": null,
        "price_list": null,
        "supplier_tax_type": null,
        "is_hidden": false,
        "created_at": "2026-01-01T00:00:00.000Z",
        "updated_at": "2026-01-01T00:00:00.000Z"
      }
    }