COconductor-is

Retrieve a purchase order

Changed on

Retrieves a purchase order by ID.

IMPORTANT: If you need to fetch multiple specific purchase orders by ID, use the list endpoint instead with the ids parameter. It accepts an array of IDs so you can batch the request into a single call, which is significantly faster.

NOTE: The response automatically includes any linked transactions.

get/quickbooks-desktop/purchase-orders/{id}

Request

Path parameters

idstring required

The QuickBooks-assigned unique identifier of the purchase order to retrieve.

Example:123ABC-1234567890

Headers

Conductor-End-User-Idstring required

The ID of the End-User to receive this request.

Example:end_usr_1234567abcdefg

Response

Returns the specified purchase order.

idstring required

The unique identifier assigned by QuickBooks to this purchase order. This ID is unique across all transaction types.

objectType'qbd_purchase_order' required

The type of object. This value is always "qbd_purchase_order".

createdAtstring required

The date and time when this purchase order was created, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm), which QuickBooks Desktop interprets in the local timezone of the end-user's computer.

updatedAtstring required

The date and time when this purchase order was last updated, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm), which QuickBooks Desktop interprets in the local timezone of the end-user's computer.

revisionNumberstring required

The current QuickBooks-assigned revision number of this purchase order object, which changes each time the object is modified. When updating this object, you must provide the most recent revisionNumber to ensure you're working with the latest data; otherwise, the update will return an error.

transactionDatestring date required

The date of this purchase order, in ISO 8601 format (YYYY-MM-DD).

refNumberstring nullable required

The case-sensitive user-defined reference number for this purchase order, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user.

dueDatestring date nullable required

The date by which this purchase order must be paid, in ISO 8601 format (YYYY-MM-DD).

expectedDatestring date nullable required

The date on which shipment of this purchase order is expected to be completed, in ISO 8601 format (YYYY-MM-DD).

shipmentOriginstring nullable required

The origin location from where the product associated with this purchase order is shipped. This is the point at which ownership and liability for goods transfer from seller to buyer. Internally, QuickBooks uses the term "FOB" for this field, which stands for "freight on board". This field is informational and has no accounting implications.

totalAmountstring required

The total monetary amount of this purchase order, equivalent to the sum of the amounts in lines and lineGroups, represented as a decimal string.

exchangeRatenumber nullable required

The market exchange rate between this purchase order's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).

totalAmountInHomeCurrencystring nullable required

The total monetary amount of this purchase order converted to the home currency of the QuickBooks company file. Represented as a decimal string.

isManuallyClosedboolean required

Indicates whether this purchase order has been manually marked as closed, even if all items have not been received or the sale has not been cancelled. Once the purchase order is marked as closed, all of its line items become closed as well. You cannot change isManuallyClosed to false after the purchase order has been fully received.

isFullyReceivedboolean nullable required

Indicates whether all items in this purchase order have been received and none of them were closed manually.

memostring nullable required

A memo or note for this purchase order that appears in reports, but not on the purchase order.

vendorMessagestring nullable required

A message to be printed on this purchase order for the vendor to read.

isQueuedForPrintboolean nullable required

Indicates whether this purchase order is included in the queue of documents for QuickBooks to print.

isQueuedForEmailboolean nullable required

Indicates whether this purchase order is included in the queue of documents for QuickBooks to email to the customer.

otherCustomField1string nullable required

A built-in custom field for additional information specific to this purchase order. Unlike the user-defined fields in the customFields array, this is a standard QuickBooks field that exists for all purchase orders for convenience. Developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.

otherCustomField2string nullable required

A second built-in custom field for additional information specific to this purchase order. Unlike the user-defined fields in the customFields array, this is a standard QuickBooks field that exists for all purchase orders for convenience. Like otherCustomField1, developers often use this field for tracking information that doesn't fit into other standard QuickBooks fields. Hidden by default in the QuickBooks UI.

externalIdstring nullable required

A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.

Example response

{
  "id": "123ABC-1234567890",
  "objectType": "qbd_purchase_order",
  "createdAt": "2025-01-01T12:34:56+00:00",
  "updatedAt": "2025-02-01T12:34:56+00:00",
  "revisionNumber": "1721172183",
  "vendor": {
    "id": "80000001-1234567890",
    "fullName": "Acme Supplies Ltd."
  },
  "class": {
    "id": "80000001-1234567890",
    "fullName": "Office Supplies"
  },
  "inventorySite": {
    "id": "80000001-1234567890",
    "fullName": "Main Warehouse"
  },
  "shipToEntity": {
    "id": "80000001-1234567890",
    "fullName": "Customer"
  },
  "documentTemplate": {
    "id": "80000001-1234567890",
    "fullName": "Purchase Order Template"
  },
  "transactionDate": "2024-10-01",
  "refNumber": "PO-1234",
  "vendorAddress": {
    "line1": "Conductor Labs Inc.",
    "line2": "540 Market St.",
    "line3": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94110",
    "country": "United States",
    "note": "Conductor HQ"
  },
  "shippingAddress": {
    "line1": "Conductor Labs Inc.",
    "line2": "540 Market St.",
    "line3": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94110",
    "country": "United States",
    "note": "Conductor HQ"
  },
  "terms": {
    "id": "80000001-1234567890",
    "fullName": "Net 30"
  },
  "dueDate": "2024-10-31",
  "expectedDate": "2024-01-01",
  "shippingMethod": {
    "id": "80000001-1234567890",
    "fullName": "FedEx Ground"
  },
  "shipmentOrigin": "San Francisco, CA",
  "totalAmount": "1000.00",
  "currency": {
    "id": "80000001-1234567890",
    "fullName": "USD"
  },
  "exchangeRate": 1.2345,
  "totalAmountInHomeCurrency": "1234.56",
  "isManuallyClosed": true,
  "memo": "Office supplies for September",
  "vendorMessage": "Please include packing slip with shipment",
  "isQueuedForPrint": true,
  "isQueuedForEmail": true,
  "salesTaxCode": {
    "id": "80000001-1234567890",
    "fullName": "Non"
  },
  "otherCustomField1": "Special handling required",
  "otherCustomField2": "Always ship with a spare",
  "externalId": "12345678-abcd-1234-abcd-1234567890ab",
  "linkedTransactions": [
    {
      "id": "123ABC-1234567890",
      "objectType": "qbd_linked_transaction",
      "transactionType": "invoice",
      "transactionDate": "2024-10-01",
      "refNumber": "LINK-1234",
      "linkType": "amount",
      "amount": "1000.00"
    }
  ],
  "lines": [
    {
      "id": "456DEF-1234567890",
      "objectType": "qbd_purchase_order_line",
      "item": {
        "id": "80000001-1234567890",
        "fullName": "Widget A"
      },
      "sku": "MPN-123456",
      "description": "Office chairs - Herman Miller Aeron (Black)",
      "quantity": 5,
      "unitOfMeasure": "Each",
      "overrideUnitOfMeasureSet": {
        "id": "80000001-1234567890",
        "fullName": "Volume Units"
      },
      "rate": "10.00",
      "class": {
        "id": "80000001-1234567890",
        "fullName": "Office Supplies"
      },
      "amount": "1000.00",
      "inventorySiteLocation": {
        "id": "80000001-1234567890",
        "fullName": "Aisle 3, Shelf B"
      },
      "payee": {
        "id": "80000001-1234567890",
        "fullName": "Acme Corporation"
      },
      "serviceDate": "2024-03-15",
      "salesTaxCode": {
        "id": "80000001-1234567890",
        "fullName": "Non"
      },
      "receivedQuantity": 5,
      "unbilledQuantity": 2,
      "isManuallyClosed": true,
      "otherCustomField1": "Special handling required",
      "otherCustomField2": "Always ship with a spare",
      "customFields": [
        {
          "ownerId": "0",
          "name": "Customer Rating",
          "type": "string_1024_type",
          "value": "Premium"
        }
      ]
    }
  ],
  "lineGroups": [
    {
      "id": "456DEF-1234567890",
      "objectType": "qbd_purchase_order_line_group",
      "itemGroup": {
        "id": "80000001-1234567890",
        "fullName": "Office Supplies Bundle"
      },
      "description": "Office supplies bundle",
      "quantity": 5,
      "unitOfMeasure": "Each",
      "overrideUnitOfMeasureSet": {
        "id": "80000001-1234567890",
        "fullName": "Volume Units"
      },
      "shouldPrintItemsInGroup": true,
      "totalAmount": "1000.00",
      "serviceDate": "2024-03-15",
      "lines": [
        {
          "id": "456DEF-1234567890",
          "objectType": "qbd_purchase_order_line",
          "item": {
            "id": "80000001-1234567890",
            "fullName": "Widget A"
          },
          "sku": "MPN-123456",
          "description": "Office chairs - Herman Miller Aeron (Black)",
          "quantity": 5,
          "unitOfMeasure": "Each",
          "overrideUnitOfMeasureSet": {
            "id": "80000001-1234567890",
            "fullName": "Volume Units"
          },
          "rate": "10.00",
          "class": {
            "id": "80000001-1234567890",
            "fullName": "Office Supplies"
          },
          "amount": "1000.00",
          "inventorySiteLocation": {
            "id": "80000001-1234567890",
            "fullName": "Aisle 3, Shelf B"
          },
          "payee": {
            "id": "80000001-1234567890",
            "fullName": "Acme Corporation"
          },
          "serviceDate": "2024-03-15",
          "salesTaxCode": {
            "id": "80000001-1234567890",
            "fullName": "Non"
          },
          "receivedQuantity": 5,
          "unbilledQuantity": 2,
          "isManuallyClosed": true,
          "otherCustomField1": "Special handling required",
          "otherCustomField2": "Always ship with a spare",
          "customFields": [
            {
              "ownerId": "0",
              "name": "Customer Rating",
              "type": "string_1024_type",
              "value": "Premium"
            }
          ]
        }
      ],
      "customFields": [
        {
          "ownerId": "0",
          "name": "Customer Rating",
          "type": "string_1024_type",
          "value": "Premium"
        }
      ]
    }
  ],
  "customFields": [
    {
      "ownerId": "0",
      "name": "Customer Rating",
      "type": "string_1024_type",
      "value": "Premium"
    }
  ]
}

Changes

  • 8ee3502091a4Revision changes
    • warning

      added the new transfer_inventory enum value to the // response property for the response status

  • 1de07095c4b7Revision changes
    • warning

      for the path request parameter id, the maxLength was set to 36