Skip to content
YoPrintDevelopers

List quotes

Open .md

POST/v2/api/store/{team_slug}/v2/quote/filter

v2Operation ID v2_public_quote_filter

Lists quotes, a page at a time, with filters and sorting. It is a read, despite the POST. Sales orders are not included.

Send filters and sort in the body, both optional. Rows are in data, in the Get a sales order shape without line items; each row carries customer (the customer record, or null), so you don't need a lookup per row. pagination has the total. A page holds the team's page size (50 unless the team changed it); ask for the next page with ?page=2.

Filter keys, with their operators and values:

Key Operators Value
issue_date, due_date (production due), cust_due_date (in-hands date), ship_due_date, deposit_due, full_amount_due, status_last_change_date, status_completion_date, quickbook_last_success_sync, quickbook_last_error_sync eq, gte, lte whole days from today in UTC: 0 is today, -7 a week ago, 7 a week ahead. gte N starts at 00:00 UTC of day N. lte N stops at 00:00 UTC of day N, so day N is left out. eq N matches almost nothing. See the rules below
status_id, customer_id, created_by, assigned_users, tag in, nin a list of ids
status_type in, nin a list of start (Pending), in_progress, end (Completed)
approval_status in, nin a list of requested, sent-to-customer, viewed-by-customer, need-changes, approved
external_type in, nin a list of shopify, native
payment_status, deposit_status eq paid or unpaid
is_rush, draft, quote, trashed_only, created_by_me, assigned_to_me, my_customer, has_order_approval, has_job_approval, has_not_invoiced_items, has_over_invoiced_items, shopify_deleted_externally eq, neq true or false (JSON booleans)
total_qty_need_ordering eq, gte, lte a number

Sort keys: id, issue_date, due_date, start_date, deposit_due, cust_due_date, ship_due_date, full_amount_due, status_last_change_date, status_completion_date, calc_total, status_id, status_position, quote, is_rush, quickbooks_sync_status, name, customer_name, created_at, total_qty_need_ordering; each with direction asc or desc.

Use this instead of the retired v1 quote filter.

Permission

Needs permission to view quotes: a role that sees every order (view_all_order) gets all of them; a role that sees only its own (view_self_order) gets only the ones its user created. Without either, 403.

Business rules

  • Every filter needs key, operator and value, and the operator and value must suit the key; otherwise 422 with no detail of which filter failed.
  • Date filters take a whole number of days from today (UTC), not a calendar date: 0 is today, 7 is 7 days from today, -7 is 7 days ago. The number becomes a UTC date and is compared with the stored date and time. gte N starts at 00:00 UTC of day N. lte N stops at 00:00 UTC of day N, so day N itself is left out. eq N matches only a record stamped exactly 00:00:00 UTC, so in practice almost nothing. Due dates are stored as the end of the team's local day, so a UTC day does not line up with it.
  • To cover the days A to B of your team's calendar, ask gte A-1 and lte B+2, then keep the rows whose date falls in those days by checking the dates in your own code. For "late", ask lte 1 and keep the rows whose date is before now.
  • Booleans must be JSON true or false.
  • Ids are the id fields of other answers (status, customer, user and tag ids).

Path parameters

  • team_slugstringrequired

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

    • Example your-team

Query parameters

  • pageinteger

    The page to return, from 1.

    • Minimum 1

Request body

application/json, optional.

  • count_onlyboolean

    true to get only pagination (the total), with no rows.

  • filtersarray of objects

    Conditions, combined with AND. Leave it out to list everything.

    Fields of each item (3)
    • keystringrequired

      A filter key from the table.

    • operatorstringrequired
      • One of: "eq", "neq", "gte", "lte", "in", "nin"
    • valueanyrequired

      A number of days, a list of ids or options, a string option, a boolean, or a number, depending on the key.

  • sortarray of objects

    Sort order, first entry first.

    Fields of each item (2)
    • directionstringrequired
      • One of: "asc", "desc"
    • keystringrequired

Response

200Successful response.

  • dataarray of objectsrequired
    Fields of each item (110)
    • idstringrequired

      The order's hash id: use it in every other call.

    • internal_statusstringrequired

      draft until published.

      • One of: "draft", "published"
    • object_typestringrequired
      • One of: "sales_order", "quote"
    • scoped_idstringrequired

      The order number people see, SO and at least four digits (quotes too). Not an id.

    • unique_keystringrequired

      The order's unique key (ord_…); accepted wherever {order_unique_key} is.

    • approval_statusstring | null

      requested, sent-to-customer, viewed-by-customer, need-changes or approved; null without approvals.

    • assigned_usersarray of objects

      The team members in the order's Assigned To list (always included).

      Fields of each item (5)
    • auto_invoice_managedboolean

      true when YoPrint keeps one invoice in step with the order.

    • auto_invoice_shipment_price_typestring | null

      DONOTMANAGE, NONE, MARKUP or MARGIN.

    • auto_invoice_shipment_ratedecimal pair

      The MARKUP or MARGIN percentage. A decimal pair: the amount is value ÷ 10^dp ({ "value": 12500000, "dp": 6 } is 12.50). Kept with 6 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • auto_invoice_typestring | null

      How the automatic invoice is built. Always single_invoice today.

    • billing_addressobject | null

      An address, as the address operations return it.

      Child fields (8)
    • billing_address_idstring | null
    • calc_deposit_totalinteger | number | string | null

      The deposit amount, rounded to 2 decimal places: the percentage of order_item_cart_total, or of the invoiced total once every line is invoiced (or the invoiced total reaches the order's); 0 unless deposit_required. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • client_notestring | null

      The Client Note.

    • created_atstring (date-time) | null

      Created. ISO 8601 with offset, or null.

    • created_bystring | null

      Created By (a team member id).

    • creator_namestring | null
    • cust_due_datestring (date-time) | null

      Customer in-hands date. ISO 8601 with offset, or null.

    • customerobject | null

      Always present on order answers, lists included: the customer record, or null when the order has none. Get a sales order also nests the customer's contacts, addresses, brand profiles, tags, files and assigned users in it.

      Child fields (6)
    • customer_billing_contact_idstring | null

      The id of the contact on the order (the same contact as customer_contact_id), or null.

    • customer_contact_idstring | null
    • customer_has_emailboolean
    • customer_idstring | null
    • customer_po_numberstring | null
    • customer_profile_idstring | null

      Brand profile.

    • deposit_amount_duedecimal pair

      Deposit still to pay (negative once overpaid). A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • deposit_duestring (date-time) | null

      Deposit due date. ISO 8601 with offset, or null.

    • deposit_requiredboolean
    • deposit_totalinteger | number | string | null

      The deposit as a percentage of the order. A percentage ×1000: 8250 is 8.25%. With X-Yoprint-Decimal-Format: exact-v1, a value that isn't a whole number comes back as a string.

    • due_datestring (date-time) | null

      Production due. ISO 8601 with offset, or null.

    • external_idsarray of objects

      The order's links to records in other systems. An empty list when there are none.

    • external_typestring | null

      shopify for a Shopify order; null for YoPrint orders.

    • from_legacyboolean

      true for an order that was moved over from the old format.

    • full_amount_duestring (date-time) | null

      Full payment due date. ISO 8601 with offset, or null.

    • grouped_pdfarray of objects

      PDF links, grouped: Main (only for roles with view_order_finance), Job (not on Shopify orders), Shipment and the team's templates.

      Fields of each item (2)
    • has_external_integration_sync_errorboolean

      true when the last sync with an integration failed.

    • has_invoiceboolean

      true when the order has at least one invoice, so a zero invoiced total can be told apart from no invoice.

    • has_not_invoiced_itemsboolean

      true when some line items are not on an invoice yet.

    • has_over_invoiced_itemsboolean

      true when some line items are invoiced for more than the order has.

    • has_shipment_items_not_allocatedboolean

      true when some line items are not on a shipment yet.

    • has_shipment_items_over_allocatedboolean

      true when some line items are on shipments for more than the order has.

    • has_valid_invoiceboolean

      true when at least one of the order's invoices is in a valid state.

    • has_valid_shipmentboolean

      true when at least one of the order's shipments is in a valid state.

    • inventory_statusstring | null

      Stock status of the order's lines: not_committed, committed, partially_committed, not_applicable or pending.

    • invoice_lock_versioninteger | string | null

      Changes whenever the order's invoices change.

    • invoiced_discount_subtotaldecimal pair

      Discounts on the order's invoices; 0 until invoiced. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • invoiced_order_item_subtotaldecimal pair

      The lines and shipping fees the order's invoices bill (the sum of their cart_item_subtotal); 0 until invoiced. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • invoiced_shipment_subtotaldecimal pair

      The shipping fees in invoiced_order_item_subtotal; 0 until invoiced. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • invoiced_tax_subtotaldecimal pair

      Tax on the order's invoices; 0 until invoiced. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • invoiced_totaldecimal pair

      Total of the order's invoices. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • is_client_note_editableboolean

      false for a Shopify order, whose client note comes from Shopify.

    • is_externalboolean

      true for an order synced from an integration such as Shopify.

    • is_legacyboolean

      true for an order made in the old format.

    • is_rushboolean
    • issue_datestring (date-time) | null

      Issue date. ISO 8601 with offset, or null.

    • job_lock_versioninteger | string | null

      Changes whenever the order's jobs change.

    • last_payment_request_datestring (date-time) | null

      When a payment reminder was last emailed for the order. ISO 8601 with offset, or null.

    • lock_versioninteger | string | null

      Changes on every save.

    • modestring

      Older flag: create for a draft, view once published.

      • One of: "create", "view", "edit"
    • namestring | null
    • order_balance_duedecimal pair

      Invoiced total minus paid. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • order_item_cart_totaldecimal pair

      The value of the order's lines: the order's own total before invoicing. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • order_item_lock_versioninteger | string | null

      Changes whenever the order's line items change.

    • order_margin_percentagedecimal pair

      Margin, in percent. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Kept with 2 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • order_markup_percentagedecimal pair

      Markup, in percent. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Kept with 2 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • order_profitdecimal pair

      Profit. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Kept with 2 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • paid_amountinteger | number | string | null

      Paid so far. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • payment_lock_versioninteger | string | null

      Changes whenever the order's payments change.

    • payment_term_idstring | null
    • pricing_group_idstring | null
    • pricing_strategystring | null

      job_separately, job_together or service_loc_together.

    • prod_notestring | null

      The production note.

    • producible_item_countnumber | integer | string | null

      Quantity to produce.

    • quickbook_disable_syncboolean

      true when QuickBooks sync is off for this order.

    • quickbook_disable_sync_atstring (date-time) | null

      When the switch was last changed. ISO 8601 with offset, or null.

    • quickbook_disable_sync_bystring | null

      The team member who last changed the switch, or null.

    • quickbook_disable_sync_reasonstring | null

      The note given at the last change of the order's QuickBooks sync switch (off or back on), at most 500 characters, or null.

    • quickbook_last_error_syncstring (date-time) | null

      When a QuickBooks sync of the order last failed. ISO 8601 with offset, or null.

    • quickbook_last_success_syncstring (date-time) | null

      When QuickBooks last accepted the order. ISO 8601 with offset, or null.

    • quickbooks_holdobject | null

      Set when YoPrint holds back a QuickBooks payment covering this order: code is changed, deleted or rejected (the payment was changed or deleted in QuickBooks, or QuickBooks refused a change), and detail is already_deposited (the payment is in a QuickBooks bank deposit) or null. Null when nothing is held.

      Child fields (2)
      • codestring
        • One of: "changed", "deleted", "rejected"
      • detailstring | null
    • quoteboolean

      Older flag: true for a quote.

    • ship_due_datestring (date-time) | null

      Ship due date. ISO 8601 with offset, or null.

    • shipment_billable_fee_invoice_statusstring | null

      Whether those shipping fees are on an invoice. Null when there is nothing to bill.

    • shipment_billable_fee_totaldecimal pair

      The shipping fees you bill the customer on the order's shipments. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • shipment_cost_totaldecimal pair

      Shipping cost incurred. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • shipment_lock_versioninteger | string | null

      Changes whenever the order's shipments change.

    • shipping_addressobject | null

      An address, as the address operations return it.

    • shipping_address_idstring | null
    • shopify_last_error_syncstring (date-time) | null

      When a Shopify sync of the order last failed. Shopify orders only. ISO 8601 with offset, or null.

    • shopify_last_success_syncstring (date-time) | null

      When Shopify last accepted the order. Shopify orders only. ISO 8601 with offset, or null.

    • shopify_terminal_topicstring | null

      Shopify orders only: the Shopify event name behind the order's final state there. Null on YoPrint orders. The answer can also hold more shopify_* fields (shopify_admin_url, shopify_compliance_deletion, shopify_finance_notices, shopify_has_fulfillment_conflict, shopify_last_fulfillment_conflict_at): they are null or empty on YoPrint orders.

    • start_datestring (date-time) | null

      Production start. ISO 8601 with offset, or null.

    • statusobject | null

      The order's status (always included).

      Child fields (9)
      • colorstringrequired

        A hex color, such as #2196f3.

      • customer_labelstringrequired

        What customers see in the customer portal. When none is set: Pending for start, In Progress for in_progress and pre_production, Completed for end.

      • idstringrequired
      • labelstringrequired

        The status name people see.

      • positionintegerrequired

        Sort order within its list, lowest first.

      • rolestringrequired

        Which list the status belongs to: order, quote, job, shipment, purchase_order, pipeline or customer_message.

      • trashedbooleanrequired

        true for a deleted status.

      • typestringrequired

        start is the first status of its list and end the last; pre_production and in_progress are the ones in between.

        • One of: "start", "pre_production", "in_progress", "end"
      • pipeline_idstring

        The task preset, for pipeline statuses only; absent for other roles.

    • status_completion_datestring (date-time) | null

      When the order's status last moved to an end status. ISO 8601 with offset, or null.

    • status_idstring

      The order's status (from the team's sales order or quote statuses).

    • status_last_change_datestring (date-time) | null

      Last status change. ISO 8601 with offset, or null.

    • tagsarray of objects
      Fields of each item (3)
    • total_qty_need_orderingstring

      Quantity still to buy, as a decimal string with 8 decimal places ("24.00000000").

    • trashedboolean

      true when the order is deleted.

    • typestring

      Older name for object_type.

      • One of: "order", "quote"
    • unallocated_amountinteger | number | string | null

      Payments not yet allocated to an invoice. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • updated_atstring (date-time) | null

      Last changed. ISO 8601 with offset, or null.

    • versioninteger | string | null

      The order format version.

    • wallet_currency_isostring | null

      The order's currency code (USD and so on), or null on older orders without one.

    • warehouse_idstring | null
    • calc_discountinteger | number | string | nulldeprecated

      Deprecated: use invoiced_discount_subtotal, the same amount. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • calc_subtotalinteger | number | string | nulldeprecated

      Deprecated: use invoiced_order_item_subtotal, which already includes billed shipping. This older field adds invoiced_shipment_subtotal to it once more. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • calc_taxinteger | number | string | nulldeprecated

      Deprecated: use invoiced_tax_subtotal, the same amount. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • calc_totalinteger | number | string | nulldeprecated

      Deprecated: use invoiced_total, the same amount. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

  • statusintegerrequired
  • successbooleanrequired
  • paginationobject
    Child fields (6)
    • countintegerrequired
    • currentPageintegerrequired
    • perPageintegerrequired
    • totalintegerrequired
    • totalPagesintegerrequired

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
    The role can't view quotes at all. This error has no envelope: the body is {"message": "You do not have permission to view this resource"}.
    Fix
    Ask the team owner for view permission.

  • 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.

  • 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

    When
    An unknown key, a wrong operator for the key, or a value of the wrong kind.
    Fix
    Check each filter against the table.

Notes

  • Deleted quotes are hidden unless you filter trashed_only eq true.
  • Drafts are included; filter draft eq false to leave them out.
  • Day offsets here count forward from today (7 is a week ahead). Some older v1 filters count the other way; check each filter's page before reusing a filter.

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