# Filter shipments ```http POST https://secure.yoprint.com/v1/api/store/{team_slug}/shipment/filter ``` - API version: v1 - Operation ID: `v1_public_shipment_filter` - Section: Shipping › [Shipments](https://developer.yoprint.com/reference/shipments.md) - Web page: https://developer.yoprint.com/reference/shipments/v1-shipment-filter/ - Authentication: `Authorization: Bearer YOUR_API_KEY` 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_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`. ## Request body Content type `application/json`, optional. Fields: - `filters` (array of objects, optional): Conditions, all of which must match. Omit for no filter. At least 1 item. - Each item: - `key` (string, required): 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"`. - `operator` (string, required): 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"`. - `value` (string | number | boolean | array, required): What to compare with: text, a number of days, true or false, or an array of hash ids or options, by kind of key. - `page` (integer, optional): The page to read. Default `1`. Minimum 1. - `sort` (array of objects, optional): Sort keys, applied in order. Without `sort` the order is not guaranteed. - Each item: - `direction` (string, required): One of: `"asc"`, `"desc"`. - `key` (string, required): 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"`. ### Example request ```bash curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/shipment/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": "ready_to_ship", "operator": "eq", "value": true }, { "key": "status_type", "operator": "nin", "value": [ "end" ] } ], "page": 1, "sort": [ { "direction": "asc", "key": "customer_due_date" } ] }' ``` ## Response `200` Successful response. Fields: - `data` (array of objects, required) - Each item: - `customer` (object, optional) - `name` (string | null, optional) - `customer_due_date` (string (date-time) | null, optional): The order's customer due date. ISO 8601 with offset, or null. - `customer_id` (string | null, optional): The customer. - `has_third_party_fulfilled_items` (boolean, optional) - `id` (string, optional): The shipment. - `order_id` (string, optional): The order. - `order_object_type` (string | null, optional) - `order_quote` (boolean, optional) - `order_scoped_id` (string | null, optional) - `packed_by` (string | null, optional): Who packed it. - `pdf` (array of objects, optional): The packing slip and the shipment label in Letter, 4" x 6" and 1" x 2-1/8" sizes (`is_custom` absent), then one entry per enabled custom shipment PDF template (`label`, `type`, `description`, `url`, the `show_in_*` flags, `is_custom: true`). - Each item: - `description` (string, optional) - `is_custom` (boolean, optional): True on custom template entries. - `label` (string, optional) - `object_type` (string, optional) - `url` (string, optional): A download link with its own access token. - `ready_to_ship` (boolean, optional) - `scoped_id` (string, optional): The shipment number, here without the `SHIP-` prefix. - `ship_due_date` (string (date-time) | null, optional): The order's ship-by date. ISO 8601 with offset, or null. - `shipment_estimates` (array of objects, optional) - Each item: - `created_at` (string (date-time), optional) - `frontend_data` (object | array, optional): What you sent as `frontend_data`; an empty list `[]` when you sent none. - `frontend_data_version` (any, optional): What you sent, or null. - `goshippo_selected_rate_id` (string | null, optional): The rate chosen when it was saved. - `goshippo_shipment_id` (string | null, optional): The Shippo shipment. - `id` (string, optional): The estimate. - `order_id` (string, optional): The order. - `order_object_type` (string | null, optional) - `order_quote` (boolean, optional) - `order_scoped_id` (string | null, optional) - `shipment_id` (string, optional): The shipment. - `shipment_scoped_id` (string | null, optional) - `shippo_address_from` (object, optional) - `shippo_address_to` (object, optional) - `shippo_carrier_accounts` (array of strings, optional) - `shippo_extra` (any, optional): The label options, or null. - `shippo_object_id` (string | null, optional) - `shippo_parcels` (array of objects, optional) - `shippo_rates` (array of objects, optional): Every rate of that Shippo shipment, as saved (`amount` is a decimal string). - Each item: - `amount` (string, optional) - `amount_local` (string, optional) - `arrives_by` (string | null, optional) - `attributes` (array of strings, optional): Shippo's tags, for example `CHEAPEST`. - `carrier_account` (string, optional) - `currency` (string, optional) - `currency_local` (string, optional) - `duration_terms` (string | null, optional) - `estimated_days` (integer | null, optional) - `included_insurance_price` (string | null, optional) - `messages` (array of objects, optional) - `object_created` (string, optional) - `object_id` (string, optional): The rate id. Send it as `rate_id` to buy this label. - `object_updated` (string, optional) - `provider` (string, optional) - `provider_image_200` (string, optional) - `provider_image_75` (string, optional): A URL of the carrier logo. - `servicelevel` (object, optional): Exactly these four keys; null when Shippo sends no service level. - `extended_token` (string, optional) - `name` (string, optional) - `terms` (string, optional) - `token` (string, optional) - `shipment` (string, optional): The Shippo shipment this rate belongs to. - `shippo_shipment_date` (string | null, optional) - `shippo_status` (string | null, optional) - `type` (string, optional) - `shipment_packages` (array of objects, optional) - Each item: - `charges` (integer | number | string | null, optional): 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](/concepts/money-and-quantities/). - `created_at` (string (date-time), optional) - `from_address` (any, optional): The address record behind `from_address_id`, or null when it is not set. - `from_address_id` (string | null, optional): Older packages only: the ship-from address record; null otherwise. - `goshippo` (object, optional): Shippo labels only: the Shippo details (shipment, rate, carrier, addresses, parcels). - `address_from` (any, optional): The ship-from address sent to Shippo. - `address_return` (any, optional): The return address sent to Shippo. - `address_to` (any, optional): The ship-to address sent to Shippo. - `carrier_id` (string | null, optional): The Shippo carrier account. - `parcel_id` (string | null, optional): The Shippo parcel. - `parcels` (any, optional): The parcels of the Shippo shipment. - `provider` (string | null, optional) - `provider_image_200` (string | null, optional) - `provider_image_75` (string | null, optional) - `provider_tracking_number` (string | null, optional) - `rate_id` (string | null, optional): The Shippo rate bought. - `shipment_data` (any, optional): The Shippo shipment the rate came from. - `shipment_id` (string | null, optional): The Shippo shipment. - `height` (number | string | null, optional): Parcel size and weight as stored, in `length_unit` and `weight_unit`. Null for external labels. - `id` (string, optional): The package. - `is_master` (boolean, optional): The first package of a label (the others have `parent_id`). - `length` (number | string | null, optional) - `length_unit` (string | null, optional): Shippo labels only, upper case. - `order_external_ids` (array of objects, optional): The order's links to external systems. - `order_external_type` (string | null, optional): `shopify` when the order came from Shopify. - `order_id` (string, optional): The order. - `order_object_type` (string | null, optional) - `order_quote` (boolean, optional) - `order_scoped_id` (string | null, optional) - `parent_id` (string | null, optional): The master package, for the other parcels of a multi-parcel label. - `pdf` (array of objects, optional): Not on external labels: the label file. `label` and `description` are fixed texts that always say 4 x 6, whatever your label size setting. - Each item: - `description` (string, optional) - `label` (string, optional) - `url` (string, optional): For a Shippo label, Shippo's signed link to the label file: don't publish it. - `provider_name` (string | null, optional): The carrier. - `provider_saturday_delivery` (boolean, optional): Shippo labels only (absent on external labels); always false today. - `provider_service_code` (string | null, optional): For external labels, `ups`, `fedex` or `other`. For Shippo labels it may be null: read the service from `provider_service_name`. - `provider_service_name` (string | null, optional) - `provider_shipment_id` (string | null, optional): The Shippo transaction id (Shippo labels). - `provider_tracking_number` (string | null, optional) - `shipment_external_type` (string | null, optional): `shopify` when the shipment is linked to Shopify. - `shipment_has_third_party_fulfilled_items` (boolean, optional) - `shipment_id` (string, optional): The shipment. - `shipment_scoped_id` (string, optional) - `shipment_shopify_sync` (any, optional): Shopify sync state of the shipment. - `status` (string, optional): One of: `"pending"`, `"ready-to-ship"`, `"shipped"`, `"delivered"`. - `to_address` (any, optional): The address record behind `to_address_id`, or null when it is not set. - `to_address_id` (string | null, optional): Older packages only: the ship-to address record; null otherwise. - `type` (string, optional): `goshippo` a label bought through Shippo; `external_label` a label recorded from elsewhere. One of: `"goshippo"`, `"external_label"`, `"single_label"`. - `weight` (number | string | null, optional) - `weight_unit` (string | null, optional): Shippo labels only, upper case. - `width` (number | string | null, optional) - `shipping_address` (object | null, optional): An address. - `address1` (string | null, optional) - `address2` (string | null, optional) - `city` (string | null, optional) - `country` (string | null, optional) - `country_code` (string | null, optional) - `id` (string, optional): The address. - `label` (string | null, optional) - `postcode` (string | null, optional) - `state` (string | null, optional) - `state_code` (string | null, optional) - `shipping_type_id` (string | null, optional): The shipping type. - `shipping_type_name` (string | null, optional) - `status_id` (string | null, optional): The shipment status. - `status` (integer, required) - `success` (boolean, required) - `pagination` (object, optional) - `count` (integer, required) - `currentPage` (integer, required) - `links` (object | array of any, required): Links to the neighbouring pages: `previous` and `next`, each present only when that page exists. An empty list, `[]`, when there is only one page. - `next` (string (uri), optional): The next page. - `previous` (string (uri), optional): The previous page. - `perPage` (integer, required) - `total` (integer, required) - `totalPages` (integer, required) Example response: ```json { "data": [ { "customer": { "name": "Northwind Apparel" }, "customer_due_date": "2026-11-10T00:00:00+00:00", "customer_id": "ifAHmADekGZ6id", "has_third_party_fulfilled_items": false, "id": "MQyJUnd3oty75h", "order_id": "sFbALVSYD55eXe", "order_object_type": "sales_order", "order_quote": false, "order_scoped_id": "SO1001", "packed_by": null, "pdf": [ { "description": "Packing slip with white labeling", "label": "Packing Slip", "object_type": "shipment", "url": "https://example.com/pdf/packing-slip.pdf" } ], "ready_to_ship": false, "scoped_id": "12", "ship_due_date": "2026-11-08T00:00:00+00:00", "shipment_estimates": [ { "created_at": "2026-11-03T15:00:00+00:00", "frontend_data": [], "frontend_data_version": null, "goshippo_selected_rate_id": "rate_0001", "goshippo_shipment_id": "shipment_0001", "id": "tVjoZLKlSwZFF5", "order_id": "sFbALVSYD55eXe", "order_object_type": "sales_order", "order_quote": false, "order_scoped_id": "SO1001", "shipment_id": "MQyJUnd3oty75h", "shipment_scoped_id": "SHIP-12", "shippo_address_from": { "city": "Austin", "company": "", "country": "US", "email": "", "name": "Northwind Apparel", "phone": "+1 201 555 0123", "state": "TX", "street1": "100 Example Street", "street2": "", "zip": "78701" }, "shippo_address_to": { "city": "Denver", "company": "", "country": "US", "email": "alex@example.com", "name": "Alex Rivera", "phone": "", "state": "CO", "street1": "100 Example Street", "street2": "", "zip": "80202" }, "shippo_carrier_accounts": [], "shippo_extra": null, "shippo_object_id": "shipment_0001", "shippo_parcels": [ { "distance_unit": "in", "height": "4", "length": "12", "mass_unit": "lb", "weight": "2", "width": "10" } ], "shippo_rates": [ { "amount": "12.40", "amount_local": "12.40", "arrives_by": null, "attributes": [ "CHEAPEST" ], "carrier_account": "carrier_0001", "currency": "USD", "currency_local": "USD", "duration_terms": "Delivery in 2 to 5 days.", "estimated_days": 3, "included_insurance_price": null, "messages": [], "object_created": "2026-11-03T15:00:00Z", "object_id": "rate_0001", "object_updated": "2026-11-03T15:00:00Z", "provider": "USPS", "provider_image_200": "https://example.com/usps_200.png", "provider_image_75": "https://example.com/usps_75.png", "servicelevel": { "extended_token": "usps_ground_advantage", "name": "Ground Advantage", "terms": "", "token": "usps_ground_advantage" }, "shipment": "shipment_0001" } ], "shippo_shipment_date": "2026-11-03T15:00:00Z", "shippo_status": "SUCCESS", "type": "integration_shippo" } ], "shipment_packages": [ { "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" } ], "shipping_address": { "address1": "100 Example Street", "address2": null, "city": "Austin", "country": "United States", "country_code": "US", "id": "117KfwwfreX15N", "label": "Main office", "postcode": "78701", "state": "Texas", "state_code": "TX" }, "shipping_type_id": "6OTWtTOpYcBz8q", "shipping_type_name": "USPS Ground Advantage", "status_id": "AvY6ZbnrTJqpUI" } ], "pagination": { "count": 1, "currentPage": 1, "links": [], "perPage": 50, "total": 1, "totalPages": 1 }, "status": 200, "success": true } ``` ## Errors - `401` The API key is missing or wrong (`unauthenticated`). - `403` You 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`. - `404` Not 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. - `422` The 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. - `500` A 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. ## Related - [Get a shipment](https://developer.yoprint.com/reference/shipments/v2-shipment-show.md): `GET /v2/api/store/{team_slug}/v2/shipment/{unique_key}` - [List shipment statuses](https://developer.yoprint.com/reference/statuses/v1-status-list-shipment.md): `GET /v1/api/store/{team_slug}/setting/status/shipment` - [Download packing slips (PDF)](https://developer.yoprint.com/reference/shipments/v1-shipment-export-packing-slip.md): `POST /v1/api/store/{team_slug}/shipment/export_packing_slip`