Filter packages

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

v1Operation ID v1_public_shipment_package_filter

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

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`	Options	`in` or `nin`, with an array of the listed values.	The package status: `pending`, `ready-to-ship`, `shipped`, `delivered`.
`shipment_status_id`	Hash ids	`in` or `nin`, with an array of hash ids.	The status of the package's shipment.
`created_at`	Date	`eq`, `gte` or `lte`, with a whole number of days counted from now (UTC). See below.	When the package was created.

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", "shipment_status_id", "created_at"
- 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", "shipment_id", "status", "provider_service_name", "created_at"

Response

200Successful response.

dataarray of objectsrequired
Fields of each item (36)
- chargesinteger | number | string | null
  The label cost. For a multi-parcel label every package repeats the rate's full amount: read the master's value and don't add packages up. Null for external labels. 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.
- created_atstring (date-time)
- from_addressany
  The address record behind from_address_id, or null when it is not set.
- from_address_idstring | null
  Older packages only: the ship-from address record; null otherwise.
- goshippoobject
  Shippo labels only: the Shippo details (shipment, rate, carrier, addresses, parcels).
  Child fields (13)
  - address_fromany
    The ship-from address sent to Shippo.
  - address_returnany
    The return address sent to Shippo.
  - address_toany
    The ship-to address sent to Shippo.
  - carrier_idstring | null
    The Shippo carrier account.
  - parcel_idstring | null
    The Shippo parcel.
  - parcelsany
    The parcels of the Shippo shipment.
  - providerstring | null
  - provider_image_200string | null
  - provider_image_75string | null
  - provider_tracking_numberstring | null
  - rate_idstring | null
    The Shippo rate bought.
  - shipment_dataany
    The Shippo shipment the rate came from.
  - shipment_idstring | null
    The Shippo shipment.
- heightnumber | string | null
  Parcel size and weight as stored, in length_unit and weight_unit. Null for external labels.
- idstring
  The package.
- is_masterboolean
  The first package of a label (the others have parent_id).
- lengthnumber | string | null
- length_unitstring | null
  Shippo labels only, upper case.
- order_external_idsarray of objects
  The order's links to external systems.
- order_external_typestring | null
  shopify when the order came from Shopify.
- order_idstring
  The order.
- order_object_typestring | null
- order_quoteboolean
- order_scoped_idstring | null
- parent_idstring | null
  The master package, for the other parcels of a multi-parcel label.
- pdfarray of objects
  Not on external labels: the label file. label and description are fixed texts that always say 4 x 6, whatever your label size setting.
  Fields of each item (3)
  - descriptionstring
  - labelstring
  - urlstring
    For a Shippo label, Shippo's signed link to the label file: don't publish it.
- provider_namestring | null
  The carrier.
- provider_saturday_deliveryboolean
  Shippo labels only (absent on external labels); always false today.
- provider_service_codestring | null
  For external labels, ups, fedex or other. For Shippo labels it may be null: read the service from provider_service_name.
- provider_service_namestring | null
- provider_shipment_idstring | null
  The Shippo transaction id (Shippo labels).
- provider_tracking_numberstring | null
- shipment_external_typestring | null
  shopify when the shipment is linked to Shopify.
- shipment_has_third_party_fulfilled_itemsboolean
- shipment_idstring
  The shipment.
- shipment_scoped_idstring
- shipment_shopify_syncany
  Shopify sync state of the shipment.
- statusstring
  - One of: "pending", "ready-to-ship", "shipped", "delivered"
- to_addressany
  The address record behind to_address_id, or null when it is not set.
- to_address_idstring | null
  Older packages only: the ship-to address record; null otherwise.
- typestring
  goshippo a label bought through Shippo; external_label a label recorded from elsewhere.
  - One of: "goshippo", "external_label", "single_label"
- weightnumber | string | null
- weight_unitstring | null
  Shippo labels only, upper case.
- widthnumber | string | null
statusintegerrequired
successbooleanrequired
paginationobject
Child fields (6)
- countintegerrequired
- currentPageintegerrequired
- linksobject | array of anyrequired
  Links to the neighbouring pages: previous and next, each present only when that page exists. An empty list, [], when there is only one page.
  Child fields (2)
  - nextstring (uri)
    The next page.
  - previousstring (uri)
    The previous page.
- 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.
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 breaks the table.
Fix
Check each filter against the table.

GETList the packages of a shipment/v2/api/store/{team_slug}/v2/shipment/{hash_id}/packages
PATCHGet live tracking for a package/v1/api/store/{team_slug}/shipment_package/{id}/track

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/shipment_package/filter' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "filters": [      {        "key": "status",        "operator": "in",        "value": [          "pending",          "ready-to-ship"        ]      }    ],    "page": 1,    "sort": [      {        "direction": "desc",        "key": "created_at"      }    ]  }'

Example response 200

{
  "data": [
    {
      "charges": 12400,
      "created_at": "2026-11-03T15:00:00+00:00",
      "goshippo": {
        "parcels": [
          {
            "distance_unit": "in",
            "height": "4",
            "length": "12",
            "mass_unit": "lb",
            "weight": "2",
            "width": "10"
          }
        ],
        "provider": "USPS",
        "rate_id": "rate_0001"
      },
      "height": "4",
      "id": "o6foWpSAayc79D",
      "is_master": true,
      "length": "12",
      "length_unit": "IN",
      "order_id": "sFbALVSYD55eXe",
      "order_object_type": "sales_order",
      "order_quote": false,
      "order_scoped_id": "SO1001",
      "parent_id": null,
      "pdf": [
        {
          "description": "Postage label individually to be printed 4\" x 6\" label",
          "label": "Postage Label (4 in x 6 in label)",
          "url": "https://example.com/labels/o6foWpSAayc79D.pdf"
        }
      ],
      "provider_name": "USPS",
      "provider_saturday_delivery": false,
      "provider_service_code": null,
      "provider_service_name": "Ground Advantage",
      "provider_shipment_id": "transaction_0001",
      "provider_tracking_number": "9400100000000000000000",
      "shipment_has_third_party_fulfilled_items": false,
      "shipment_id": "MQyJUnd3oty75h",
      "shipment_scoped_id": "SHIP-12",
      "status": "pending",
      "type": "goshippo",
      "weight": "2",
      "weight_unit": "LB",
      "width": "10"
    }
  ],
  "pagination": {
    "count": 1,
    "currentPage": 1,
    "links": [],
    "perPage": 50,
    "total": 1,
    "totalPages": 1
  },
  "status": 200,
  "success": true
}

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 spec Support: support@yoprint.com yoprint.com