Skip to content
YoPrintDevelopers

Get a purchase order

Open .md

GET/v1/api/store/{team_slug}/purchase_order/{hash_id}

v1Operation ID v1_public_purchase_order_show

Returns one purchase order with its lines, status, vendor, delivery and billing addresses, creator and tags.

This operation is kept for YoPrint's Zapier app, which uses this path, and its answer keeps the flat line fields Zapier reads: each line in items has product (type, with id or name), quantity, price and totals as plain values. The public API has no newer purchase order operations to use instead: creating, editing and receiving purchase orders are not part of it.

Money in this answer is in thousandths, an older encoding (10800 is 10.80): calc_subtotal, calc_tax and calc_total on the purchase order and on each line, and each line's price. A whole number of thousandths is a JSON integer; an amount finer than a thousandth comes back as a decimal string such as "12656.3", whatever headers you send, so parse these as decimals. See Money and quantities. A line's quantity is what is still to receive, not what was ordered; received_total is what has arrived. items lists every line, deleted and voided ones included, and the rows don't say which.

{hash_id} is the purchase order's id, not its number (PO0042). Deleted purchase orders are not found.

Permission

Who can read it: the team owner; a role whose Manage Purchase Order level includes view_all_po, for any of the team's purchase orders; or one with view_self_po, only for purchase orders the API key's user created or is assigned to (any other purchase order answers 404).

Path parameters

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • hash_idstringrequired

    The purchase order's id (not its number, such as PO0042). A hash id from an earlier answer; unique keys and document numbers (such as PO0042) don't work here.

    • Example EDhVUaC6jbLbed

Request body

This operation takes no request body.

Response

200Successful response.

  • dataobjectrequired
    Child fields (39)
    • calc_subtotalinteger | stringrequired

      The purchase order's subtotal. Thousandths, an older encoding: 10800 is 10.80. A whole number of thousandths comes back as a JSON integer; an amount finer than a thousandth comes back as a decimal string, such as "12656.3", whatever headers you send. Parse it as a decimal. See Money and quantities.

    • calc_taxinteger | stringrequired

      Its tax. Thousandths, an older encoding: 10800 is 10.80. A whole number of thousandths comes back as a JSON integer; an amount finer than a thousandth comes back as a decimal string, such as "12656.3", whatever headers you send. Parse it as a decimal. See Money and quantities.

    • calc_totalinteger | stringrequired

      Its total. Thousandths, an older encoding: 10800 is 10.80. A whole number of thousandths comes back as a JSON integer; an amount finer than a thousandth comes back as a decimal string, such as "12656.3", whatever headers you send. Parse it as a decimal. See Money and quantities.

    • idstringrequired

      The purchase order's id: use it in the path.

    • itemsarray of objectsrequired

      Every line of the purchase order, including deleted and voided ones: the rows don't say which.

      Fields of each item (11)
      • calc_subtotalinteger | stringrequired

        The line's subtotal as YoPrint stores it: usually price times the quantity ordered; on some older lines, times the quantity still to receive. Thousandths, an older encoding: 10800 is 10.80. A whole number of thousandths comes back as a JSON integer; an amount finer than a thousandth comes back as a decimal string, such as "12656.3", whatever headers you send. Parse it as a decimal. See Money and quantities.

      • calc_taxinteger | stringrequired

        The line's tax. Thousandths, an older encoding: 10800 is 10.80. A whole number of thousandths comes back as a JSON integer; an amount finer than a thousandth comes back as a decimal string, such as "12656.3", whatever headers you send. Parse it as a decimal. See Money and quantities.

      • calc_totalinteger | stringrequired

        calc_subtotal plus calc_tax. Thousandths, an older encoding: 10800 is 10.80. A whole number of thousandths comes back as a JSON integer; an amount finer than a thousandth comes back as a decimal string, such as "12656.3", whatever headers you send. Parse it as a decimal. See Money and quantities.

      • idstringrequired

        The line's id.

      • non_inventorybooleanrequired

        true for a line that doesn't track stock.

      • priceinteger | stringrequired

        The unit price. Thousandths, an older encoding: 10800 is 10.80. A whole number of thousandths comes back as a JSON integer; an amount finer than a thousandth comes back as a decimal string, such as "12656.3", whatever headers you send. Parse it as a decimal. See Money and quantities.

      • productobjectrequired

        What the line buys, flat. id is a catalog item id such as smr-10001 for db_catalog, or the hash id of your product or variant for db_simple, user_simple and db_variant; name is the line's own name for custom, fee, fees and customer_provide_product. Older lines can have cart_item or order_item, with that record's id. size and color appear only when the line has them.

        Child fields (5)
        • typestringrequired

          The product kind, such as db_catalog, user_simple, db_variant, custom or fee.

        • colorstring
        • idstring
        • namestring | null
        • sizestring
      • quantityinteger | stringrequired

        The quantity still to receive (ordered minus received), not the quantity ordered. A whole number is a JSON integer; a fraction is a decimal string, such as "1.25".

      • received_totalinteger | stringrequired

        The quantity received so far. A whole number is a JSON integer; a fraction is a decimal string, such as "1.25".

      • tax_totalinteger | stringrequired

        The line's own tax rate, used when tax_mode is line_level, as a percentage ×1000: 8000 is 8% (0 when the line has none). A rate that is not a whole number comes back as a decimal string.

      • positioninteger | string | null

        The line's place on the purchase order, or null. A whole number is a JSON integer; a fraction is a decimal string, such as "1.25".

    • scoped_idstringrequired

      The purchase order number people see, such as PO0042. Not an id.

    • status_idstring | nullrequired
    • trashedbooleanrequired
    • billing_addressobject | null

      The billing address.

      Child fields (33)
      • address1string | nullrequired
      • idstringrequired
      • is_current_sourcebooleanrequired

        False for deleted, replaced, Shopify or redacted addresses. Only current addresses can be picked for new documents or edited.

      • is_primarybooleanrequired
      • labelstring | nullrequired
      • revision_numberintegerrequired

        Goes up by one on every saved change. Send it back as base_revision_number when updating the address to protect against concurrent edits.

      • rolestringrequired

        billing or shipping for customer addresses.

      • trashedbooleanrequired
      • address2string | null
      • address_family_idstring | null

        Shared by an address and the copies made when it was edited after use.

      • citystring | null
      • copied_from_address_idstring | null
      • countrystring | null
      • country_codestring | null
      • customer_idstring

        Customer addresses only: the customer's id.

      • external_typestring | null

        shopify for an address synced from Shopify.

      • hold_stockboolean

        Company locations only; false for customer addresses.

      • is_default_warehouseboolean

        Company locations only; false for customer addresses.

      • is_externalboolean

        True for an address synced from Shopify; such addresses are read-only.

      • nexusboolean

        Company locations only; false for customer addresses.

      • notestring | null
      • owner_idstring | null

        The owner's id: for a customer address, the customer's id (the same as customer_id).

      • owner_typestring

        customer for customer addresses.

        • One of: "customer", "team", "unknown"
      • postal_can_validateboolean
      • postal_is_validboolean
      • postal_validatedboolean

        True once YoPrint has checked the address with its address validator. postal_can_validate says whether it could be checked and postal_is_valid gives the result. Any edit resets it to false.

      • postcodestring | null
      • sourcestring

        customer for customer addresses.

        • One of: "customer", "company_location", "custom", "unknown"
      • statestring | null
      • state_codestring | null
      • superseded_atstring (date-time) | null
      • superseded_by_address_idstring | null

        Set on an old copy: the address that replaced it.

      • used_by_active_profileboolean

        True when a brand profile uses it as Ship From. Sent on lists, reads, updates and customer answers; not on create or set-primary.

    • billing_address_idstring | null
    • created_atstring (date-time) | null
    • created_bystring | null

      The team member who created it.

    • creatorobject | null

      The team member who created it: id, name, email, avatar_url, timezone and a few profile flags.

      Child fields (3)
    • doc_viewer_urlstring

      A link that opens the purchase order in the document viewer, with the same kind of token.

    • due_datestring (date-time) | null
    • internal_notestring | null
    • is_custom_warehouseboolean

      true when the delivery address is not one of the team's company locations.

    • issue_datestring (date-time) | null
    • namestring | null
    • pdfarray of objects

      PDF links: the purchase order detail, its 4" x 6" label, and the team's custom purchase order templates. Each url carries a token like pdf_url.

      Fields of each item (3)
    • pdf_urlstring

      A link that downloads the purchase order PDF. Its token stops working 9,000 hours (about a year) after the answer was made, and anyone with the link can open the PDF: don't share it.

    • quickbook_disable_syncboolean

      true when QuickBooks sync is off for this purchase order.

    • quickbook_last_error_syncstring (date-time) | null
    • quickbook_last_success_syncstring (date-time) | null
    • statusobject | null

      The purchase order's status, as List purchase order statuses returns it: id, role (purchase_order), type (start, pre_production, in_progress or end), label, customer_label, color, position and trashed.

      Child fields (4)
      • idstring
      • labelstring
      • rolestring
      • typestring
        • One of: "start", "pre_production", "in_progress", "end"
    • status_completion_datestring (date-time) | null

      When it was moved to its final (end) status; null otherwise.

    • status_last_change_datestring (date-time) | null
    • tagsarray of objects
      Fields of each item (3)
      • color_hexstring | nullrequired

        Such as #2563EB. Null for a tag saved without a color.

      • idstringrequired
      • namestringrequired
    • tax_modestring | null

      order_level: one tax_rate for the purchase order, and each line is taxable or not. line_level: each line has its own rate (tax_total).

    • tax_ratestring | null

      For order_level: the rate as a decimal string fraction with 6 decimals, "0.080000" is 8%. Null when not set.

    • teamobject

      Your team, as the shared purchase order answer carries it: id, name, slug, contact details, the public ids of its enabled payment gateways, and plan. Nothing here is specific to the purchase order.

    • updated_atstring (date-time) | null
    • vendorobject | null

      The vendor with its contacts, as Get a vendor returns it.

      Child fields (8)
    • vendor_idstring | null
    • vendor_notestring | null

      The note printed for the vendor.

    • versioninteger

      2 for purchase orders made in the current editor; 1 for older ones.

    • warehouseobject | null

      The delivery address, usually one of the team's company locations.

    • warehouse_can_hold_stockboolean

      true when the delivery address is set and holds stock, so receiving adds stock there.

    • warehouse_idstring | null

      Where the goods are delivered.

  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

    When
    Your role has no Manage Purchase Order permission to view. This 403 has a short body, {"message": "Insufficient Permission"}, with no success or error.
    Fix
    Ask a team owner to give your role a Manage Purchase Order level.

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

    When
    No live purchase order with this id in the team, or your role sees only purchase orders you created or are assigned to and this is not one of them. error.code is null and error.message names the record type.
    Fix
    Check the id, or ask to be assigned to the purchase order.

Notes

  • A line's quantity is the quantity still to receive. To get the quantity ordered, add received_total.
  • Read status.type: end means the purchase order is complete.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com