Skip to content
YoPrintDevelopers

Filter shipments

Open .md

POST/v1/api/store/{team_slug}/shipment/filter

v1Operation ID v1_public_shipment_filter

Returns one page of your team's shipments that match the filters, across all sales orders (quotes, drafts and deleted shipments are left out).

Each row is a summary with its packages and estimates: number (scoped_id, here without the SHIP- prefix), order, shipping type, due dates, ready_to_ship, packer, status, customer, address and pdf links.

Every condition in filters must match (they are joined with AND). Omit filters for no filter; an empty array is a 422. A key that isn't in the table, a missing operator or value, or a value of the wrong kind fails the whole request with 422; the message for filters (or sort) is the bare rule name validation.filter_rule (or validation.filter_sort_rule), with no detail, so check each filter against the table. Send real values: no key here matches empty columns with "null" or "" (for dates, use the ..._is_set keys where the table has them). Hash ids in value are decoded for you. system-current-user stands for the caller only where a key's row says so; elsewhere it is compared as a raw value, so with in it matches nothing and with nin it matches every row that has a value.

key Kind Operators and value Meaning
status_id Hash ids in or nin, with an array of hash ids. The shipment status (from List shipment statuses).
status_type Options in or nin, with an array of the listed values. The kind of status: start (Pending), pre_production or in_progress (In Progress), end (Completed).
shipping_type_id Hash ids in or nin, with an array of hash ids. The shipping type.
ready_to_ship Yes or no eq or neq, with true or false. Every job of the shipment's lines is Completed.
packed_by Hash ids in or nin, with an array of hash ids. Who packed it: an array of user hash ids. system-current-user is not supported here: with in it matches nothing, with nin every shipment with a packer.
customer_due_date Date eq, gte or lte, with a whole number of days counted from now (UTC). See below. The order's customer due date. This key uses its own date comparison rather than the rule below (it compares the date with the current time), so eq may match nothing: use gte and lte and check the edge days.
status_last_change_date Date eq, gte or lte, with a whole number of days counted from now (UTC). See below. When the status last changed.
status_completion_date Date eq, gte or lte, with a whole number of days counted from now (UTC). See below. When the shipment reached a Completed status.
ship_due_date Date eq, gte or lte, with a whole number of days counted from now (UTC). See below. Don't use: accepted, but this route can't apply it and fails with a server error.
order_external_type Options in or nin, with an array of the listed values. Don't use (shopify, native): accepted, but this route can't apply it and fails with a server error.
shipment_source Options in or nin, with an array of the listed values. Don't use (shopify, yoprint, broken_link): accepted, but this route can't apply it and fails with a server error.

A date filter's value is a whole number of days, counted from the moment of the request in UTC: eq N matches the whole UTC day N days from today (0 is today, -1 yesterday); gte N matches dates on or after now plus N days; lte N matches dates on or before now minus N days. So "due in the next 7 days" is due_date gte 0 and due_date lte -7, and "overdue" is due_date lte 0. This differs from the v2 filters (Filter invoices, the production control calendar), where lte and gte both count forward.

The response is one page with pagination. The page size is the team's list page size setting (50 unless the team changed it); per_page is not read. Send page (from 1) in the body or the query string for later pages.

Permission

Any member of the team. No sales order permission is checked.

Path parameters

  • team_slugstringrequired

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

    • Example your-team

Request body

application/json, optional.

  • filtersarray of objects

    Conditions, all of which must match. Omit for no filter.

    • At least 1 item
    Fields of each item (3)
    • keystringrequired

      What to filter on. See the table in the description.

      • One of: "status_id", "status_type", "shipping_type_id", "ready_to_ship", "packed_by", "customer_due_date", "status_last_change_date", "status_completion_date", "ship_due_date", "order_external_type", "shipment_source"
    • operatorstringrequired

      How to compare. Each kind of key accepts only some operators.

      • One of: "eq", "neq", "gt", "gte", "lt", "lte", "in", "nin", "bt", "ct", "sw", "ew"
    • valuestring | number | boolean | arrayrequired

      What to compare with: text, a number of days, true or false, or an array of hash ids or options, by kind of key.

  • pageinteger

    The page to read.

    • Default 1
    • Minimum 1
  • sortarray of objects

    Sort keys, applied in order. Without sort the order is not guaranteed.

    Fields of each item (2)
    • directionstringrequired
      • One of: "asc", "desc"
    • keystringrequired
      • One of: "order_id", "status_id", "customer_due_date", "ship_due_date", "shipping_type_id", "ready_to_ship", "status_last_change_date", "status_completion_date"

Response

200Successful response.

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.

  • 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
    A filter has an unknown key, a missing part, or an operator or value its kind doesn't accept.
    Fix
    Check each filter against the table.

  • 500A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as action_not_allowed; an unexpected failure answers {"message": "Server Error"}. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.

    When
    You filtered on ship_due_date, order_external_type or shipment_source.
    Fix
    Leave those keys out.

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