openapi: 3.2.0 info: description: The byrd APIs for managing products, inbound deliveries, shipments and returns. contact: email: info@getbyrd.com name: General company contact url: https://getbyrd.com/kontakt/ license: name: Copyright byrd technologies GmbH termsOfService: https://getbyrd.com/agb/ version: '20260924' title: byrd Shipments API servers: - description: Production server url: https://api.getbyrd.com/ security: - tokenAuth: [] tags: - name: Shipments description: 'Orders shipped to your customers: create and release them, follow their units and picks, and handle their returns.' paths: /v2/returns: get: operationId: returnshipmentlistapi_get responses: '200': content: application/vnd.byrd.customer+json: schema: allOf: - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ReturnShipment' - $ref: '#/components/schemas/PaginationFields' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns the courier and customer returns of your shipments, newest first unless you sort otherwise, filtered by the query parameters. See the Listing returns guide for the meaning of `returnType`, `reason` and the item `condition`.' x-byrd-roles: - admin - warehouse - customer - operator - customer_support - warehouse_support - service parameters: - in: query name: shipment_id description: Only include returns of the shipment with this ID (UUID). schema: type: string format: uuid required: false - in: query name: status description: 'Only include returns in one of these statuses: `announced`, `confirmed`, `cancelled`. Cancelled returns are never shown to customer accounts.' schema: type: array items: type: string enum: - announced - confirmed - cancelled required: false explode: false style: form - in: query name: date_field description: 'Date field `date_from` and `date_to` apply to. Defaults to `createdAt`. - `createdAt`: when the return was created - `updatedAt`: when the return was last changed - `announcedAt`: when the return was announced - `postedAt`: when the parcel was handed to the carrier - `deliveredAt`: when the return arrived at the warehouse - `processedAt`: when the warehouse checked the items' schema: type: string default: createdAt enum: - updatedAt - postedAt - deliveredAt - processedAt - announcedAt - createdAt required: false - in: query name: date_from description: Only include returns whose `date_field` is at or after this time (ISO 8601, UTC), e.g. `2023-03-23T16:00:03Z`. schema: type: string format: date-time required: false - in: query name: date_to description: Only include returns whose `date_field` is before this time (ISO 8601, UTC), e.g. `2023-03-23T16:00:03Z`. Must be after `date_from`. schema: type: string format: date-time required: false - in: query name: parcel_id description: Only include returns of the shipment with this parcel ID, or of the shipment unit with this parcel ID. schema: type: string required: false - in: query name: reason description: Only include returns with one of these reasons. See `reason` in the response for the values. schema: type: array items: type: string enum: - bad-address - bad-product - country - no-pickup - rec-unknown - refused-delivery - unwanted - customer required: false explode: false style: form - in: query name: carrier description: Only include returns shipped with this carrier, as a carrier identifier such as `dhl_de`. schema: type: string required: false - in: query name: carrier_tracking_number description: Only include returns with this carrier tracking number. schema: type: string required: false - in: query name: user_ids description: Only include returns of shipments owned by these users (UUIDs). As a customer you only get your own returns. schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: customer_name description: Only include returns whose original shipment recipient name or company contains this text (case-insensitive). schema: type: string required: false - in: query name: product_sku description: Only include returns with a received item of this SKU. schema: type: string required: false - in: query name: product_id description: Only include returns with a received item of the product with this ID (UUID). schema: type: string required: false - in: query name: type description: 'Only include returns of this type: `courier` or `customer`.' schema: type: string enum: - courier - customer required: false - in: query name: manual_search_required description: Only include returns for which the warehouse had (`true`) or had not (`false`) to search manually for the original shipment. schema: type: boolean required: false - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/SortBy' - $ref: '#/components/parameters/SortOrder' - $ref: '#/components/parameters/Query' - $ref: '#/components/parameters/Fields' summary: List returns /v2/returns/{return_id}: get: operationId: returnshipmentdetailapi_get responses: '200': content: application/vnd.byrd.customer+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ReturnShipment' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns one of your returns with its original shipment and the announced and received items.' x-byrd-roles: - admin - warehouse - customer - operator - customer_support - warehouse_support - service parameters: - name: return_id in: path required: true schema: type: string description: ID of the return (UUID). summary: Get a return /v3/picks: get: operationId: picklistapiv3_get responses: '200': content: application/json: schema: allOf: - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Pick' - $ref: '#/components/schemas/MinimalPaginationFields' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns the picks of your shipments: which product the warehouse picks, how many, from which storage and lot. Filter by `shipment_ids` to get the picks of specific shipments.' x-byrd-roles: - customer - service - admin - operator - warehouse parameters: - in: query name: shipment_ids description: Only return picks of these shipments, by ID (comma-separated). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: include_deleted_storages description: Whether to include picks from storages that were deleted since. Defaults to `false`. schema: type: boolean required: false - in: query name: only description: Comma-separated dotted paths of the fields to return, for example `id,container_code,product.barcode`. schema: type: array items: type: string required: false explode: false style: form - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/SortBy' - $ref: '#/components/parameters/SortOrder' summary: List picks /v3/returns/announce: post: operationId: returnshipmentannouncedapiv3_post responses: '201': content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ReturnShipmentAnnounced' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Creates a customer return in the `announced` state for items of one of your shipments. The return label is generated asynchronously and emailed to `send_documents_to_email` a few seconds later, unless `send_email` is `false`, so `documents` is usually empty in the response. See Announcing returns.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ReturnShipmentAnnouncedInput' x-byrd-roles: - admin - service - customer summary: Announce a return /v3/returns/{return_id}/documents: post: operationId: returnshipmentdocumentsapiv3_post responses: '202': content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ReturnShipmentAnnounced' description: Success response to a valid request '400': $ref: '#/components/responses/Error' description: '`send_documents_to_email` is missing or not a valid email, or is sent although `send_email` is `false`.' content: application/json: schema: type: object properties: code: type: string enum: - Request.InvalidSchema '403': $ref: '#/components/responses/Error' '404': description: No return exists for the given id. content: application/json: schema: type: object properties: code: type: string enum: - Warehouse.ReturnShipments.Create.NotFound '412': description: The return cannot have documents regenerated. content: application/json: schema: type: object properties: code: type: string enum: - Warehouse.ReturnShipmentDocuments.GenerateDocuments.AlreadyPosted - Warehouse.ReturnShipmentDocuments.GenerateDocuments.InvalidStatus '422': description: The return belongs to another customer. content: application/json: schema: type: object properties: code: type: string enum: - Warehouse.ReturnShipments.Create.Unauthorized tags: - Shipments description: 'Generates a new return label for an announced return that has not been posted yet and emails it to `send_documents_to_email` (unless `send_email` is `false`), for example because the QR code on the earlier label stopped working (about two weeks after it was created). The address is used for this label only and does not replace the return''s own `send_documents_to_email`. The documents are generated asynchronously.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ReturnShipmentRegenerateDocumentsInput' x-byrd-roles: - admin - service - customer parameters: - name: return_id in: path required: true schema: type: string description: ID of the return (UUID). summary: Regenerate the documents of a return /v3/shipments: get: operationId: shipmentlistapiv3_get responses: '200': content: application/vnd.byrd.customer+json: schema: allOf: - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ShipmentList' - $ref: '#/components/schemas/MinimalPaginationFields' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns your shipments that match the filters, newest first by default. To keep tracking data in sync, list the shipments sent in a period with `sent_date_from` and `sent_date_to`; add `include_unit_items` to get the items and serial numbers of each parcel.' x-byrd-roles: - customer - service - admin - operator - warehouse parameters: - in: query name: id description: Only the shipment with this ID (UUID). schema: type: string format: uuid required: false - in: query name: ids description: Only shipments with any of these IDs (UUIDs). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: product_id description: Only shipments containing the product with this ID (UUID). schema: type: string format: uuid required: false - in: query name: product_ids description: Only shipments containing any of these products (UUIDs). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: parcel_id description: Only shipments with a parcel whose parcel ID contains this text, ignoring case; also finds deleted parcels. schema: type: string required: false - in: query name: unit_id description: Only shipments with the parcel (unit) with this ID (UUID); also finds deleted parcels. schema: type: string format: uuid required: false - in: query name: byrd_id description: Only shipments whose byrd ID contains this text, ignoring case; 3 to 10 characters. schema: type: string minLength: 3 maxLength: 10 required: false - in: query name: tracking_number description: Only shipments with a parcel that has this carrier tracking number. schema: type: string required: false - in: query name: postal_code description: Only shipments to this destination postal code. schema: type: string required: false - in: query name: storage_zone_ids description: 'For warehouse use: only shipments picked entirely from these storage zones (UUIDs); `null` selects shipments with a pick from storage outside any zone. Needs a `status` filter with only allocated shipments.' schema: type: - array - 'null' items: type: - string - 'null' format: uuid required: false explode: false style: form - in: query name: warehouse_user_id description: 'For warehouse use: only shipments assigned to this warehouse worker (UUID).' schema: type: string format: uuid required: false - in: query name: warehouse_ids description: Only shipments fulfilled by any of these warehouses (UUIDs). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: warehouse_id description: Only shipments fulfilled by this warehouse (UUID). schema: type: string format: uuid required: false - in: query name: carrier description: Only shipments with a parcel sent with any of these carriers, by carrier slug; see the list of carriers. schema: type: array items: type: string required: false explode: false style: form - in: query name: predicted_carrier description: Only shipments whose carrier, as predicted when the shipment was released, is any of these carrier slugs; unlike `carrier`, this also finds shipments that have no parcel yet. schema: type: array items: type: string required: false explode: false style: form - in: query name: service description: Only shipments sent with this `service`. schema: type: string enum: - economy - standard - express - pickup - pickup_point required: false - in: query name: date_field description: 'Date of the shipment that `date_from` and `date_to` filter on; defaults to `created_at`. - `created_at`: created - `updated_at`: last changed - `released_at`: last release attempt - `picked_at`: picking completed - `packaged_date`: packed - `sent_date`: handed over to the carrier - `delivery_date`: delivered - `returned_date`: returned - `warehouse_sla_accepted_by`, `customer_sla_accepted_by`: deadline for the carrier to accept the shipment' schema: type: string default: created_at enum: - created_at - updated_at - released_at - picked_at - packaged_date - sent_date - delivery_date - returned_date - warehouse_sla_accepted_by - customer_sla_accepted_by required: false - in: query name: date_from description: Only shipments whose `date_field` is at or after this time (ISO 8601, inclusive). schema: type: string format: date-time required: false - in: query name: date_to description: Only shipments whose `date_field` is before this time (ISO 8601, exclusive); must be after `date_from`. For one calendar day, pass the following day, not the same day as `date_from`. schema: type: string format: date-time required: false - in: query name: sent_date_from description: Only shipments sent at or after this time (ISO 8601). schema: type: string format: date-time required: false - in: query name: sent_date_to description: Only shipments sent at or before this time (ISO 8601); must not be before `sent_date_from`. schema: type: string format: date-time required: false - in: query name: sent_date description: Only shipments sent on this day (ISO 8601 date, UTC). Cannot be combined with `date_from`, `date_to`, `sent_date_from` or `sent_date_to`. schema: type: string format: date required: false - in: query name: min_age_days description: Only shipments released at least this many whole days ago; at least 1. schema: type: integer minimum: 1 required: false - in: query name: failed_release description: When `true`, only shipments whose last release attempt failed. schema: type: boolean required: false - in: query name: awaiting_release description: When `true`, only shipments waiting to be released to a warehouse. schema: type: boolean required: false - in: query name: awaiting_allocation description: When `true`, only shipments waiting for their stock to be allocated in the warehouse. schema: type: boolean required: false - in: query name: label_required description: When `true`, only packed shipments still waiting for a shipping label (sub-status `label_required` or `label_error`); when `false`, all other shipments. schema: type: boolean required: false - in: query name: failed_address_validation description: When `true`, only shipments held because their address validation failed; when `false`, only shipments without an address validation error. schema: type: boolean required: false - in: query name: failed_allocation description: When `true`, only shipments whose stock could not be allocated in the warehouse. schema: type: boolean required: false - in: query name: failed_packaging description: When `true`, only shipments with a parcel whose shipping label could not be created (sub-status `label_error`). schema: type: boolean required: false - in: query name: error_resolved description: When `true`, only shipments with a parcel whose label error was resolved and that waits to be packed again (sub-status `error_resolved`). schema: type: boolean required: false - in: query name: container_code description: 'For warehouse use: only shipments kept in the warehouse container with this code before packing.' schema: type: string required: false - in: query name: destination_email description: Only shipments to this recipient email address, ignoring case. schema: type: string required: false - in: query name: is_b2b description: When `true`, only B2B shipments; when `false`, only B2C shipments. schema: type: boolean required: false - in: query name: processing_standard description: Only B2B shipments that use any of these B2B templates, by template key. schema: type: array items: type: string required: false explode: false style: form - in: query name: is_cod description: When `true`, only cash on delivery shipments; when `false`, only other shipments. schema: type: boolean required: false - in: query name: status description: Only shipments in any of these statuses; see `status` on the shipment for the values. schema: type: array items: type: string enum: - new - releasing - released - picking - packaging - packaged - sent - delivered - returning - returned - deleted required: false explode: false style: form - in: query name: sub_status description: Only shipments in any of these sub-statuses; needs a `status` filter. With more than one sub-status, send exactly one `status`, and each combination has to be valid. schema: type: array items: type: string enum: - validating_address - address_invalid - recalled - reserved - allocating - allocated - assigned - inbounding - inbound_error - label_error - error_resolved - autobag_failed - fba_details_required - fba_box_label_required - fba_pallet_label_required - label_required - label_created - label_uploaded - pickup_details_required - pickup_details_uploaded - manual_outbound - waiting_for_pickup - claim_reported - pick_up - in_transit - out_for_delivery - at_pickup_point - delayed - failed_delivery required: false explode: false style: form - in: query name: exclude_sub_status description: Leaves out shipments in any of these sub-statuses; shipments without a sub-status are kept. schema: type: array items: type: string enum: - validating_address - address_invalid - recalled - reserved - allocating - allocated - assigned - inbounding - inbound_error - label_error - error_resolved - autobag_failed - fba_details_required - fba_box_label_required - fba_pallet_label_required - label_required - label_created - label_uploaded - pickup_details_required - pickup_details_uploaded - manual_outbound - waiting_for_pickup - claim_reported - pick_up - in_transit - out_for_delivery - at_pickup_point - delayed - failed_delivery required: false explode: false style: form - in: query name: missing_documents description: When `true`, only shipments blocked because documents they need are missing. schema: type: boolean required: false - in: query name: priority_range description: 'For warehouse use: only shipments whose picking priority is within this range, given as `min,max` from 0 to 50; needs a `status` filter with only released statuses.' schema: type: array minItems: 2 items: type: integer minimum: 0 maximum: 50 required: false explode: false style: form - in: query name: priority description: 'For warehouse use: only shipments with exactly this picking priority, from 0 to 50; needs a `status` filter with only released statuses.' schema: type: integer minimum: 0 maximum: 50 required: false - in: query name: destination_countries description: Only shipments to any of these countries (ISO 3166-1 alpha-2), for example `DE,AT`. schema: type: array items: type: string pattern: ^[A-Z]{2}$ required: false explode: false style: form - in: query name: total_products description: Only shipments with exactly this number of different products, not counting bundles themselves; at least 1. schema: type: integer minimum: 1 required: false - in: query name: total_items description: Only shipments with exactly this total number of physical items to pick, counting the contents of bundles; at least 1. schema: type: integer minimum: 1 required: false - in: query name: total_picks description: 'For warehouse use: only shipments with exactly this number of items to pick, counting a packaging unit as one; needs a `status` filter with only allocated shipments.' schema: type: integer minimum: 1 required: false - in: query name: product_quantities description: 'For warehouse use: only shipments with exactly these contents, given as `product_id:quantity` pairs; needs a `status` filter with only allocated shipments.' schema: type: array items: type: string pattern: ^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}:[1-9]\d*$ required: false explode: false style: form - in: query name: lot_ids description: 'For warehouse use: only shipments whose picks come from exactly this set of lots (UUIDs); an empty list selects shipments without lot-tracked picks. Needs a `status` filter with only allocated shipments.' schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: has_identical_orders description: 'For warehouse use: when `true`, only shipments with exactly the same contents as at least one other shipment in the result; needs a `status` filter with only allocated shipments.' schema: type: boolean required: false - in: query name: exclude description: 'Parts to leave out of the response, which makes it faster: `items`, `units`.' schema: type: array items: type: string enum: - items - units required: false explode: false style: form - in: query name: only description: Fields to return, as comma-separated dotted paths of response field names, for example `id,status,units.items`; all fields when not sent. schema: type: array items: type: string required: false explode: false style: form - in: query name: label_error_status description: 'Only shipments with a label error in this state. - `blocked`: not resolved yet, like `failed_packaging` - `resolved`: resolved, like `error_resolved`' schema: type: string enum: - resolved - blocked required: false - in: query name: v3_packaging description: Only shipments packed (`true`) or not packed (`false`) with the v3 packing process. schema: type: boolean required: false - in: query name: order_number description: Only shipments with exactly this `shop.order_number`. schema: type: string required: false - in: query name: marketplace_order_number description: Only shipments with exactly this `shop.marketplace_order_number`. schema: type: string required: false - in: query name: marketplace description: Only shipments with this `shop.marketplace`, for example `amazon`. schema: type: string required: false - in: query name: products_barcodes_only description: 'For warehouse use: when `true`, only shipments containing products that have a barcode.' schema: type: boolean required: false - in: query name: include_unit_items description: Whether to include the items packed in each parcel (`units.items`), for example to read their serial numbers; defaults to `false`. Cannot be combined with excluding `units`. schema: type: boolean default: false required: false - in: query name: slam_compatible description: 'For warehouse use: when `true`, only shipments that can be packed on the automated labelling line; needs a `status` filter with only released statuses.' schema: type: boolean required: false - in: query name: autobag_compatible description: 'For warehouse use: only shipments that can (`true`) or cannot (`false`) be packed with the automatic bagging machine; needs a `status` filter with only released statuses.' schema: type: boolean required: false - in: query name: returnable description: 'When `true`, only shipments that can still be returned: `sent`, `delivered`, `returning` or `returned`, and sent within the last 180 days.' schema: type: boolean required: false - in: query name: customer_action_required description: When `true`, only shipments with an open action you need to take to unblock them. schema: type: boolean required: false - in: query name: customs_required description: Only shipments that need (`true`) or do not need (`false`) a customs declaration because they cross a customs border; known once a shipment is released. schema: type: boolean required: false - in: query name: has_shipping_label description: Only shipments that have (`true`) or do not have (`false`) a shipping label document. schema: type: boolean required: false - in: query name: filter_group_id description: 'For warehouse use: ID of a saved set of filters to apply instead of individual filters (UUID).' schema: type: string format: uuid required: false - in: query name: only_ground_level description: 'Deprecated. For warehouse use: when `true`, only shipments picked entirely from storage at ground level; when `false`, only shipments with at least one pick from a higher level.' schema: type: boolean required: false - in: query name: is_forklift_required description: 'For warehouse use: only shipments whose picking needs (`true`) or does not need (`false`) a forklift.' schema: type: boolean required: false - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/SortBy' - $ref: '#/components/parameters/SortOrder' - $ref: '#/components/parameters/Query' - $ref: '#/components/parameters/Fields' summary: List shipments post: operationId: shipmentlistapiv3_post responses: '201': content: application/vnd.byrd.customer+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Shipment' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Creates a B2C shipment, or a B2B shipment when `b2b_config` is sent. The shipment starts in status `new` and is released to a warehouse automatically when `options.auto_release` is `true`. Use `validate_only` to check a request without creating the shipment.' requestBody: content: application/vnd.byrd.customer+json: schema: $ref: '#/components/schemas/ShipmentInput' x-byrd-roles: - admin - service - customer parameters: - in: query name: validate_only description: Whether to only validate the request and return the resulting shipment without saving it; defaults to `false`. schema: type: boolean default: false required: false - in: query name: ensure_unique_order_id description: Whether to reject the shipment (409) if one of your shipments that is not deleted already has the same `shop.order_id`; defaults to `false`. schema: type: boolean default: false required: false - in: query name: ensure_unique_marketplace_order_number description: Whether to reject the shipment (409) if another shipment from the same shop integration already has this `shop.marketplace_order_number`; only applies to shipments from a byrd shop integration. Defaults to `false`. schema: type: boolean default: false required: false summary: Create a shipment /v3/shipments/count: get: operationId: shipmentlistcountapiv3_get responses: '200': content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ShipmentCount' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns the number of your shipments that match the same filters as the list endpoint, up to 100000.' x-byrd-roles: - service - customer - admin - operator - warehouse parameters: - in: query name: id description: Only the shipment with this ID (UUID). schema: type: string format: uuid required: false - in: query name: ids description: Only shipments with any of these IDs (UUIDs). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: product_id description: Only shipments containing the product with this ID (UUID). schema: type: string format: uuid required: false - in: query name: product_ids description: Only shipments containing any of these products (UUIDs). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: parcel_id description: Only shipments with a parcel whose parcel ID contains this text, ignoring case; also finds deleted parcels. schema: type: string required: false - in: query name: unit_id description: Only shipments with the parcel (unit) with this ID (UUID); also finds deleted parcels. schema: type: string format: uuid required: false - in: query name: byrd_id description: Only shipments whose byrd ID contains this text, ignoring case; 3 to 10 characters. schema: type: string minLength: 3 maxLength: 10 required: false - in: query name: tracking_number description: Only shipments with a parcel that has this carrier tracking number. schema: type: string required: false - in: query name: postal_code description: Only shipments to this destination postal code. schema: type: string required: false - in: query name: storage_zone_ids description: 'For warehouse use: only shipments picked entirely from these storage zones (UUIDs); `null` selects shipments with a pick from storage outside any zone. Needs a `status` filter with only allocated shipments.' schema: type: - array - 'null' items: type: - string - 'null' format: uuid required: false explode: false style: form - in: query name: warehouse_user_id description: 'For warehouse use: only shipments assigned to this warehouse worker (UUID).' schema: type: string format: uuid required: false - in: query name: warehouse_ids description: Only shipments fulfilled by any of these warehouses (UUIDs). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: warehouse_id description: Only shipments fulfilled by this warehouse (UUID). schema: type: string format: uuid required: false - in: query name: carrier description: Only shipments with a parcel sent with any of these carriers, by carrier slug; see the list of carriers. schema: type: array items: type: string required: false explode: false style: form - in: query name: predicted_carrier description: Only shipments whose carrier, as predicted when the shipment was released, is any of these carrier slugs; unlike `carrier`, this also finds shipments that have no parcel yet. schema: type: array items: type: string required: false explode: false style: form - in: query name: service description: Only shipments sent with this `service`. schema: type: string enum: - economy - standard - express - pickup - pickup_point required: false - in: query name: date_field description: 'Date of the shipment that `date_from` and `date_to` filter on; defaults to `created_at`. - `created_at`: created - `updated_at`: last changed - `released_at`: last release attempt - `picked_at`: picking completed - `packaged_date`: packed - `sent_date`: handed over to the carrier - `delivery_date`: delivered - `returned_date`: returned - `warehouse_sla_accepted_by`, `customer_sla_accepted_by`: deadline for the carrier to accept the shipment' schema: type: string default: created_at enum: - created_at - updated_at - released_at - picked_at - packaged_date - sent_date - delivery_date - returned_date - warehouse_sla_accepted_by - customer_sla_accepted_by required: false - in: query name: date_from description: Only shipments whose `date_field` is at or after this time (ISO 8601, inclusive). schema: type: string format: date-time required: false - in: query name: date_to description: Only shipments whose `date_field` is before this time (ISO 8601, exclusive); must be after `date_from`. For one calendar day, pass the following day, not the same day as `date_from`. schema: type: string format: date-time required: false - in: query name: sent_date_from description: Only shipments sent at or after this time (ISO 8601). schema: type: string format: date-time required: false - in: query name: sent_date_to description: Only shipments sent at or before this time (ISO 8601); must not be before `sent_date_from`. schema: type: string format: date-time required: false - in: query name: sent_date description: Only shipments sent on this day (ISO 8601 date, UTC). Cannot be combined with `date_from`, `date_to`, `sent_date_from` or `sent_date_to`. schema: type: string format: date required: false - in: query name: min_age_days description: Only shipments released at least this many whole days ago; at least 1. schema: type: integer minimum: 1 required: false - in: query name: failed_release description: When `true`, only shipments whose last release attempt failed. schema: type: boolean required: false - in: query name: awaiting_release description: When `true`, only shipments waiting to be released to a warehouse. schema: type: boolean required: false - in: query name: awaiting_allocation description: When `true`, only shipments waiting for their stock to be allocated in the warehouse. schema: type: boolean required: false - in: query name: label_required description: When `true`, only packed shipments still waiting for a shipping label (sub-status `label_required` or `label_error`); when `false`, all other shipments. schema: type: boolean required: false - in: query name: failed_address_validation description: When `true`, only shipments held because their address validation failed; when `false`, only shipments without an address validation error. schema: type: boolean required: false - in: query name: failed_allocation description: When `true`, only shipments whose stock could not be allocated in the warehouse. schema: type: boolean required: false - in: query name: failed_packaging description: When `true`, only shipments with a parcel whose shipping label could not be created (sub-status `label_error`). schema: type: boolean required: false - in: query name: error_resolved description: When `true`, only shipments with a parcel whose label error was resolved and that waits to be packed again (sub-status `error_resolved`). schema: type: boolean required: false - in: query name: container_code description: 'For warehouse use: only shipments kept in the warehouse container with this code before packing.' schema: type: string required: false - in: query name: destination_email description: Only shipments to this recipient email address, ignoring case. schema: type: string required: false - in: query name: is_b2b description: When `true`, only B2B shipments; when `false`, only B2C shipments. schema: type: boolean required: false - in: query name: processing_standard description: Only B2B shipments that use any of these B2B templates, by template key. schema: type: array items: type: string required: false explode: false style: form - in: query name: is_cod description: When `true`, only cash on delivery shipments; when `false`, only other shipments. schema: type: boolean required: false - in: query name: status description: Only shipments in any of these statuses; see `status` on the shipment for the values. schema: type: array items: type: string enum: - new - releasing - released - picking - packaging - packaged - sent - delivered - returning - returned - deleted required: false explode: false style: form - in: query name: sub_status description: Only shipments in any of these sub-statuses; needs a `status` filter. With more than one sub-status, send exactly one `status`, and each combination has to be valid. schema: type: array items: type: string enum: - validating_address - address_invalid - recalled - reserved - allocating - allocated - assigned - inbounding - inbound_error - label_error - error_resolved - autobag_failed - fba_details_required - fba_box_label_required - fba_pallet_label_required - label_required - label_created - label_uploaded - pickup_details_required - pickup_details_uploaded - manual_outbound - waiting_for_pickup - claim_reported - pick_up - in_transit - out_for_delivery - at_pickup_point - delayed - failed_delivery required: false explode: false style: form - in: query name: exclude_sub_status description: Leaves out shipments in any of these sub-statuses; shipments without a sub-status are kept. schema: type: array items: type: string enum: - validating_address - address_invalid - recalled - reserved - allocating - allocated - assigned - inbounding - inbound_error - label_error - error_resolved - autobag_failed - fba_details_required - fba_box_label_required - fba_pallet_label_required - label_required - label_created - label_uploaded - pickup_details_required - pickup_details_uploaded - manual_outbound - waiting_for_pickup - claim_reported - pick_up - in_transit - out_for_delivery - at_pickup_point - delayed - failed_delivery required: false explode: false style: form - in: query name: missing_documents description: When `true`, only shipments blocked because documents they need are missing. schema: type: boolean required: false - in: query name: priority_range description: 'For warehouse use: only shipments whose picking priority is within this range, given as `min,max` from 0 to 50; needs a `status` filter with only released statuses.' schema: type: array minItems: 2 items: type: integer minimum: 0 maximum: 50 required: false explode: false style: form - in: query name: priority description: 'For warehouse use: only shipments with exactly this picking priority, from 0 to 50; needs a `status` filter with only released statuses.' schema: type: integer minimum: 0 maximum: 50 required: false - in: query name: destination_countries description: Only shipments to any of these countries (ISO 3166-1 alpha-2), for example `DE,AT`. schema: type: array items: type: string pattern: ^[A-Z]{2}$ required: false explode: false style: form - in: query name: total_products description: Only shipments with exactly this number of different products, not counting bundles themselves; at least 1. schema: type: integer minimum: 1 required: false - in: query name: total_items description: Only shipments with exactly this total number of physical items to pick, counting the contents of bundles; at least 1. schema: type: integer minimum: 1 required: false - in: query name: total_picks description: 'For warehouse use: only shipments with exactly this number of items to pick, counting a packaging unit as one; needs a `status` filter with only allocated shipments.' schema: type: integer minimum: 1 required: false - in: query name: product_quantities description: 'For warehouse use: only shipments with exactly these contents, given as `product_id:quantity` pairs; needs a `status` filter with only allocated shipments.' schema: type: array items: type: string pattern: ^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}:[1-9]\d*$ required: false explode: false style: form - in: query name: lot_ids description: 'For warehouse use: only shipments whose picks come from exactly this set of lots (UUIDs); an empty list selects shipments without lot-tracked picks. Needs a `status` filter with only allocated shipments.' schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: has_identical_orders description: 'For warehouse use: when `true`, only shipments with exactly the same contents as at least one other shipment in the result; needs a `status` filter with only allocated shipments.' schema: type: boolean required: false - in: query name: exclude description: 'Parts to leave out of the response, which makes it faster: `items`, `units`.' schema: type: array items: type: string enum: - items - units required: false explode: false style: form - in: query name: only description: Fields to return, as comma-separated dotted paths of response field names, for example `id,status,units.items`; all fields when not sent. schema: type: array items: type: string required: false explode: false style: form - in: query name: label_error_status description: 'Only shipments with a label error in this state. - `blocked`: not resolved yet, like `failed_packaging` - `resolved`: resolved, like `error_resolved`' schema: type: string enum: - resolved - blocked required: false - in: query name: v3_packaging description: Only shipments packed (`true`) or not packed (`false`) with the v3 packing process. schema: type: boolean required: false - in: query name: order_number description: Only shipments with exactly this `shop.order_number`. schema: type: string required: false - in: query name: marketplace_order_number description: Only shipments with exactly this `shop.marketplace_order_number`. schema: type: string required: false - in: query name: marketplace description: Only shipments with this `shop.marketplace`, for example `amazon`. schema: type: string required: false - in: query name: products_barcodes_only description: 'For warehouse use: when `true`, only shipments containing products that have a barcode.' schema: type: boolean required: false - in: query name: include_unit_items description: Whether to include the items packed in each parcel (`units.items`), for example to read their serial numbers; defaults to `false`. Cannot be combined with excluding `units`. schema: type: boolean default: false required: false - in: query name: slam_compatible description: 'For warehouse use: when `true`, only shipments that can be packed on the automated labelling line; needs a `status` filter with only released statuses.' schema: type: boolean required: false - in: query name: autobag_compatible description: 'For warehouse use: only shipments that can (`true`) or cannot (`false`) be packed with the automatic bagging machine; needs a `status` filter with only released statuses.' schema: type: boolean required: false - in: query name: returnable description: 'When `true`, only shipments that can still be returned: `sent`, `delivered`, `returning` or `returned`, and sent within the last 180 days.' schema: type: boolean required: false - in: query name: customer_action_required description: When `true`, only shipments with an open action you need to take to unblock them. schema: type: boolean required: false - in: query name: customs_required description: Only shipments that need (`true`) or do not need (`false`) a customs declaration because they cross a customs border; known once a shipment is released. schema: type: boolean required: false - in: query name: has_shipping_label description: Only shipments that have (`true`) or do not have (`false`) a shipping label document. schema: type: boolean required: false - in: query name: filter_group_id description: 'For warehouse use: ID of a saved set of filters to apply instead of individual filters (UUID).' schema: type: string format: uuid required: false - in: query name: only_ground_level description: 'Deprecated. For warehouse use: when `true`, only shipments picked entirely from storage at ground level; when `false`, only shipments with at least one pick from a higher level.' schema: type: boolean required: false - in: query name: is_forklift_required description: 'For warehouse use: only shipments whose picking needs (`true`) or does not need (`false`) a forklift.' schema: type: boolean required: false - $ref: '#/components/parameters/Query' - $ref: '#/components/parameters/Fields' summary: Count shipments /v3/shipments/recall: post: operationId: shipmentbatchrecallapiv3_post responses: '200': $ref: '#/components/responses/Empty' '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Recalls several released shipments at once, as the single recall does for one. If any of them cannot be recalled, the request fails with the errors of each one that could not.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ShipmentBatch' x-byrd-roles: - admin - customer - service summary: Recall shipments /v3/shipments/release: post: operationId: shipmentbatchreleaseapiv3_post responses: '200': $ref: '#/components/responses/Empty' '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Schedules shipments in status `new` for release to a warehouse, which then reserves their stock and starts fulfilment. The release runs in the background; the response lists the shipments that were scheduled (`released`), could not be (`failed`) or were not found (`not_found`), with the `errors`.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ShipmentBatchRelease' x-byrd-roles: - admin - service - customer summary: Release shipments /v3/shipments/report: get: operationId: shipmentreportapiv3_get responses: '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' default: $ref: '#/components/responses/Undefined' tags: - Shipments description: 'Returns a CSV file with one row per item in each parcel of your shipments in the given period, most recent first and up to 10000 rows.' x-byrd-roles: - admin - customer parameters: - in: query name: date_from description: Start of the period to report on (ISO 8601); must be before `date_to` and not in the future. schema: type: string format: date-time required: true - in: query name: date_to description: End of the period to report on (ISO 8601, inclusive); must not be in the future. schema: type: string format: date-time required: true - in: query name: carrier description: Only parcels sent with this carrier, by carrier slug. schema: type: string required: false - in: query name: date_field description: 'Date that `date_from` and `date_to` apply to; defaults to `packaged_at`. - `packaged_at`: parcel packed - `sent_at`: parcel handed over to the carrier - `returned_at`: shipment returned - `created_at`: shipment created' schema: type: string default: packaged_at enum: - packaged_at - sent_at - returned_at - created_at required: false - in: query name: warehouse_id description: Only parcels from this warehouse (UUID). schema: type: string format: uuid required: false - in: query name: user_id description: ID of the byrd account to report on (UUID); if you send it, it has to be your own account. schema: type: string format: uuid required: false summary: Download a shipment report /v3/shipments/{shipment_id}: get: operationId: shipmentapiv3_get responses: '200': content: application/vnd.byrd.customer+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Shipment' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns the details of one of your shipments, including its parcels (`units`) with their tracking data and the items packed in each. Use `only` to return just the fields you need.' x-byrd-roles: - customer - service - admin - operator - warehouse parameters: - in: query name: only description: Fields to return, as comma-separated dotted paths of response field names, for example `id,status,units.items`; all fields when not sent. schema: type: array items: type: string required: false explode: false style: form - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: Get a shipment patch: operationId: shipmentapiv3_patch responses: '200': content: application/vnd.byrd.customer+json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Shipment' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Changes only the fields you send; a list you send, such as `items` or `documents`, replaces the existing one. The items and the service can be changed until the shipment is released, and the destination address until it is packed. See the Updating a shipment guide.' requestBody: content: application/vnd.byrd.customer+json: schema: $ref: '#/components/schemas/ShipmentUpdate' x-byrd-roles: - admin - service - customer parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: Update a shipment delete: operationId: shipmentapiv3_delete responses: '204': $ref: '#/components/responses/Empty' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Deletes one of your shipments that has not been released to a warehouse yet. To delete a released shipment, recall it first.' x-byrd-roles: - admin - service - customer parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: Delete a shipment /v3/shipments/{shipment_id}/documents: get: operationId: shipmentdocumentsbatchapiv3_get responses: '200': content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Document' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns the documents of a shipment, such as the documents you uploaded and its return labels. Shipping labels byrd created are listed once the shipment is sent.' x-byrd-roles: - service - customer - admin - operator - warehouse parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: List shipment documents post: operationId: shipmentdocumentsbatchapiv3_post responses: '201': $ref: '#/components/responses/Empty' '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Adds documents to a shipment, for example a delivery note to print and pack with it, or your own shipping label for a B2B shipment. A shipping label can only be uploaded while the shipment waits for one (sub-status `label_required`, `pickup_details_uploaded` or `label_uploaded`), except for `pickup` shipments.' requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/Document' x-byrd-roles: - service - customer - admin - operator - warehouse parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: Upload shipment documents /v3/shipments/{shipment_id}/documents/{document_id}/file: get: operationId: shipmentdocumentfileapiv3_get responses: '403': $ref: '#/components/responses/Error' default: $ref: '#/components/responses/Undefined' tags: - Shipments description: 'Returns the file of one document of the shipment, for example the PDF of its return label. Shipping labels byrd created can be downloaded once the shipment is sent.' x-byrd-roles: - service - customer - admin - operator - warehouse parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). - name: document_id in: path required: true schema: type: string description: ID of the shipment document (UUID). summary: Download a shipment document file /v3/shipments/{shipment_id}/picks: get: operationId: shipmentpicklistapiv3_get responses: '200': content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Pick' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns what was picked for the shipment, including the storage and lot each item came from. Lot details are complete once the shipment is `packaged`. See the shipped items lot data guide.' x-byrd-roles: - service - customer - admin - operator - warehouse parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: List a shipment's picks /v3/shipments/{shipment_id}/recall: post: operationId: shipmentrecallapiv3_post responses: '200': $ref: '#/components/responses/Empty' '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Takes a shipment back from the warehouse while it is still `released`, before picking starts, and cancels its fulfilment. The shipment returns to `new` with sub-status `recalled` and can be released again, to the same or another warehouse.' requestBody: content: application/json: schema: $ref: '#/components/schemas/ShipmentRecall' x-byrd-roles: - admin - customer - operator - service parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: Recall a shipment /v3/shipments/{shipment_id}/reservations: get: operationId: shipmentreservationlistapiv3_get responses: '200': content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Reservation' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns the stock reserved for the shipment in the warehouse, per product and lot, newest first. Reservations from earlier release attempts are left out.' x-byrd-roles: - service - customer - admin - operator - warehouse parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: List a shipment's reservations /v3/shipments/{shipment_id}/schedule-pickup: post: operationId: schedulepickupapiv3_post responses: '200': $ref: '#/components/responses/Empty' '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Sets the days a packed B2B shipment will be collected and, if known, the carrier and its tracking data, or that you collect it yourself. Allowed while the shipment''s sub-status is `pickup_details_required`, `pickup_details_uploaded` or `label_required`.' requestBody: content: application/json: schema: $ref: '#/components/schemas/SchedulePickup' x-byrd-roles: - admin - service - customer parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: Schedule the pickup of a B2B shipment /v3/shipments/{shipment_id}/units/{unit_id}: get: operationId: shipmentunitapiv3_get responses: '200': content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ShipmentUnit' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns one unit (parcel or pallet) of one of your shipments, with its carrier and tracking details, dimensions, packed items and serial numbers. See the tracking data guide for how units are used.' x-byrd-roles: - admin - customer - operator - warehouse parameters: - in: query name: only description: Comma-separated dotted paths of the fields to return, for example `id,status,items`. schema: type: array items: type: string required: false explode: false style: form - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). - name: unit_id in: path required: true schema: type: string description: ID of the unit (parcel or pallet) of the shipment (UUID). summary: Get a shipment unit /v3/shipments/{shipment_id}/validate-address: post: operationId: shipmentaddressvalidationapiv3_post responses: '200': $ref: '#/components/responses/Empty' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Queues the destination address of a shipment in status `new` for validation, for example after you corrected it. Only available when address validation is enabled for your account, and not for `pickup` shipments.' x-byrd-roles: - admin - service - customer parameters: - name: shipment_id in: path required: true schema: type: string description: ID of the shipment (UUID). summary: Validate a shipment's address /v3/units: get: operationId: unitlistapiv3_get responses: '200': content: application/json: schema: allOf: - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ShipmentUnitList' - $ref: '#/components/schemas/MinimalPaginationFields' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns the units (parcels and pallets) of your shipments, newest first by default, one page at a time. Filter by `shipment_id` to page through the units of a shipment that has too many to read from the shipment itself.' x-byrd-roles: - customer - service - admin - operator - warehouse parameters: - in: query name: ids description: Only return these units, by ID (comma-separated). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: shipment_id description: Only return units of these shipments, by ID (comma-separated). Use it to page through the units of a shipment with many units. schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: parcel_id description: Only return the unit with this parcel ID. schema: type: string minLength: 1 maxLength: 10 required: false - in: query name: status description: Only return units with one of these statuses (comma-separated). schema: type: array items: type: string enum: - new - packaged - sent - delivered - returning - returned required: false explode: false style: form - in: query name: sub_status description: Only return units with one of these sub-statuses (comma-separated). Requires `status`, and each sub-status must be possible for at least one of the given statuses. schema: type: array items: type: string enum: - at_pickup_point - autobag_failed - delayed - error_resolved - failed_delivery - fba_box_label_required - fba_details_required - fba_pallet_label_required - in_transit - label_created - label_error - label_required - label_uploaded - manual_outbound - out_for_delivery - pick_up - pickup_details_required - pickup_details_uploaded - slam_ready - waiting_for_pickup required: false explode: false style: form - in: query name: ignore_slam_errors description: Whether to leave out units blocked by an error of a SLAM machine. schema: type: boolean required: false - in: query name: label_error_status description: Only return units whose label error has one of these triage statuses (comma-separated); `untriaged` selects label errors not looked at yet. See `label_error_status` in the response for the values. schema: type: array items: type: string enum: - waiting_for_pricing - waiting_for_procurement - waiting_for_customer - waiting_for_warehouse - waiting_for_operations - waiting_for_engineering - waiting_for_carrier - waiting_for_deletion - untriaged required: false explode: false style: form - in: query name: min_age description: 'Only return units at least this old, measured from their creation: a positive whole number followed by `h` (hours), `d` (days), `w` (weeks) or `m` (30 days), for example `2d`.' schema: {} required: false - in: query name: max_age description: Only return units at most this old. Same format as `min_age`. schema: {} required: false - in: query name: custom_handling description: Only return units whose shipment is (`true`) or is not (`false`) custom-handled. schema: type: boolean required: false - in: query name: is_demo description: Only return units whose shipment belongs (`true`) or does not belong (`false`) to a demo account. schema: type: boolean required: false - in: query name: user_id description: Only return units of shipments of these byrd accounts, by ID (comma-separated). For customers, always their own account. schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: warehouse_id description: Only return units of shipments fulfilled by these warehouses, by ID (comma-separated). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: sort_by description: 'Field to sort by. Defaults to `created_at`. - `created_at` - `updated_at` - `label_error_occurred`' schema: type: string required: false - in: query name: sort_order description: Sort direction, `asc` or `desc`. Defaults to `desc`. schema: type: string enum: - asc - desc required: false - in: query name: include_deleted description: Whether to include deleted units. Defaults to `false`; always `false` for customers. schema: type: boolean default: false required: false - in: query name: only description: Comma-separated dotted paths of the fields to return, for example `id,status,items`. schema: type: array items: type: string required: false explode: false style: form - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Page' summary: List units /v3/units/count: get: operationId: unitlistcountapiv3_get responses: '200': content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ShipmentUnitCount' description: Success response to a valid request '400': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' tags: - Shipments description: 'Returns how many of your units match the filters, which are the same as those of the unit list. The count stops at 10,000; `capped` tells you when it did.' x-byrd-roles: - customer - service - admin - operator - warehouse parameters: - in: query name: ids description: Only return these units, by ID (comma-separated). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: shipment_id description: Only return units of these shipments, by ID (comma-separated). Use it to page through the units of a shipment with many units. schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: parcel_id description: Only return the unit with this parcel ID. schema: type: string minLength: 1 maxLength: 10 required: false - in: query name: status description: Only return units with one of these statuses (comma-separated). schema: type: array items: type: string enum: - new - packaged - sent - delivered - returning - returned required: false explode: false style: form - in: query name: sub_status description: Only return units with one of these sub-statuses (comma-separated). Requires `status`, and each sub-status must be possible for at least one of the given statuses. schema: type: array items: type: string enum: - at_pickup_point - autobag_failed - delayed - error_resolved - failed_delivery - fba_box_label_required - fba_details_required - fba_pallet_label_required - in_transit - label_created - label_error - label_required - label_uploaded - manual_outbound - out_for_delivery - pick_up - pickup_details_required - pickup_details_uploaded - slam_ready - waiting_for_pickup required: false explode: false style: form - in: query name: ignore_slam_errors description: Whether to leave out units blocked by an error of a SLAM machine. schema: type: boolean required: false - in: query name: label_error_status description: Only return units whose label error has one of these triage statuses (comma-separated); `untriaged` selects label errors not looked at yet. See `label_error_status` in the response for the values. schema: type: array items: type: string enum: - waiting_for_pricing - waiting_for_procurement - waiting_for_customer - waiting_for_warehouse - waiting_for_operations - waiting_for_engineering - waiting_for_carrier - waiting_for_deletion - untriaged required: false explode: false style: form - in: query name: min_age description: 'Only return units at least this old, measured from their creation: a positive whole number followed by `h` (hours), `d` (days), `w` (weeks) or `m` (30 days), for example `2d`.' schema: {} required: false - in: query name: max_age description: Only return units at most this old. Same format as `min_age`. schema: {} required: false - in: query name: custom_handling description: Only return units whose shipment is (`true`) or is not (`false`) custom-handled. schema: type: boolean required: false - in: query name: is_demo description: Only return units whose shipment belongs (`true`) or does not belong (`false`) to a demo account. schema: type: boolean required: false - in: query name: user_id description: Only return units of shipments of these byrd accounts, by ID (comma-separated). For customers, always their own account. schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: warehouse_id description: Only return units of shipments fulfilled by these warehouses, by ID (comma-separated). schema: type: array items: type: string format: uuid required: false explode: false style: form - in: query name: sort_by description: 'Field to sort by. Defaults to `created_at`. - `created_at` - `updated_at` - `label_error_occurred`' schema: type: string required: false - in: query name: sort_order description: Sort direction, `asc` or `desc`. Defaults to `desc`. schema: type: string enum: - asc - desc required: false - in: query name: include_deleted description: Whether to include deleted units. Defaults to `false`; always `false` for customers. schema: type: boolean default: false required: false - in: query name: only description: Comma-separated dotted paths of the fields to return, for example `id,status,items`. schema: type: array items: type: string required: false explode: false style: form summary: Count units components: schemas: ReturnShipmentAnnounced: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). shipment_id: type: string format: uuid description: ID of the shipment being returned (UUID). The shipment must be yours and must have been sent. send_documents_to_email: type: - string - 'null' format: email description: Email address the return label is sent to once it is generated. `null` when the return was announced with `send_email` set to `false`. documents_email_language: type: string maxLength: 2 description: Language of the email carrying the return label and of the label itself, as an ISO 639-1 two-letter code, for example `de`. `en`, `de` and `fr` are supported and any other value falls back to English. When `null`, the language is taken from the destination country of the shipment, falling back to English. portal_tier: type: - string - 'null' enum: - basic - pro - null description: Returns Portal tier the return was announced through, `basic` or `pro`; `null` when the return was not announced through the Returns Portal. label_type: type: string enum: - byrd_label - identifier_only description: 'Kind of return label generated for the return. Defaults to `byrd_label`. - `byrd_label`: carrier shipping label for `courier`. - `identifier_only`: a return slip whose cut-off strip identifies the return to the warehouse; it is not a shipping label and has no tracking number.' courier: type: string enum: - amazon_prime - asendia_global - brt_it - colissimo_fr - correos_es - dbschenker_global - delivengo_fr - derkurier_de - dhl_de - dhlexpress_de - dpd_at - dpd_de - dpd_gb - exporto_global - fedex_global - gls_global - mondialrelay_fr - parcelforce_gb - post_at - post_de - post_it - post_nl - royalmail_gb - schneckenpost_de - sendcloud_global - seur_es - sevensenders_global maxLength: 64 description: Carrier the return is shipped with. Must be a carrier enabled for your account, the warehouse and the destination country; ask your byrd contact person which value applies to you. status: type: string description: 'Current status of the return. - `announced`: the return was announced and has not been processed by the warehouse yet. - `confirmed`: the warehouse received and confirmed the return. - `cancelled`: the confirmed return was cancelled.' return_type: type: string description: 'Type of the return. - `customer`: the recipient sends the shipment back; every return announced through this API has this type. - `courier`: the carrier sent the shipment back after a failed delivery.' reason: type: string description: Reason for the return; always `customer` for a return announced by the recipient. The reason for each item is in `items_announced`. items_announced: description: Items of the shipment that are being returned, with their amounts; at least one. Each shipment item can be announced in only one return. type: array items: $ref: '#/components/schemas/ItemsAnnounced' documents: readOnly: true description: Documents generated for the return, such as the return label. Usually empty right after announcing, because the documents are generated a few seconds later. type: array items: $ref: '#/components/schemas/ReturnShipmentAnnouncedDocument' required: - send_documents_to_email - shipment_id title: Return shipment announced Customer: type: object properties: id: type: string format: uuid readOnly: true description: ID of the byrd account (UUID). company_name: type: string description: Company name of the byrd account. title: Customer ShipmentUnitListWarehouse: type: object properties: id: type: string format: uuid description: ID of the warehouse (UUID); `null` until a warehouse is assigned. code: type: string description: Short code of the warehouse. additionalProperties: false title: Shipment unit list warehouse ShipmentList: type: object properties: id: type: string format: uuid readOnly: true description: ID of the shipment (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). b2b_config: readOnly: true description: 'B2B configuration of the shipment: the B2B template it uses and your answers to it; `null` for B2C shipments.' allOf: - $ref: '#/components/schemas/B2BConfig' checkpoints: readOnly: true description: Timestamps (ISO 8601, UTC) of the milestones the shipment has reached; a milestone not reached yet is `null`. allOf: - $ref: '#/components/schemas/Checkpoints' container_code: type: string description: Code of the warehouse container the picked items are kept in until the shipment is packed. customs: description: Customs details used to generate the export documents; required for international shipments. `null` when none were provided. allOf: - $ref: '#/components/schemas/Customs' destination_address: description: Address and contact details of the recipient. For deliveries to a carrier pickup point, see the pickup point guides for how to fill it. allOf: - $ref: '#/components/schemas/ShipmentDestinationAddress' errors: readOnly: true description: Errors blocking the shipment from progressing, for example a failed address validation or an allocation problem; empty when nothing is blocking it. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' insurance: description: Declared value the shipment is insured for; `null` when the shipment is not insured. allOf: - $ref: '#/components/schemas/Insurance' metrics: readOnly: true description: Item, SKU, pick and packaging-unit counts for the shipment. allOf: - $ref: '#/components/schemas/ShipmentListMetrics' notes: description: Free-text notes for your own use and packaging instructions for the warehouse. allOf: - $ref: '#/components/schemas/Notes' options: description: Fulfilment and shipping options set on the shipment. allOf: - $ref: '#/components/schemas/ShipmentListOptions' origin: type: string readOnly: true description: 'How the shipment was created; `null` for shipments created before this was recorded. - `api`: through the API with an API key - `manual`: in the byrd dashboard - `integration`: by a byrd shop integration' byrd_id: type: string readOnly: true description: Short human-readable identifier of the shipment, shown in the dashboard and printed on warehouse documents. example: ABCD12345 priority: type: integer readOnly: true description: Picking priority in the warehouse, from 0 (normal) to 40 (highest); rises automatically once the shipping deadline is reached. `null` until the shipment is released. example: 10 return_address: readOnly: true description: Address of the fulfilling warehouse that returns are sent to; `null` until the shipment is released. allOf: - $ref: '#/components/schemas/ReturnAddress' service: type: string enum: - economy - standard - express - pickup - pickup_point description: 'Shipping service the shipment is sent with. - `standard`: regular delivery - `express`: faster delivery, picked with higher priority - `economy`: cheapest, slower delivery - `pickup_point`: delivery to a carrier pickup point - `pickup`: collected from the warehouse, not shipped' shop: description: Order references from your shop or order system, such as the order number. allOf: - $ref: '#/components/schemas/ShipmentShop' status: type: string readOnly: true description: 'Current status of the shipment. - `new`: created and not yet released to a warehouse - `releasing`: being released to a warehouse - `released`: released and waiting to be picked - `picking`: items are being picked - `packaging`: being packed - `packaged`: packed and labelled - `sent`: handed over to the carrier - `delivered`: delivered to the recipient - `returning`: a return shipment was created - `returned`: the return arrived at the warehouse - `deleted`: deleted' sub_status: type: string readOnly: true description: 'Detail on the current `status`; `null` when there is none. - `validating_address`, `address_invalid`, `recalled`: while `new` - `reserved`, `allocating`, `allocated`, `assigned`, `inbounding`, `inbound_error`: while `released` - `label_error`, `error_resolved`, `autobag_failed`: while `packaging` - `label_required`, `label_created`, `label_uploaded`, `pickup_details_required`, `pickup_details_uploaded`, `manual_outbound`, `waiting_for_pickup`, `fba_details_required`, `fba_box_label_required`, `fba_pallet_label_required`: while `packaged`, mostly for B2B shipments - `pick_up`, `in_transit`, `at_pickup_point`, `out_for_delivery`, `delayed`, `failed_delivery`: carrier tracking events while `sent` - `claim_reported`: a support claim is open, while `sent` or `delivered`' units: readOnly: true description: Physical parcels or pallets the shipment is packed into, each with its own tracking information. type: array items: $ref: '#/components/schemas/ShipmentListUnit' warnings: readOnly: true description: Problems that do not block the shipment, for example an address validation error on a shipment released anyway, or the reason it was recalled. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' warehouse: readOnly: true description: Warehouse fulfilling the shipment; its fields are `null` until a warehouse is assigned. allOf: - $ref: '#/components/schemas/ShipmentWarehouse' user: readOnly: true description: byrd account the shipment belongs to. allOf: - $ref: '#/components/schemas/ShipmentUser' dangerous_goods: readOnly: true description: Dangerous goods totals for the shipment. allOf: - $ref: '#/components/schemas/DGDetails' cash_on_delivery: description: Amount the carrier collects from the recipient on delivery; `null` when the shipment is not cash on delivery. allOf: - $ref: '#/components/schemas/CashOnDelivery' total_value: readOnly: true description: Total value of the items (unit price × quantity), converted to EUR. allOf: - $ref: '#/components/schemas/CashOnDeliveryPrice' packaging_materials: description: Packaging materials requested or suggested for packing the shipment. type: - array - 'null' items: $ref: '#/components/schemas/PackagingMaterials' user_id: type: string format: uuid writeOnly: true description: ID of the byrd account the shipment is created for (UUID); for your requests it is always your own account. documents: writeOnly: true description: Documents the warehouse prints and packs with the shipment, such as delivery notes or invoices. type: array items: $ref: '#/components/schemas/Document' warehouse_id: type: - string - 'null' format: uuid writeOnly: true description: ID of the warehouse that has to fulfil the shipment; if omitted, byrd assigns one automatically. warehouse_user_id: type: - string - 'null' format: uuid writeOnly: true description: ID of the warehouse worker assigned to pick the shipment. pickup_point: type: - object - 'null' default: null writeOnly: true description: Carrier pickup point to deliver to, for `pickup_point` shipments; the fields it needs depend on the carrier. additionalProperties: {} items: description: Products in the shipment and their quantities; at least one. type: array items: $ref: '#/components/schemas/Item' required: - destination_address - items title: Shipment list ShipmentUpdateShop: type: object properties: id: type: string description: ID of the byrd shop integration the shipment was imported from; `null` for shipments created through the API. type: type: string description: Type of the byrd shop integration the shipment was imported from; `null` for shipments created through the API. order_number: type: string description: Order number in your shop or order system, shown in the Order column of the dashboard. order_id: type: string description: Any other identifier of the order in your system; not shown in the dashboard. marketplace_order_number: type: string description: Order number given by the marketplace the order was sold on, when that is not the system sending the shipment, for example the Amazon order number of an order forwarded by a connected shop. Returns are labelled with it, which lets the warehouse match a return to the shipment; send it in addition to `order_number` and `order_id`. marketplace: type: string description: Marketplace that `marketplace_order_number` belongs to, in lower case, for example `amazon`, `ebay` or `kaufland`. If you cannot tell it reliably, leave it out rather than guess. title: Shipment update shop PickStorageLot: type: object properties: id: type: string format: uuid description: ID of the lot (UUID). lot_number: type: string description: Lot (batch) number the product was picked from. expiry_date: type: string description: Date the lot expires (ISO 8601 date, `YYYY-MM-DD`); `null` when the lot has no expiry date. example: '2024-12-31' title: Pick storage lot Reservation: type: object properties: id: type: string format: uuid readOnly: true description: ID of the reservation (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). quantity: type: integer description: Number of selling units reserved. lot_id: type: string format: uuid readOnly: true description: ID of the lot the stock is reserved from (UUID); `null` when no specific lot is reserved. product: description: Product the stock is reserved for. allOf: - $ref: '#/components/schemas/ReservationProduct' shipment_id: type: string format: uuid description: ID of the shipment the stock is reserved for (UUID). warehouse_id: type: string format: uuid description: ID of the warehouse the stock is reserved in (UUID). title: Reservation ShipmentUnitCount: type: object properties: count: type: integer readOnly: true description: Number of units matching the filters. capped: type: boolean readOnly: true description: Whether the count reached the maximum of 10,000; when `true`, `count` is that maximum and more units may match. additionalProperties: false title: Shipment unit count ReturnShipment: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). shipment: readOnly: true description: Original shipment the return belongs to. allOf: - $ref: '#/components/schemas/ReturnedShipment' shipmentID: type: string format: uuid description: ID of the original shipment (UUID). unitID: type: - string - 'null' format: uuid description: ID of the shipment unit (parcel) that came back (UUID); set for courier returns only. unit: readOnly: true description: Shipment unit (parcel) that came back; `null` when the return is not linked to a unit. allOf: - $ref: '#/components/schemas/ReturnShipmentUnit' status: type: string enum: - announced - confirmed - cancelled readOnly: true description: 'Current status of the return. - `announced`: announced by the recipient, not received yet - `confirmed`: received and confirmed by the warehouse - `cancelled`: a confirmed return that was cancelled; not included in your results' returnType: type: string enum: - courier - customer description: 'Who initiated the return. - `courier`: the carrier could not deliver the shipment and sent it back, e.g. because of a wrong address or failed delivery attempts - `customer`: the recipient sent items back, e.g. because they were defective or unwanted' reason: type: string description: 'Why the shipment was returned. Customer returns always have `customer`; the reasons per item are in `itemsAnnounced`. - `bad-address`: the address was wrong or incomplete - `bad-product`: the product was defective, damaged or not as expected - `country`: shipping restrictions or customs rules of the destination country - `no-pickup`: the recipient did not collect the parcel where the courier held it - `rec-unknown`: the recipient is unknown at the address - `refused-delivery`: the recipient refused the delivery - `unwanted`: the recipient no longer wanted the items - `customer`: a return announced by the recipient' manualSearchRequired: type: boolean description: Whether the warehouse had to search manually to find the original shipment of the return. internalComments: type: string description: Notes the warehouse recorded while processing the return. publicComments: type: string description: Comments of the warehouse about the return, meant for you; empty when there are none. courierFee: description: Fee charged for accepting the return from the courier; `null` when there is none. allOf: - $ref: '#/components/schemas/TotalPrice' items: description: Items the warehouse received and checked, with their condition; empty until the return is processed. type: array items: $ref: '#/components/schemas/ReturnShipmentItem' itemsAnnounced: readOnly: true description: Items announced for return, with quantity and reason, before the warehouse checked them; empty when the return was not announced. type: array items: $ref: '#/components/schemas/ReturnShipmentItemAnnounced' sendDocumentsToEmail: type: string format: email readOnly: true description: Email address the return label was sent to; `null` when no label was sent. documents: readOnly: true description: Documents generated for the return, such as the return label. Usually empty right after announcing, as they are generated asynchronously. type: array items: $ref: '#/components/schemas/ReturnShipmentDocument' courier: type: string readOnly: true description: Carrier the return is shipped with, as a carrier identifier such as `dhl_de`; `null` when unknown. courierTrackingNumber: type: string readOnly: true description: Tracking number of the return parcel at the carrier; `null` when unknown. courierTrackingURL: type: string readOnly: true description: Carrier tracking page of the return parcel; `null` when unknown. announcedAt: type: string format: date-time readOnly: true description: When the return was announced (ISO 8601, UTC); `null` for returns that were not announced, such as courier returns. postedAt: type: string format: date-time readOnly: true description: When the returner handed the parcel to the carrier (ISO 8601, UTC); `null` when unknown. deliveredAt: type: string format: date-time readOnly: true description: When the return arrived at the warehouse (ISO 8601, UTC); `null` until it arrives. processedAt: type: string format: date-time readOnly: true description: When the warehouse checked the returned items (ISO 8601, UTC); `null` until processed. confirmedAt: type: string format: date-time readOnly: true description: When the warehouse confirmed the return (ISO 8601, UTC); `null` until confirmed. cancelledAt: type: string format: date-time readOnly: true description: When the confirmed return was cancelled (ISO 8601, UTC); `null` unless cancelled. portalTier: type: string readOnly: true description: 'Returns portal tier the return was created with; `null` for returns not created through the returns portal. - `basic` - `pro`' labelType: type: string readOnly: true description: 'Kind of label the return got; `null` for returns not created through the returns portal. - `byrd_label`: a carrier shipping label - `identifier_only`: only a label identifying the return' warehouseID: type: string format: uuid readOnly: true description: ID of the warehouse the return is sent to (UUID). shipmentError: readOnly: true description: Error that stopped the return documents from being generated; `null` when there is none. allOf: - $ref: '#/components/schemas/ReturnShipmentError' required: - shipmentID title: Return shipment RemoteAreaSurcharge: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ tax_factor: type: - number - 'null' actual_carrier: type: - string - 'null' value: type: string readOnly: true title: Remote area surcharge ReturnedShipmentUser: type: object properties: companyName: type: - string - 'null' description: Name of your company; `null` when not set. directComplete: type: boolean readOnly: true description: Whether the warehouse may use the simplified picking process for your shipments, skipping barcode scans when picking. firstName: type: string description: First name of the account holder. id: type: string format: uuid readOnly: true description: ID of the record (UUID). lastName: type: string description: Last name of the account holder. senderName: type: - string - 'null' description: Sender name printed on shipping labels instead of the company name; `null` when not set. skipBarcodePick: type: boolean readOnly: true description: Whether warehouse staff may skip scanning product barcodes when picking and packing your shipments. warehouseInstructions: type: - string - 'null' readOnly: true description: Packing instructions the warehouse follows for all your shipments (HTML); `null` when there are none. required: - firstName - lastName - warehouseInstructions title: Returned shipment user ReturnShipmentAnnouncedDocument: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). type: type: string description: 'Kind of document. - `printable_label`: return label to print and attach to the parcel (PDF). - `qr_code`: QR code from the carrier, for example to hand in the parcel without a printed label (PNG).' data_type: type: string description: 'File format of the document. - `pdf`: PDF file. - `png`: PNG image.' required: - data_type - type title: Return shipment announced document Address: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). thoroughfare: type: - string - 'null' description: Street name; send the house number in `subThoroughfare` where possible. subThoroughfare: type: - string - 'null' description: House or building number. subSubThoroughfare: type: - string - 'null' description: Additional address details, such as building, floor or apartment. locality: type: string description: City or town. subLocality: type: - string - 'null' description: District or neighbourhood within the city. adminArea: type: - string - 'null' description: State, province or region, where the country uses one. subAdminArea: type: - string - 'null' description: County or district below the state or region. postalCode: type: string description: Postal code. A prefix matching `countryCode`, as in `DE-12345`, is removed. countryCode: type: string pattern: ^[A-Z]{2}$ description: Country, as an ISO 3166-1 alpha-2 code. latitude: type: - number - 'null' description: Latitude of the address, in decimal degrees. longitude: type: - number - 'null' description: Longitude of the address, in decimal degrees. validated: type: boolean readOnly: true description: Whether byrd has validated the address. `false` only means it was not validated, not that it is invalid. required: - countryCode - locality - postalCode title: Address ItemBaseDangerousGoods: type: object properties: un_number: type: string readOnly: true description: Four-digit UN number identifying the dangerous substance. example: '3481' quantity: type: number readOnly: true description: Amount of the dangerous substance in one unit of the product, in the measure its UN number uses (g, l or Wh). limit_type: type: string readOnly: true description: 'Transport regime the dangerous goods are shipped under. - `LQ`: limited quantity - `SV188`: special provision 188 (small lithium cells and batteries)' title: Item base dangerous goods ShipmentUnitCheckpoint: type: object properties: packaged_at: type: string format: date-time description: When the warehouse packed the unit. accepted_at: type: string format: date-time description: When the carrier first scanned the unit. delivered_at: type: string format: date-time description: When the carrier delivered the unit to the recipient. sent_at: type: string format: date-time description: When the unit left the warehouse. title: Shipment unit checkpoint UnitMetrics: type: object properties: total_items: type: integer description: Number of physical items in the unit, with packaging units counted by their contents. total_skus: type: integer description: Number of distinct products in the unit. total_multi_picks: type: integer description: Number of packaging units in the unit. total_single_picks: type: integer description: Number of single selling units in the unit, not counting packaging units and branding products. total_organic_picks: type: integer description: Number of organic products in the unit. total_grs_picks: type: integer description: Number of GRS (Global Recycled Standard) certified products in the unit. total_fragile_picks: type: integer description: Number of fragile products in the unit. total_branding_picks: type: integer description: Number of branding products, such as flyers or stickers, in the unit. total_serial_numbers: type: integer description: Number of serial numbers recorded for the unit. total_dangerous_goods: type: integer description: Number of dangerous goods products in the unit. title: Unit metrics ShipmentUnitDetailCheckpoint: type: object properties: packaged_at: type: string format: date-time description: When the warehouse packed the unit. accepted_at: type: string format: date-time description: When the carrier first scanned the unit. delivered_at: type: string format: date-time description: When the carrier delivered the unit to the recipient. sent_at: type: string format: date-time description: When the unit left the warehouse. created_at: type: string format: date-time description: When the unit was created. label_error_occurred_at: type: string format: date-time description: When the unit's last label error occurred (ISO 8601, UTC); `null` when label creation never failed. label_error_resolved_at: type: string format: date-time description: When the unit's last label error was resolved; `null` when it never had one or it is not resolved yet. slam_prepared_at: type: string format: date-time description: When the packed unit was ready to be labelled by a SLAM machine; `null` for units not labelled by one. title: Shipment unit detail checkpoint ShipmentCount: type: object properties: count: type: integer readOnly: true description: Number of shipments that match the filters, up to 100000. capped: type: boolean readOnly: true description: Whether the number of matching shipments reached the limit of 100000, in which case `count` is the limit rather than the exact number. additionalProperties: false title: Shipment count ShipmentUnitList: type: object properties: id: type: string format: uuid readOnly: true description: ID of the unit (UUID). items: description: Products packed in the unit; empty for units packed before items were recorded per unit. type: array items: $ref: '#/components/schemas/UnitItem' service: type: string description: 'Shipping service the unit is sent with; usually the shipment''s `service`, but it can differ when an economy fallback applies. - `standard` - `express` - `economy` - `pickup_point` - `pickup` - `amazon_prime`' carrier: description: Carrier the unit is sent with and its tracking details; the fields are `null` until a label is created. allOf: - $ref: '#/components/schemas/Carrier' parcel_id: type: string readOnly: true description: Unique 10-character alphanumeric identifier of the unit. example: A1B2C3D4E5 type: type: string readOnly: true description: 'Kind of unit. - `parcel`: a parcel - `pallet`: a pallet' status: type: string readOnly: true description: 'Current status of the unit. - `new`: created and not yet packed and labelled - `packaged`: packed and labelled - `sent`: handed over to the carrier - `delivered`: delivered to the recipient - `returning`: being returned to the warehouse - `returned`: the return arrived at the warehouse' sub_status: type: string readOnly: true description: 'Detail on the current `status`; `null` when there is none. - `label_error`, `error_resolved`: creating the label failed, or the failure was fixed; while `new` or `packaged` - `slam_ready`, `autobag_failed`: waiting for the SLAM machine, or the bagging machine failed; while `new` - `label_required`, `label_created`, `label_uploaded`, `pickup_details_required`, `pickup_details_uploaded`, `waiting_for_pickup`, `manual_outbound`, `fba_details_required`, `fba_box_label_required`, `fba_pallet_label_required`: while `packaged`, mostly for B2B shipments - `pick_up`, `in_transit`, `at_pickup_point`, `out_for_delivery`, `delayed`, `failed_delivery`: carrier tracking events while `sent`' label_error_status: type: string readOnly: true description: 'Who byrd is waiting on to resolve the unit''s label error; `null` when there is no error or it has not been looked at yet. - `waiting_for_customer`: you have to fix or confirm something, such as the address or customs data - `waiting_for_warehouse`: the warehouse has to check the parcel - `waiting_for_carrier`: the carrier has to respond or fix something - `waiting_for_pricing`, `waiting_for_procurement`, `waiting_for_operations`, `waiting_for_engineering`: a byrd team has to act - `waiting_for_deletion`: the error will not be fixed and the unit will be deleted' checkpoints: readOnly: true description: Timestamps (ISO 8601, UTC) of the milestones the unit has reached; a milestone not reached yet is `null`. allOf: - $ref: '#/components/schemas/ShipmentUnitCheckpoint' errors: readOnly: true description: Errors blocking the unit, such as a failed label creation; empty when nothing is blocking it. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' error_code: type: string readOnly: true description: Code of the error currently blocking the unit, for example `LC00` for a carrier error; `null` when there is none. slam: type: boolean readOnly: true description: Whether the unit is measured and labelled by a SLAM (scan, label, apply, manifest) machine. autobag: type: boolean readOnly: true description: Whether the unit is packed by an automatic bagging machine. dimensions: description: Outer dimensions (cm) and weight (kg) of the packed unit. allOf: - $ref: '#/components/schemas/UnitDimensions' pregenerated: type: boolean readOnly: true description: Whether the unit and its shipping label were created in advance, before packing. packaging_materials: description: Packaging materials the unit was packed with. type: - array - 'null' items: $ref: '#/components/schemas/PackagingMaterials' group_number: type: integer readOnly: true description: Number of the packing station group whose printer printed the unit's label; `null` until the unit is labelled. shipment_id: type: string format: uuid readOnly: true description: ID of the shipment the unit belongs to (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). label_error_occurred_at: type: string format: date-time readOnly: true description: When the unit's last label error occurred (ISO 8601, UTC); `null` when label creation never failed. warehouse: readOnly: true description: Warehouse fulfilling the unit's shipment. allOf: - $ref: '#/components/schemas/ShipmentUnitListWarehouse' customer: readOnly: true description: byrd account the unit's shipment belongs to. allOf: - $ref: '#/components/schemas/Customer' sequence_number: type: string readOnly: true description: Position of the unit among the shipment's units, starting at 1. metrics: readOnly: true description: Item and pick counts for the unit; `null` for units without recorded items. allOf: - $ref: '#/components/schemas/UnitMetrics' title: Shipment unit list ReturnedShipment: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). cod: type: - object - 'null' properties: codValue: type: number minimum: 0 maximum: 2500 description: Amount to collect from the recipient, from 0 to 2500. codCurrency: type: string enum: - EUR description: Currency of `codValue` (ISO 4217); only `EUR`. required: - codCurrency - codValue description: Amount the carrier collects from the recipient on delivery; `null` when the shipment is not cash on delivery. customs: type: - object - 'null' properties: invoiceNumber: type: string description: Commercial invoice number of the order. goodsType: type: string enum: - document - gift - sample - remand - other description: 'Type of goods in the shipment. - `document`: documents - `gift`: a gift - `sample`: commercial samples - `remand`: returned goods - `other`: any other goods' required: - goodsType - invoiceNumber description: Customs details used to generate the export documents; `null` when none were provided. description: type: - string - 'null' description: Note for your own use, visible in the dashboard. It is not sent to the recipient nor shown to the warehouse. destinationAddress: description: Address of the recipient. allOf: - $ref: '#/components/schemas/Address' destinationCompany: type: - string - 'null' description: Company name, if the recipient is a company. destinationEmail: type: - string - 'null' description: Email address of the recipient. destinationName: type: string description: Name of the recipient. destinationPhone: type: - string - 'null' description: Phone number of the recipient, including the country code where possible (for example `+4912345890`). Characters other than digits and `+` are removed. fragile: type: boolean description: Whether the shipment contains fragile items that need extra care. insurance: type: - object - 'null' properties: insuranceValue: type: number minimum: 0 description: Value of the whole shipment for insurance purposes; at least 0. insuranceCurrency: type: string enum: - EUR description: Currency of `insuranceValue` (ISO 4217); only `EUR`. required: - insuranceCurrency - insuranceValue description: Declared value the shipment is insured for; `null` when the shipment is not insured. option: type: string enum: - book - economy - standard - express - amazon_prime - pickup - pickup_point description: 'Shipping service of the shipment. Defaults to `standard`. - `standard`: regular delivery - `express`: faster delivery - `economy`: cheapest, slower delivery - `pickup_point`: delivery to a carrier pickup point - `pickup`: collected from the warehouse; B2B shipments only - `amazon_prime`: Amazon Prime order, labelled through Amazon - `book`: legacy value, not used any more' orderID: type: - string - 'null' description: Any other identifier of the order in your system; not shown in the dashboard. orderNumber: type: - string - 'null' description: Order number from your shop, shown in the Order column of the dashboard. preferredCarrier: type: - string - 'null' description: Carrier you prefer for this shipment. It overrides byrd's automatic carrier selection and can lead to shipment errors, so use it with caution. shopID: type: - string - 'null' format: uuid description: ID of the connected shop the shipment came from (UUID); `null` when it was not created by a shop integration. shopType: type: - string - 'null' description: Type of shop system the shipment came from, for example `shopify` or `woocommerce`. toBeBranded: type: - boolean - 'null' description: Whether the shipment is packed with your branded packaging. toBePackaged: type: - boolean - 'null' description: Whether the warehouse packs the items into shipping packaging; `false` ships them in their own packaging. userHeight: type: - number - 'null' minimum: 0 description: Parcel height you provided, in cm. userLength: type: - number - 'null' minimum: 0 description: Parcel length you provided, in cm. userPictureID: type: - string - 'null' format: uuid userWeight: type: - number - 'null' minimum: 0 description: Parcel weight you provided, in kg. userWidth: type: - number - 'null' minimum: 0 description: Parcel width you provided, in cm. recallReason: type: - string - 'null' readOnly: true description: Why the shipment was recalled from the warehouse; `null` when it was not recalled. carrier: type: - string - 'null' readOnly: true description: Carrier the shipment is sent with; `null` until a label is created. packagingStartDate: type: string format: date-time readOnly: true description: When packing of the shipment started (ISO 8601); `null` until then. releasedAt: type: string format: date-time readOnly: true description: When the shipment was released to a warehouse (ISO 8601); `null` until a release succeeds. Failed release attempts do not set it. releaseError: type: object readOnly: true description: Error from the last failed attempt to release the shipment to a warehouse; `null` when there is none. additionalProperties: {} outboundError: type: object readOnly: true description: Error from handing the shipment over to the carrier; `null` when there is none. additionalProperties: {} labelError: type: - object - 'null' readOnly: true description: Error from the last failed attempt to create the shipping label, with its `code` and `message`; `null` when there is none. addressValidationError: type: - object - 'null' readOnly: true description: Error from the failed address validation, with its `code` and `message`; `null` when the address passed or was not validated. totalPrice: readOnly: true description: 'Total price of the shipment: the shipping rate plus the fees recorded on it.' allOf: - $ref: '#/components/schemas/TotalPrice' type: type: string readOnly: true description: Type of the shipment; always `fulfillment`. user: readOnly: true description: byrd account the shipment belongs to. allOf: - $ref: '#/components/schemas/ReturnedShipmentUser' subStatus: type: string readOnly: true description: 'Detail on a `fulfillmentCompleted` shipment; `null` in every other status. - `waitingForLabel`: ready for its shipping label - `labelErrorOccurred`: creating the label failed and the shipment is blocked until the error is fixed - `labelErrorResolved`: a label error was fixed and the label can be created again' packagingMaterialID: type: - string - 'null' readOnly: true description: ID of the packaging material used to pack the shipment. Superseded by `packagingMaterials`. packagingMaterials: type: array readOnly: true items: type: object properties: packagingMaterialID: type: string quantity: type: integer description: Packaging materials used to pack the shipment, each with its `packagingMaterialID` and `quantity`; empty until packed. warehouseID: type: - string - 'null' format: uuid readOnly: true description: ID of the warehouse that fulfils the shipment (UUID); if omitted, byrd assigns one automatically. hasDangerousGoods: type: boolean readOnly: true description: Whether any item of the shipment contains dangerous goods. limitedQuantityWeight: type: number readOnly: true description: Total weight of the items with limited-quantity dangerous goods, in kg; printed on the delivery note. totalDangerousGoodsItems: type: integer readOnly: true description: Number of item units in the shipment that contain dangerous goods. shipmentItems: description: Products in the shipment and their quantities. type: array items: $ref: '#/components/schemas/ShipmentItem' documents: description: Documents for the shipment, such as delivery notes, invoices or labels. type: array items: $ref: '#/components/schemas/ShipmentDocument' b2bConfig: type: - object - 'null' properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). templateID: type: string format: uuid description: ID of the template version used (UUID). templateKey: type: string description: Key of the template used, e.g. `amazon`. customerInput: type: string description: Values you entered for the fields of the template, keyed by field name as defined in its `customerInputSchema`. isPallet: type: boolean description: Whether the shipment is sent on pallets instead of parcels. required: - templateID description: 'B2B configuration of the shipment: the B2B template it uses and your answers to it; `null` for B2C shipments.' amazon_prime_generated_label: type: - string - 'null' readOnly: true description: Whether the shipping label of an `amazon_prime` shipment was created through Amazon rather than through a byrd carrier integration. fuelSurchargeRate: type: - object - 'null' properties: value: type: number description: Fuel surcharge amount; `0` when none applies. actual_carrier: type: - string - 'null' description: Carrier the fuel surcharge applies to; `null` when not recorded. taxFactor: type: - number - 'null' description: Tax factor applied to the fuel surcharge. currency: type: string readOnly: true description: Currency of the fuel surcharge (ISO 4217); defaults to `EUR`. additionalProperties: false readOnly: true description: Fuel surcharge applied to the shipping rate; `null` when none applies. brandingFee: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true description: Branding fee recorded on the shipment. Legacy field, usually `null`. carrierService: type: - string - 'null' readOnly: true description: Carrier service or product the shipment is sent with; `null` until a label is created. carrierShipmentID: type: - string - 'null' readOnly: true description: ID the carrier gave the shipment; `null` until a label is created. carrierTrackingNumber: type: - string - 'null' readOnly: true description: Carrier tracking number; `null` until a label is created. carrierTrackingURL: type: - string - 'null' readOnly: true description: URL of the carrier tracking page; `null` until a label is created. codFee: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true containerCode: type: - string - 'null' readOnly: true description: Code of the warehouse container the picked items are kept in until the shipment is packed. customHandling: type: - boolean - 'null' readOnly: true description: Whether the shipment is custom handled, that is processed manually outside the standard packing flow. deliveryDate: type: - string - 'null' format: date-time readOnly: true description: When the shipment was delivered to the recipient (ISO 8601); `null` until then. fragileFee: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true description: Fragile handling fee recorded on the shipment. Legacy field, usually `null`. height: type: - number - 'null' readOnly: true minimum: 0 description: Height of the packed parcel, in cm. insuranceFee: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true description: Insurance fee recorded on the shipment. Legacy field, usually `null`. length: type: - number - 'null' readOnly: true minimum: 0 description: Length of the packed parcel, in cm. otherFees: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true description: Other fees recorded on the shipment. Legacy field, usually `null`. oversizeFee: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true packagedDate: type: - string - 'null' format: date-time readOnly: true description: When the shipment was packed (ISO 8601); `null` until then. acceptedDate: type: - string - 'null' format: date-time readOnly: true description: When the carrier accepted the shipment (ISO 8601); `null` until then. packagingFee: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true description: Packaging fee recorded on the shipment. Legacy field, usually `null`. parcelID: type: - string - 'null' readOnly: true description: Unique 10-character code of the shipment in the warehouse. Depending on the processing stage it identifies the shipment itself or the box it is picked into. pickFee: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true description: Pick fee recorded on the shipment. Legacy field, usually `null`. plannedSentDay: type: - string - 'null' format: date readOnly: true description: Day the shipment is planned to be sent (ISO 8601 date). returnDate: type: - string - 'null' format: date-time readOnly: true description: When the shipment was returned (ISO 8601); `null` when it was not. sentDate: type: - string - 'null' format: date-time readOnly: true description: When the shipment was handed over to the carrier (ISO 8601); `null` until then. latestShipDate: type: - string - 'null' format: date-time readOnly: true description: Deadline by which the shipment should be sent (ISO 8601). shippingRate: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value readOnly: true description: Shipping price charged to you for the shipment; `null` until it is known. status: type: - string - 'null' readOnly: true description: 'Current status of the shipment. - `waitingForAddressValidation`: the address is being validated - `new`: created and not yet released to a warehouse - `recalled`: recalled from the warehouse, can be released again - `waitingForRelease`: being released to a warehouse - `readyForFulfillment`: released and waiting to be picked - `fulfillmentStarted`: items are being picked - `fulfillmentCompleted`: picked and being packed - `requiresLabel`: packed, a manual label is required (B2B) - `readyToLabel`: packed, the manual label was uploaded (B2B) - `readyToShip`: packed and ready for manual outbound (B2B) - `packaged`: packed and labelled - `sent`: handed over to the carrier - `delivered`: delivered to the recipient - `returnAnnounced`: a return was created for the shipment - `returned`: the return arrived at the warehouse - `deleted`: deleted' width: type: - number - 'null' readOnly: true minimum: 0 description: Width of the packed parcel, in cm. weight: type: - number - 'null' readOnly: true minimum: 0 description: Weight of the packed parcel, in kg. totalPickedUnits: type: - integer - 'null' readOnly: true description: Number of item units picked for the shipment; `null` until picking is complete. totalPickedPackagingUnits: type: - integer - 'null' readOnly: true description: Number of packaging units picked for the shipment; `null` until picking is complete. required: - destinationAddress - destinationName - packagingMaterials title: Returned shipment PickStorage: type: object properties: id: type: string format: uuid description: ID of the storage (UUID). bsid: type: string description: 'byrd storage ID: the unique code of the storage.' lot: description: Lot stored in the storage; `null` for products without lot tracking. allOf: - $ref: '#/components/schemas/PickStorageLot' shelf_identifier: type: string description: Identifier of the shelf the storage is on, for example `SH-MS-10`. type: type: integer description: 'Type of the storage location. - `10`: pallet - `20`: shelf - `0`: legacy store location, no longer used' location_id: type: string format: uuid description: ID of the storage location (UUID), as shown in the QR code on the location label. blocked_at: type: string format: date-time description: When the storage was blocked (ISO 8601, UTC); `null` when it is not blocked. title: Pick storage MinimalPaginationFields: type: object required: - page - per_page - last_page properties: page: type: integer description: Current page of results, 0-indexed per_page: type: integer description: Number of results per page last_page: type: boolean description: Whether this is the final page of results title: Minimal pagination fields ShipmentItemDangerousGoods: type: object properties: UNNumber: type: string description: UN number identifying the dangerous good. quantity: type: number description: Quantity of the dangerous good in one unit of the product, in the unit defined for its UN number. required: - UNNumber - quantity additionalProperties: false title: Shipment item dangerous goods Dimensions: type: object properties: height: type: - number - 'null' minimum: 0.1 description: Height in cm; `null` when unknown. width: type: - number - 'null' minimum: 0.1 description: Width in cm; `null` when unknown. length: type: - number - 'null' minimum: 0.1 description: Length in cm; `null` when unknown. weight: type: - number - 'null' minimum: 0.001 description: Weight in kg; `null` when unknown. title: Dimensions Shipment: type: object properties: id: type: string format: uuid readOnly: true description: ID of the shipment (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). b2b_config: readOnly: true description: 'B2B configuration of the shipment: the B2B template it uses and your answers to it; `null` for B2C shipments.' allOf: - $ref: '#/components/schemas/B2BConfig' checkpoints: readOnly: true description: Timestamps (ISO 8601, UTC) of the milestones the shipment has reached; a milestone not reached yet is `null`. allOf: - $ref: '#/components/schemas/Checkpoints' container_code: type: string description: Code of the warehouse container the picked items are kept in until the shipment is packed. customs: description: Customs details used to generate the export documents; required for international shipments. `null` when none were provided. allOf: - $ref: '#/components/schemas/Customs' destination_address: description: Address and contact details of the recipient. For deliveries to a carrier pickup point, see the pickup point guides for how to fill it. allOf: - $ref: '#/components/schemas/ShipmentDestinationAddress' errors: readOnly: true description: Errors blocking the shipment from progressing, for example a failed address validation or an allocation problem; empty when nothing is blocking it. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' insurance: description: Declared value the shipment is insured for; `null` when the shipment is not insured. allOf: - $ref: '#/components/schemas/Insurance' metrics: readOnly: true description: Item, SKU, pick and packaging-unit counts for the shipment. allOf: - $ref: '#/components/schemas/Metrics' notes: description: Free-text notes for your own use and packaging instructions for the warehouse. allOf: - $ref: '#/components/schemas/Notes' options: type: - object - 'null' properties: branding: type: - boolean - 'null' default: null description: Whether the shipment is packed with your branded packaging material; defaults to your account setting. packaging: type: - boolean - 'null' default: null description: Whether the warehouse packs the items in packaging material; defaults to your account setting. custom_handling: type: - boolean - 'null' default: false description: Whether the shipment is held for custom handling at the warehouse; it cannot be packed while this is `true`. Read-only for you. auto_release: type: - boolean - 'null' default: null description: Whether the shipment is released to a warehouse automatically once it is created; if `false` or not sent, it normally stays `new` until you release it. preferred_carrier: type: - string - 'null' default: null description: Carrier to send the shipment with, instead of the one byrd selects; see the list of carriers. Use it with caution, as a carrier that cannot serve the shipment leads to shipment errors. incoterm: type: - string - 'null' default: null description: 'Incoterm passed to the carrier for international shipments. - `DAP`: delivered at place; the recipient pays import duties and taxes (default) - `DDP`: delivered duty paid; you pay them' charge: type: string readOnly: true description: Whether byrd charges you for the shipment. fragile: type: boolean readOnly: true description: Whether the shipment contains at least one fragile product. organic: type: boolean readOnly: true description: Whether the shipment contains at least one organic product. grs: type: boolean readOnly: true description: Whether the shipment contains at least one product that complies with the Global Recycled Standard (GRS). create_return_label: type: boolean readOnly: true description: Whether a return label is created for each parcel when the shipment is released; send it together with `print_return_label`. print_return_label: type: boolean readOnly: true description: Whether the return label is printed and packed with the shipment; requires `create_return_label` to be `true`, and has to be sent together with it. economy_fallback: type: boolean readOnly: true description: Whether the shipment is sent with the `standard` service when `economy` is not available for it; set on your account. not_before_date: type: string format: date-time readOnly: true description: Earliest date the shipment may be sent (ISO 8601, at midnight); `null` when there is no such date. not_later_date: type: string format: date-time readOnly: true description: Latest date and time the shipment has to be sent by (ISO 8601); `null` when not set. pickup_date: type: string format: date readOnly: true description: Date the carrier collects the shipment (ISO 8601), for B2B shipments; `null` when not scheduled. international: type: - boolean - 'null' default: null description: Whether the shipment needs a customs declaration because it crosses a customs border; `null` until the shipment is released. has_dangerous_goods: type: boolean readOnly: true description: Whether the shipment contains at least one item classified as dangerous goods. v3_packaging: type: boolean readOnly: true description: Whether the warehouse packs the shipment with the v3 packing process. requires_export_declaration: type: string readOnly: true description: Whether the shipment has to carry an export declaration; always `false` before the shipment is released. slam_compatible: type: string readOnly: true description: Whether the warehouse can pack the shipment on its automated labelling line; `null` until the shipment is released. autobag_compatible: type: string readOnly: true description: Whether the warehouse can pack the shipment with its automatic bagging machine. partial_fulfillment: type: string readOnly: true description: Whether the shipment was split off so that part of an order could be sent while the rest waits. expired_stock_allowed: type: boolean readOnly: true description: Whether the shipment may be fulfilled with expired stock; defaults to `false`. pickup_date_from: type: string format: date readOnly: true description: First day of the window in which the shipment will be collected (ISO 8601), for B2B shipments; set with the schedule pickup endpoint. pickup_date_to: type: string format: date readOnly: true description: Last day of the window in which the shipment will be collected (ISO 8601), for B2B shipments; set with the schedule pickup endpoint. self_pickup_by_customer: type: boolean readOnly: true description: Whether you collect the shipment from the warehouse yourself instead of a carrier, for B2B shipments; set with the schedule pickup endpoint. shipping_label_mode: type: string readOnly: true description: 'How the shipping label is obtained. - `auto`: byrd creates it with the carrier - `manual`: byrd uploads it, for example for `pickup` shipments' description: Fulfilment and shipping options set on the shipment. origin: type: string readOnly: true description: 'How the shipment was created; `null` for shipments created before this was recorded. - `api`: through the API with an API key - `manual`: in the byrd dashboard - `integration`: by a byrd shop integration' byrd_id: type: string readOnly: true description: Short human-readable identifier of the shipment, shown in the dashboard and printed on warehouse documents. example: ABCD12345 priority: type: integer readOnly: true description: Picking priority in the warehouse, from 0 (normal) to 40 (highest); rises automatically once the shipping deadline is reached. `null` until the shipment is released. example: 10 return_address: readOnly: true description: Address of the fulfilling warehouse that returns are sent to; `null` until the shipment is released. allOf: - $ref: '#/components/schemas/ReturnAddress' service: type: string enum: - economy - standard - express - pickup - pickup_point description: 'Shipping service the shipment is sent with. - `standard`: regular delivery - `express`: faster delivery, picked with higher priority - `economy`: cheapest, slower delivery - `pickup_point`: delivery to a carrier pickup point - `pickup`: collected from the warehouse, not shipped' shop: description: Order references from your shop or order system, such as the order number. allOf: - $ref: '#/components/schemas/ShipmentShop' status: type: string readOnly: true description: 'Current status of the shipment. - `new`: created and not yet released to a warehouse - `releasing`: being released to a warehouse - `released`: released and waiting to be picked - `picking`: items are being picked - `packaging`: being packed - `packaged`: packed and labelled - `sent`: handed over to the carrier - `delivered`: delivered to the recipient - `returning`: a return shipment was created - `returned`: the return arrived at the warehouse - `deleted`: deleted' sub_status: type: string readOnly: true description: 'Detail on the current `status`; `null` when there is none. - `validating_address`, `address_invalid`, `recalled`: while `new` - `reserved`, `allocating`, `allocated`, `assigned`, `inbounding`, `inbound_error`: while `released` - `label_error`, `error_resolved`, `autobag_failed`: while `packaging` - `label_required`, `label_created`, `label_uploaded`, `pickup_details_required`, `pickup_details_uploaded`, `manual_outbound`, `waiting_for_pickup`, `fba_details_required`, `fba_box_label_required`, `fba_pallet_label_required`: while `packaged`, mostly for B2B shipments - `pick_up`, `in_transit`, `at_pickup_point`, `out_for_delivery`, `delayed`, `failed_delivery`: carrier tracking events while `sent` - `claim_reported`: a support claim is open, while `sent` or `delivered`' units: readOnly: true description: Physical parcels or pallets the shipment is packed into, each with its own tracking information. type: array items: $ref: '#/components/schemas/ShipmentUnitDetail' warnings: readOnly: true description: Problems that do not block the shipment, for example an address validation error on a shipment released anyway, or the reason it was recalled. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' warehouse: readOnly: true description: Warehouse fulfilling the shipment; its fields are `null` until a warehouse is assigned. allOf: - $ref: '#/components/schemas/ShipmentWarehouse' user: readOnly: true description: byrd account the shipment belongs to. allOf: - $ref: '#/components/schemas/ShipmentUser' dangerous_goods: readOnly: true description: Dangerous goods totals for the shipment. allOf: - $ref: '#/components/schemas/DGDetails' cash_on_delivery: description: Amount the carrier collects from the recipient on delivery; `null` when the shipment is not cash on delivery. allOf: - $ref: '#/components/schemas/CashOnDelivery' total_value: readOnly: true description: Total value of the items (unit price × quantity), converted to EUR. allOf: - $ref: '#/components/schemas/CashOnDeliveryPrice' packaging_materials: description: Packaging materials requested or suggested for packing the shipment. type: - array - 'null' items: $ref: '#/components/schemas/PackagingMaterials' user_id: type: string format: uuid writeOnly: true description: ID of the byrd account the shipment is created for (UUID); for your requests it is always your own account. documents: writeOnly: true description: Documents the warehouse prints and packs with the shipment, such as delivery notes or invoices. type: array items: $ref: '#/components/schemas/Document' warehouse_id: type: - string - 'null' format: uuid writeOnly: true description: ID of the warehouse that has to fulfil the shipment; if omitted, byrd assigns one automatically. warehouse_user_id: type: - string - 'null' format: uuid writeOnly: true description: ID of the warehouse worker assigned to pick the shipment. pickup_point: type: - object - 'null' default: null writeOnly: true description: Carrier pickup point to deliver to, for `pickup_point` shipments; the fields it needs depend on the carrier. additionalProperties: {} items: description: Products in the shipment and their quantities; at least one. type: array items: $ref: '#/components/schemas/Item' required: - destination_address - items title: Shipment UndefinedResponse: type: object description: Generic (expected) response when endpoint doesn't explicitly define one properties: data: type: object title: Undefined response ProductBarcode: type: object properties: value: type: string description: Value encoded in the barcode. barcode_type: description: 'Type of the barcode. - `ean_13` - `code_128` - `gs1_128` - `qr_code`' type: string enum: - ean_13 - code_128 - gs1_128 - qr_code is_primary: type: boolean description: Whether this is the product's primary barcode. title: Product barcode ReservationProduct: type: object properties: id: type: string format: uuid description: ID of the product (UUID). name: type: string description: Name of the product. sku: type: string description: Stock keeping unit (SKU) of the product, unique in your account. type: type: string description: 'Type of the product. - `product` - `alias` - `supplementary` - `marketing` - `branding` - `packaging_material` - `prepacked_product` - `bundle`' title: Reservation product IslandSurcharge: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ tax_factor: type: - number - 'null' actual_carrier: type: - string - 'null' value: type: string readOnly: true title: Island surcharge ShipmentInput: type: object properties: customs: type: - object - 'null' properties: invoice_number: type: string description: Commercial invoice number of the order, printed on the customs documents. goods_type: type: string default: other enum: - document - gift - sample - remand - other description: 'Type of goods in the shipment, declared to customs; defaults to `other`. - `document`: documents only - `gift`: a gift - `sample`: commercial samples - `remand`: goods sent back - `other`: anything else, such as sold goods' export_mrn: type: - string - 'null' maxLength: 18 description: Movement Reference Number (MRN) of the export declaration filed for the shipment, passed to the carrier; up to 18 characters. has_electronic_export_notification: type: - boolean - 'null' description: Whether an electronic export declaration was filed for the shipment; passed to the carrier. description: Customs details used to generate the export documents; required for international shipments. `null` when none were provided. destination_address: description: Address and contact details of the recipient. For deliveries to a carrier pickup point, see the pickup point guides for how to fill it. allOf: - $ref: '#/components/schemas/ShipmentUpdateDestinationAddress' documents: description: Documents the warehouse prints and packs with the shipment, such as delivery notes or invoices. type: array items: $ref: '#/components/schemas/ShipmentUpdateDocument' insurance: type: - object - 'null' properties: value: type: number description: Value of the whole shipment it is insured for, in `currency`. currency: type: string description: Currency of `value` (ISO 4217), for example `EUR`. description: Declared value the shipment is insured for; `null` when the shipment is not insured. items: minItems: 1 description: Products in the shipment and their quantities; at least one. type: array items: $ref: '#/components/schemas/ItemInput' notes: type: - object - 'null' properties: customer_note: type: - string - 'null' description: Note for your own use, shown in the dashboard; it is not sent to the recipient or shown to the warehouse. packaging_instructions: type: string readOnly: true description: Packing instructions for the warehouse, from the account settings of the customer; not taken from the request. Not returned to customers. label_error_note: type: string readOnly: true description: Instructions byrd gave the warehouse when resolving a label error on the shipment; `null` when there are none. description: Free-text notes for your own use and packaging instructions for the warehouse. options: description: Fulfilment and shipping options set on the shipment. allOf: - $ref: '#/components/schemas/ShipmentUpdateOptions' service: type: string enum: - economy - standard - express - pickup - pickup_point description: 'Shipping service the shipment is sent with. - `standard`: regular delivery - `express`: faster delivery, picked with higher priority - `economy`: cheapest, slower delivery - `pickup_point`: delivery to a carrier pickup point - `pickup`: collected from the warehouse, not shipped' shop: description: Order references from your shop or order system, such as the order number. allOf: - $ref: '#/components/schemas/ShipmentInputShop' user_id: type: string description: ID of the byrd account the shipment is created for (UUID); for your requests it is always your own account. warehouse_id: type: string description: ID of the warehouse that has to fulfil the shipment; if omitted, byrd assigns one automatically. cash_on_delivery: type: - object - 'null' properties: price: description: Total amount the carrier collects from the recipient; only `EUR` is supported. allOf: - $ref: '#/components/schemas/CashOnDeliveryPrice' description: Amount the carrier collects from the recipient on delivery; `null` when the shipment is not cash on delivery. pickup_point: type: - object - 'null' description: Carrier pickup point to deliver to, for `pickup_point` shipments; the fields it needs depend on the carrier. additionalProperties: {} packaging_materials: description: Packaging materials requested or suggested for packing the shipment. type: array items: $ref: '#/components/schemas/PackagingMaterialsInput' required: - destination_address - items title: Shipment input Insurance: type: object properties: value: type: number description: Value of the whole shipment it is insured for, in `currency`. currency: type: string description: Currency of `value` (ISO 4217), for example `EUR`. title: Insurance Customs: type: object properties: invoice_number: type: string description: Commercial invoice number of the order, printed on the customs documents. goods_type: type: string description: 'Type of goods in the shipment, declared to customs; defaults to `other`. - `document`: documents only - `gift`: a gift - `sample`: commercial samples - `remand`: goods sent back - `other`: anything else, such as sold goods' export_mrn: type: - string - 'null' description: Movement Reference Number (MRN) of the export declaration filed for the shipment, passed to the carrier; up to 18 characters. has_electronic_export_notification: type: - boolean - 'null' description: Whether an electronic export declaration was filed for the shipment; passed to the carrier. title: Customs PackagingMaterialsInput: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). code: type: string minLength: 7 maxLength: 7 description: Unique 7-character code of the packaging material; ask byrd Support for it once the warehouse has validated the material. quantity: type: integer description: Number of units of the packaging material to use. override_reason_code: type: string enum: - too_big - too_small - not_available - other description: 'Reason a different packaging material was used than the one requested. - `too_big`: it was too big for the items - `too_small`: it was too small for the items - `not_available`: it was not available - `other`: another reason, given in `override_reason_text`' override_reason_text: type: string description: Explanation of why a different packaging material was used; required when `override_reason_code` is `other`. required: type: boolean description: Whether the warehouse has to use the packaging material (`true`, default) or may use a different one (`false`); a different one is used anyway when it is out of stock. type: type: - string - 'null' description: Type of the packaging material, filled in by byrd. size: type: - string - 'null' description: Size group of the packaging material, filled in by byrd. required: - code title: Packaging materials input ReturnShipmentItemPhoto: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). url: type: string format: url description: URL of the photo. required: - url title: Return shipment item photo ShipmentItem: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). amount: type: integer minimum: 1 description: Number of units to ship; at least 1. For an item inside a bundle, the number per bundle. byrdProduct: type: object readOnly: true description: byrd product of the item, as an object holding its `id`. additionalProperties: {} byrdProductID: type: - string - 'null' format: uuid description: ID of the byrd product (UUID). Send this or `sku` to identify the product. sku: type: - string - 'null' description: SKU of the product in byrd. Send this or `byrdProductID` to identify the product. productName: type: - string - 'null' description: Name of the product. description: type: - string - 'null' description: Description of the item, used on customs documents for international shipments. customs: type: - object - 'null' properties: customsTariffNumber: type: string description: Harmonised System (HS) tariff number of the product. originCountryCode: type: string pattern: ^[A-Z]{2}$ description: Country the product originates from, as an ISO 3166-1 alpha-2 code. required: - customsTariffNumber - originCountryCode additionalProperties: false description: Customs details of the product; `null` when not provided. height: type: - number - 'null' minimum: 0 description: Height of one unit of the item, in cm. length: type: - number - 'null' minimum: 0 description: Length of one unit of the item, in cm. lotNumber: type: - string - 'null' description: Lot the product must be picked from. If not set, byrd picks by the FIFO principle. pictureID: type: - string - 'null' format: uuid variantID: type: - string - 'null' description: ID of the product variant in your shop system. weight: type: - number - 'null' minimum: 0 description: Weight of one unit of the item, in kg. width: type: - number - 'null' minimum: 0 description: Width of one unit of the item, in cm. price: type: - object - 'null' properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' readOnly: true description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value description: Retail price of one unit, used for customs documents and insurance; multiplied by `amount` on customs documents. dangerousGoods: readOnly: true description: Dangerous goods the product contains; `null` when it contains none. type: - array - 'null' items: $ref: '#/components/schemas/ShipmentItemDangerousGoods' productID: type: - string - 'null' description: ID of the product in your shop system. required: - amount title: Shipment item ReturnShipmentError: type: object properties: id: type: string readOnly: true description: ID of the error (UUID). code: type: string enum: - Warehouse.ReturnShipmentDocuments.GenerateDocuments.UnsupportedDocument - Warehouse.ReturnShipmentDocuments.GenerateDocuments.GenerationFailed - Warehouse.ReturnShipmentDocuments.GenerateDocuments.UploadFailure - Warehouse.ReturnShipmentDocuments.GenerateDocuments.InvalidStatus - Warehouse.ReturnShipmentDocuments.GenerateDocuments.AlreadyExist - Warehouse.ReturnShipmentDocuments.GenerateDocuments.DefaultError readOnly: true description: 'Code of the error. `DefaultError` stands for any error without a more specific code. - `Warehouse.ReturnShipmentDocuments.GenerateDocuments.UnsupportedDocument` - `Warehouse.ReturnShipmentDocuments.GenerateDocuments.GenerationFailed` - `Warehouse.ReturnShipmentDocuments.GenerateDocuments.UploadFailure` - `Warehouse.ReturnShipmentDocuments.GenerateDocuments.InvalidStatus` - `Warehouse.ReturnShipmentDocuments.GenerateDocuments.AlreadyExist` - `Warehouse.ReturnShipmentDocuments.GenerateDocuments.DefaultError`' additionalProperties: false title: Return shipment error TotalPrice: type: object properties: value: type: number description: Amount, as a string with two decimals separated by a dot. currency: type: string pattern: ^[A-Z]{3}$ description: Currency (ISO 4217 code, e.g. `EUR`). taxFactor: type: - number - 'null' description: Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set. required: - currency - value title: Total price ShipmentWarehouse: type: object properties: id: type: string format: uuid description: ID of the warehouse (UUID); `null` until a warehouse is assigned. code: type: string description: Short code of the warehouse. name: type: string description: Display name of the warehouse. additionalProperties: false title: Shipment warehouse Item: type: object properties: id: type: string format: uuid readOnly: true description: ID of the item line (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). product_id: type: string format: uuid description: ID of the byrd product to ship (UUID); send it or `sku`. `null` for custom bundles. quantity: type: integer description: Number of units to ship; at least 1. For items of a custom bundle, the number per bundle. name: type: string description: Name of the product; replaced by the name stored on the product. Required for custom bundles and their items. price: description: Retail price of one unit, used for customs documents and insurance; it is multiplied by `quantity`. Required for custom bundles. allOf: - $ref: '#/components/schemas/CarrierShippingRate' dimensions: description: Dimensions and weight of one unit of the product; missing values are taken from the product, and the weight stored on the product always replaces the one sent. allOf: - $ref: '#/components/schemas/Dimensions' customs: description: Customs details of the product, needed for shipments leaving the EU or the UK; taken from the product when not sent. allOf: - $ref: '#/components/schemas/ItemCustoms' lot_number: type: string description: Lot the units have to be picked from; if not sent, byrd chooses lots first in, first out (FIFO). serial_number_tracked: type: boolean readOnly: true description: Whether serial numbers are recorded for the item when it is packed; set from the serial number setting of the product. dangerous_goods: readOnly: true description: Dangerous goods classifications of the product, taken from the product; empty when it is not dangerous goods. type: array items: $ref: '#/components/schemas/ItemBaseDangerousGoods' type: type: string description: 'Type of item. - `product`: a single product (default) - `bundle`: a bundle product set up in byrd - `custom_bundle`: products packed together, listed in `children` - `supplement`: a supplementary product, such as a flyer, added because it is linked to another product in the shipment' fragile: type: boolean default: false readOnly: true description: Whether the product is fragile, as set on the product. organic: type: boolean default: false readOnly: true description: Whether the product is organic and needs special shipping conditions, as set on the product. grs: type: boolean default: false readOnly: true description: Whether the product complies with the Global Recycled Standard (GRS), as set on the product. required: type: boolean readOnly: true description: Whether the item has to be in the shipment for it to be sent; `false` for optional supplementary products, such as flyers, that can be left out. description: type: - string - 'null' description: Description of the product, used on customs documents; taken from the product when not sent. sku: type: - string - 'null' description: SKU of the byrd product to ship; send it or `product_id`. Required for custom bundles, where it has to be unique within the shipment. children: readOnly: true description: 'Items the bundle consists of; empty for other item types. Required when `type` is `custom_bundle`: list every product to pack together, including the bag or box they go in.' allOf: - $ref: '#/components/schemas/ItemBase' shop_product_id: type: - string - 'null' writeOnly: true description: ID of the product in your shop or order system; not necessarily a UUID. required: - quantity title: Item PackagingMaterials: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). code: type: string description: Unique 7-character code of the packaging material; ask byrd Support for it once the warehouse has validated the material. quantity: type: integer description: Number of units of the packaging material to use. type: type: string description: Type of the packaging material, filled in by byrd. required: type: boolean description: Whether the warehouse has to use the packaging material (`true`, default) or may use a different one (`false`); a different one is used anyway when it is out of stock. size: type: string description: Size group of the packaging material, filled in by byrd. title: Packaging materials FuelSurcharge: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ tax_factor: type: - number - 'null' actual_carrier: type: - string - 'null' value: type: string readOnly: true title: Fuel surcharge ShipmentUnit: type: object properties: id: type: string format: uuid readOnly: true description: ID of the unit (UUID). items: description: Products packed in the unit; empty for units packed before items were recorded per unit. type: array items: $ref: '#/components/schemas/UnitItem' service: type: string description: 'Shipping service the unit is sent with; usually the shipment''s `service`, but it can differ when an economy fallback applies. - `standard` - `express` - `economy` - `pickup_point` - `pickup` - `amazon_prime`' carrier: description: Carrier the unit is sent with and its tracking details; the fields are `null` until a label is created. allOf: - $ref: '#/components/schemas/Carrier' parcel_id: type: string readOnly: true description: Unique 10-character alphanumeric identifier of the unit. example: A1B2C3D4E5 type: type: string readOnly: true description: 'Kind of unit. - `parcel`: a parcel - `pallet`: a pallet' status: type: string readOnly: true description: 'Current status of the unit. - `new`: created and not yet packed and labelled - `packaged`: packed and labelled - `sent`: handed over to the carrier - `delivered`: delivered to the recipient - `returning`: being returned to the warehouse - `returned`: the return arrived at the warehouse' sub_status: type: string readOnly: true description: 'Detail on the current `status`; `null` when there is none. - `label_error`, `error_resolved`: creating the label failed, or the failure was fixed; while `new` or `packaged` - `slam_ready`, `autobag_failed`: waiting for the SLAM machine, or the bagging machine failed; while `new` - `label_required`, `label_created`, `label_uploaded`, `pickup_details_required`, `pickup_details_uploaded`, `waiting_for_pickup`, `manual_outbound`, `fba_details_required`, `fba_box_label_required`, `fba_pallet_label_required`: while `packaged`, mostly for B2B shipments - `pick_up`, `in_transit`, `at_pickup_point`, `out_for_delivery`, `delayed`, `failed_delivery`: carrier tracking events while `sent`' label_error_status: type: string readOnly: true description: 'Who byrd is waiting on to resolve the unit''s label error; `null` when there is no error or it has not been looked at yet. - `waiting_for_customer`: you have to fix or confirm something, such as the address or customs data - `waiting_for_warehouse`: the warehouse has to check the parcel - `waiting_for_carrier`: the carrier has to respond or fix something - `waiting_for_pricing`, `waiting_for_procurement`, `waiting_for_operations`, `waiting_for_engineering`: a byrd team has to act - `waiting_for_deletion`: the error will not be fixed and the unit will be deleted' checkpoints: readOnly: true description: Timestamps (ISO 8601, UTC) of the milestones the unit has reached; a milestone not reached yet is `null`. allOf: - $ref: '#/components/schemas/ShipmentUnitCheckpoint' errors: readOnly: true description: Errors blocking the unit, such as a failed label creation; empty when nothing is blocking it. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' error_code: type: string readOnly: true description: Code of the error currently blocking the unit, for example `LC00` for a carrier error; `null` when there is none. slam: type: boolean readOnly: true description: Whether the unit is measured and labelled by a SLAM (scan, label, apply, manifest) machine. autobag: type: boolean readOnly: true description: Whether the unit is packed by an automatic bagging machine. dimensions: description: Outer dimensions (cm) and weight (kg) of the packed unit. allOf: - $ref: '#/components/schemas/UnitDimensions' pregenerated: type: boolean readOnly: true description: Whether the unit and its shipping label were created in advance, before packing. packaging_materials: description: Packaging materials the unit was packed with. type: - array - 'null' items: $ref: '#/components/schemas/PackagingMaterials' group_number: type: integer readOnly: true description: Number of the packing station group whose printer printed the unit's label; `null` until the unit is labelled. title: Shipment unit DecarbonizationSurcharge: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ tax_factor: type: - number - 'null' actual_carrier: type: - string - 'null' value: type: string readOnly: true title: Decarbonization surcharge PeakSurcharge: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ tax_factor: type: - number - 'null' actual_carrier: type: - string - 'null' value: type: string readOnly: true title: Peak surcharge UnitItem: type: object properties: id: type: string format: uuid readOnly: true description: ID of the unit item (UUID). packaging_unit_id: type: - string - 'null' description: ID of the packaging unit the product was packed in (UUID); `null` when it was packed as single selling units. product: readOnly: true description: Product packed in the unit. allOf: - $ref: '#/components/schemas/UnitProduct' custom_bundle_id: type: string format: uuid description: ID of the custom bundle the item belongs to (UUID); `null` when it is not part of one. product_id: type: - string - 'null' format: uuid writeOnly: true description: ID of the product packed in the unit (UUID). serial_numbers: type: - array - 'null' description: Serial numbers of the packed items, one for each item; `null` for products without serial number tracking. items: type: string quantity: type: integer minimum: 1 description: Number packed, in packaging units when `packaging_unit_id` is set; at least 1. required: - quantity additionalProperties: false title: Unit item ReturnShipmentItemAnnounced: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). shipmentItemID: type: string format: uuid description: ID of the shipment item announced for return (UUID). amount: type: integer minimum: 1 description: Number of units announced for return; at least 1. reason: type: string description: Reason given for returning the item. required: - amount - reason title: Return shipment item announced PickPackagingUnit: type: object properties: id: type: string format: uuid description: ID of the packaging unit (UUID). quantity: type: integer description: Number of selling units the packaging unit holds; at least 2. barcode_type: description: 'Type of the packaging unit''s barcode; required when a barcode value is given. - `ean_13` - `code_128` - `gs1_128` - `qr_code`' type: string enum: - ean_13 - code_128 - gs1_128 - qr_code barcode_value: type: string description: Barcode printed on the packaging unit; at most 48 characters. title: Pick packaging unit DGDetails: type: object properties: limited_quantity_weight: type: number readOnly: true description: The total weight of the dangerous goods of type limited quantity (LQ). title: DG details Notes: type: object properties: customer_note: type: string description: Note for your own use, shown in the dashboard; it is not sent to the recipient or shown to the warehouse. label_error_note: type: string readOnly: true description: Instructions byrd gave the warehouse when resolving a label error on the shipment; `null` when there are none. title: Notes CashOnDeliveryPrice: type: object properties: value: type: number description: Amount in `currency`, with a dot as decimal separator. currency: type: string pattern: ^[A-Z]{3}$ description: Currency of `value` (ISO 4217), for example `EUR`. tax_factor: type: - number - 'null' description: Tax factor of the price; `1.0` on item prices and `null` elsewhere. Ignored on input. required: - currency - value title: Cash on delivery price Checkpoints: type: object properties: release_error_at: type: string format: date-time description: When the last attempt to release the shipment failed (ISO 8601, UTC); `null` if releasing never failed. released_at: type: string format: date-time description: When the shipment was released to the warehouse (ISO 8601, UTC). picked_at: type: string format: date-time description: When picking of the shipment's items was completed (ISO 8601, UTC). assigned_at: type: string format: date-time description: When the shipment was assigned to a warehouse worker for picking (ISO 8601, UTC). allocated_at: type: string format: date-time description: When stock was allocated to the shipment for picking (ISO 8601, UTC). packaging_started_at: type: string format: date-time description: When the warehouse started packing the shipment (ISO 8601, UTC). packaged_at: type: string format: date-time description: When the shipment was packed and labelled (ISO 8601, UTC). accepted_at: type: string format: date-time description: When the carrier first scanned the last of the shipment's units (ISO 8601, UTC); `null` until every unit was scanned. sent_at: type: string format: date-time description: When all of the shipment's units left the warehouse (ISO 8601, UTC). delivered_at: type: string format: date-time description: When the last of the shipment's units was delivered to the recipient (ISO 8601, UTC). returned_at: type: string format: date-time description: When the return of the shipment arrived at the warehouse (ISO 8601, UTC). title: Checkpoints ReturnShipmentAnnouncedInput: type: object properties: shipment_id: type: string format: uuid writeOnly: true description: ID of the shipment being returned (UUID). The shipment must be yours and must have been sent. user_id: type: string format: uuid writeOnly: true description: 'ID of the byrd account the shipment belongs to (UUID). Ignored for customer accounts: the return is always created for your own account.' send_documents_to_email: type: string format: email writeOnly: true description: Email address the return label is sent to once it is generated. Required unless `send_email` is `false`, and must be left out then. send_email: type: boolean default: true writeOnly: true description: Whether the return label is emailed once it is generated. Set it to `false` to only generate the label and download it from `documents` instead. Defaults to `true`. documents_email_language: type: string writeOnly: true maxLength: 2 description: Language of the email carrying the return label and of the label itself, as an ISO 639-1 two-letter code, for example `de`. `en`, `de` and `fr` are supported and any other value falls back to English. When `null`, the language is taken from the destination country of the shipment, falling back to English. portal_tier: type: string enum: - basic - pro writeOnly: true description: Returns Portal tier the return is announced through, `basic` or `pro`. Ignored for customer accounts. label_type: type: string enum: - byrd_label - identifier_only writeOnly: true description: 'Kind of return label generated for the return. Defaults to `byrd_label`. - `byrd_label`: carrier shipping label for `courier`. - `identifier_only`: a return slip whose cut-off strip identifies the return to the warehouse; it is not a shipping label and has no tracking number.' origin: type: string default: portal enum: - portal - dashboard - api writeOnly: true description: 'Where the return was announced. Ignored for customer accounts. - `portal`: the Returns Portal. - `dashboard`: the byrd dashboard. - `api`: the API.' items_announced: writeOnly: true description: Items of the shipment that are being returned, with their amounts; at least one. Each shipment item can be announced in only one return. type: array items: $ref: '#/components/schemas/ReturnShipmentItemAnnouncedInput' courier: type: string enum: - amazon_prime - asendia_global - brt_it - colissimo_fr - correos_es - dbschenker_global - delivengo_fr - derkurier_de - dhl_de - dhlexpress_de - dpd_at - dpd_de - dpd_gb - exporto_global - fedex_global - gls_global - mondialrelay_fr - parcelforce_gb - post_at - post_de - post_it - post_nl - royalmail_gb - schneckenpost_de - sendcloud_global - seur_es - sevensenders_global maxLength: 64 description: Carrier the return is shipped with. Must be a carrier enabled for your account, the warehouse and the destination country; ask your byrd contact person which value applies to you. required: - courier - shipment_id additionalProperties: false title: Return shipment announced input ReturnShipmentRegenerateDocumentsInput: type: object properties: send_documents_to_email: type: string format: email writeOnly: true description: Email address the regenerated return label is sent to. Used for this label only; the return keeps its own `send_documents_to_email`. Required unless `send_email` is `false`, and must be left out then. send_email: type: boolean default: true writeOnly: true description: Whether the return label is emailed once it is generated. Set it to `false` to only generate the label and download it from `documents` instead. Defaults to `true`. additionalProperties: false title: Return shipment regenerate documents input ReturnAddress: type: object properties: id: type: string format: uuid description: ID of the address (UUID). name: type: string description: Name of the warehouse that returns are sent to. street_name: type: string description: Name of the street, without the house number. city: type: string description: City. country_code: type: string description: Country (ISO 3166-1 alpha-2), for example `DE`. street_number: type: string description: House number. address_addition: type: string description: Additional address details, such as building or floor. postal_code: type: string description: Postal code. For countries with numeric postal codes, anything but digits is removed, such as a `DE-` prefix. state: type: string description: State, province or region; `null` when not needed. title: Return address ReturnShipmentItem: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). returnID: type: string format: uuid readOnly: true description: ID of the return the item belongs to (UUID). byrdProductID: type: string format: uuid description: ID of the returned product (UUID). shipmentItemID: type: string format: uuid description: ID of the shipment item that was returned (UUID); `null` when the warehouse matched the item by product only. amount: type: integer minimum: 1 description: Number of units returned; at least 1. When `packagingUnitID` is set, the number of packaging units. packagingUnitID: type: string format: uuid description: ID of the packaging unit the product came back in (UUID); `null` for single units. condition: type: string enum: - a-new - used - damaged description: 'Condition of the item as rated by the warehouse. What happens to the item next is agreed during onboarding. - `a-new`: like new, normally put back into stock - `used`: shows signs of use and cannot be resold without further steps - `damaged`: cannot be resold' internalComments: type: string description: Notes the warehouse recorded about the item. photos: description: Photos the warehouse took of the returned item. type: array items: $ref: '#/components/schemas/ReturnShipmentItemPhoto' required: - amount - byrdProductID - condition title: Return shipment item ShipmentBatch: type: object properties: shipment_ids: type: array minItems: 1 description: IDs of the shipments (UUIDs); at least one. items: type: string format: uuid required: - shipment_ids title: Shipment batch Pick: type: object properties: id: type: string format: uuid description: ID of the pick (UUID). quantity: type: integer description: Number picked, in packaging units when `packaging_unit` is set; see `total_items` for the number of items. storage: description: Storage the items are picked from, with its lot. allOf: - $ref: '#/components/schemas/PickStorage' product: description: Product picked. allOf: - $ref: '#/components/schemas/PickProduct' container_code: type: string description: Code of the warehouse container the picked items were placed in; `null` until picked. packaging_unit: description: Packaging unit picked; `null` when single selling units are picked. allOf: - $ref: '#/components/schemas/PickPackagingUnit' total_items: type: integer description: 'Number of items picked: `quantity` times the packaging unit''s quantity, or `quantity` when no packaging unit is picked.' reservation: type: boolean description: 'Whether the pick is still planned: `true` until the warehouse picks it and the stock is deducted from the storage.' shipment_id: type: string format: uuid description: ID of the shipment the pick is for (UUID). warehouse_id: type: string format: uuid description: ID of the warehouse fulfilling the shipment (UUID). zones: description: Warehouse zones the storage location belongs to; only returned when requested with `only`. type: array items: $ref: '#/components/schemas/StorageZone' title: Pick CarrierShippingRate: type: object properties: value: type: number description: Amount in `currency`, with a dot as decimal separator. currency: type: string pattern: ^[A-Z]{3}$ description: Currency of `value` (ISO 4217), for example `EUR`. tax_factor: type: - number - 'null' description: Tax factor of the price; `1.0` on item prices and `null` elsewhere. Ignored on input. required: - currency - value title: Carrier shipping rate ShipmentUnitDetail: type: object properties: id: type: string format: uuid readOnly: true description: ID of the unit (UUID). items: description: Products packed in the unit; empty for units packed before items were recorded per unit. type: array items: $ref: '#/components/schemas/UnitItem' service: type: string description: 'Shipping service the unit is sent with; usually the shipment''s `service`, but it can differ when an economy fallback applies. - `standard` - `express` - `economy` - `pickup_point` - `pickup` - `amazon_prime`' carrier: description: Carrier the unit is sent with and its tracking details; the fields are `null` until a label is created. allOf: - $ref: '#/components/schemas/Carrier' parcel_id: type: string readOnly: true description: Unique 10-character alphanumeric identifier of the unit. example: A1B2C3D4E5 type: type: string readOnly: true description: 'Kind of unit. - `parcel`: a parcel - `pallet`: a pallet' status: type: string readOnly: true description: 'Current status of the unit. - `new`: created and not yet packed and labelled - `packaged`: packed and labelled - `sent`: handed over to the carrier - `delivered`: delivered to the recipient - `returning`: being returned to the warehouse - `returned`: the return arrived at the warehouse' sub_status: type: string readOnly: true description: 'Detail on the current `status`; `null` when there is none. - `label_error`, `error_resolved`: creating the label failed, or the failure was fixed; while `new` or `packaged` - `slam_ready`, `autobag_failed`: waiting for the SLAM machine, or the bagging machine failed; while `new` - `label_required`, `label_created`, `label_uploaded`, `pickup_details_required`, `pickup_details_uploaded`, `waiting_for_pickup`, `manual_outbound`, `fba_details_required`, `fba_box_label_required`, `fba_pallet_label_required`: while `packaged`, mostly for B2B shipments - `pick_up`, `in_transit`, `at_pickup_point`, `out_for_delivery`, `delayed`, `failed_delivery`: carrier tracking events while `sent`' label_error_status: type: string readOnly: true description: 'Who byrd is waiting on to resolve the unit''s label error; `null` when there is no error or it has not been looked at yet. - `waiting_for_customer`: you have to fix or confirm something, such as the address or customs data - `waiting_for_warehouse`: the warehouse has to check the parcel - `waiting_for_carrier`: the carrier has to respond or fix something - `waiting_for_pricing`, `waiting_for_procurement`, `waiting_for_operations`, `waiting_for_engineering`: a byrd team has to act - `waiting_for_deletion`: the error will not be fixed and the unit will be deleted' checkpoints: readOnly: true description: Timestamps (ISO 8601, UTC) of the milestones the unit has reached; a milestone not reached yet is `null`. allOf: - $ref: '#/components/schemas/ShipmentUnitDetailCheckpoint' errors: readOnly: true description: Errors blocking the unit, such as a failed label creation; empty when nothing is blocking it. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' error_code: type: string readOnly: true description: Code of the error currently blocking the unit, for example `LC00` for a carrier error; `null` when there is none. slam: type: boolean readOnly: true description: Whether the unit is measured and labelled by a SLAM (scan, label, apply, manifest) machine. autobag: type: boolean readOnly: true description: Whether the unit is packed by an automatic bagging machine. dimensions: description: Outer dimensions (cm) and weight (kg) of the packed unit. allOf: - $ref: '#/components/schemas/UnitDimensions' pregenerated: type: boolean readOnly: true description: Whether the unit and its shipping label were created in advance, before packing. packaging_materials: description: Packaging materials the unit was packed with. type: - array - 'null' items: $ref: '#/components/schemas/PackagingMaterials' group_number: type: integer readOnly: true description: Number of the packing station group whose printer printed the unit's label; `null` until the unit is labelled. sequence_number: type: string readOnly: true description: Position of the unit among the shipment's units, starting at 1. metrics: readOnly: true description: Item and pick counts for the unit; `null` for units without recorded items. allOf: - $ref: '#/components/schemas/UnitMetrics' title: Shipment unit detail ItemInput: type: object properties: product_id: type: - string - 'null' format: uuid description: ID of the byrd product to ship (UUID); send it or `sku`. `null` for custom bundles. shop_product_id: type: - string - 'null' description: ID of the product in your shop or order system; not necessarily a UUID. quantity: type: integer minimum: 1 description: Number of units to ship; at least 1. For items of a custom bundle, the number per bundle. name: type: - string - 'null' description: Name of the product; replaced by the name stored on the product. Required for custom bundles and their items. price: type: - object - 'null' properties: value: type: number description: Amount in `currency`, with a dot as decimal separator. currency: type: string pattern: ^[A-Z]{3}$ description: Currency of `value` (ISO 4217), for example `EUR`. tax_factor: type: - number - 'null' description: Tax factor of the price; `1.0` on item prices and `null` elsewhere. Ignored on input. required: - currency - value description: Retail price of one unit, used for customs documents and insurance; it is multiplied by `quantity`. Required for custom bundles. dimensions: type: - object - 'null' properties: height: type: - number - 'null' minimum: 0.1 description: Height in cm; `null` when unknown. width: type: - number - 'null' minimum: 0.1 description: Width in cm; `null` when unknown. length: type: - number - 'null' minimum: 0.1 description: Length in cm; `null` when unknown. weight: type: - number - 'null' minimum: 0.001 description: Weight in kg; `null` when unknown. description: Dimensions and weight of one unit of the product; missing values are taken from the product, and the weight stored on the product always replaces the one sent. customs: type: - object - 'null' properties: origin_country_code: type: - string - 'null' pattern: ^[A-Z]{2}$ description: Country the product was made in (ISO 3166-1 alpha-2), for example `CN`. hs_tariff_number: type: - string - 'null' description: 'Harmonized System (HS) tariff number of the product: 6, 8 or 10 digits.' additionalProperties: false description: Customs details of the product, needed for shipments leaving the EU or the UK; taken from the product when not sent. lot_number: type: - string - 'null' description: Lot the units have to be picked from; if not sent, byrd chooses lots first in, first out (FIFO). description: type: - string - 'null' description: Description of the product, used on customs documents; taken from the product when not sent. sku: type: - string - 'null' description: SKU of the byrd product to ship; send it or `product_id`. Required for custom bundles, where it has to be unique within the shipment. serial_number_tracked: type: - boolean - 'null' description: Whether serial numbers are recorded for the item when it is packed; set from the serial number setting of the product. type: type: - string - 'null' description: 'Type of item. - `product`: a single product (default) - `bundle`: a bundle product set up in byrd - `custom_bundle`: products packed together, listed in `children` - `supplement`: a supplementary product, such as a flyer, added because it is linked to another product in the shipment' children: description: 'Items the bundle consists of; empty for other item types. Required when `type` is `custom_bundle`: list every product to pack together, including the bag or box they go in.' type: - array - 'null' items: $ref: '#/components/schemas/Child' required: - quantity title: Item input CashOnDelivery: type: object properties: price: description: Total amount the carrier collects from the recipient; only `EUR` is supported. allOf: - $ref: '#/components/schemas/CashOnDeliveryPrice' title: Cash on delivery StorageZone: type: object properties: id: type: string format: uuid description: ID of the warehouse zone (UUID). identifier: type: string description: Identifier of the warehouse zone. title: Storage zone ShipmentUnitDetailError: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). code: type: string description: Machine-readable code of the problem, for example `Warehouse.Shipments.Recalled.Warning`. message: type: string description: Human-readable explanation of the problem. extra: type: object description: Additional details about the problem, such as the IDs or values involved; the keys depend on `code`. additionalProperties: {} errors: type: array description: Underlying errors that caused this one, in the same format. items: type: object additionalProperties: {} title: Shipment unit detail error ShipmentListUnit: type: object properties: id: type: string format: uuid readOnly: true description: ID of the unit (UUID). items: description: Products packed in the unit; empty for units packed before items were recorded per unit. type: array items: $ref: '#/components/schemas/UnitItem' service: type: string description: 'Shipping service the unit is sent with; usually the shipment''s `service`, but it can differ when an economy fallback applies. - `standard` - `express` - `economy` - `pickup_point` - `pickup` - `amazon_prime`' carrier: description: Carrier the unit is sent with and its tracking details; the fields are `null` until a label is created. allOf: - $ref: '#/components/schemas/Carrier' parcel_id: type: string readOnly: true description: Unique 10-character alphanumeric identifier of the unit. example: A1B2C3D4E5 type: type: string readOnly: true description: 'Kind of unit. - `parcel`: a parcel - `pallet`: a pallet' status: type: string readOnly: true description: 'Current status of the unit. - `new`: created and not yet packed and labelled - `packaged`: packed and labelled - `sent`: handed over to the carrier - `delivered`: delivered to the recipient - `returning`: being returned to the warehouse - `returned`: the return arrived at the warehouse' sub_status: type: string readOnly: true description: 'Detail on the current `status`; `null` when there is none. - `label_error`, `error_resolved`: creating the label failed, or the failure was fixed; while `new` or `packaged` - `slam_ready`, `autobag_failed`: waiting for the SLAM machine, or the bagging machine failed; while `new` - `label_required`, `label_created`, `label_uploaded`, `pickup_details_required`, `pickup_details_uploaded`, `waiting_for_pickup`, `manual_outbound`, `fba_details_required`, `fba_box_label_required`, `fba_pallet_label_required`: while `packaged`, mostly for B2B shipments - `pick_up`, `in_transit`, `at_pickup_point`, `out_for_delivery`, `delayed`, `failed_delivery`: carrier tracking events while `sent`' label_error_status: type: string readOnly: true description: 'Who byrd is waiting on to resolve the unit''s label error; `null` when there is no error or it has not been looked at yet. - `waiting_for_customer`: you have to fix or confirm something, such as the address or customs data - `waiting_for_warehouse`: the warehouse has to check the parcel - `waiting_for_carrier`: the carrier has to respond or fix something - `waiting_for_pricing`, `waiting_for_procurement`, `waiting_for_operations`, `waiting_for_engineering`: a byrd team has to act - `waiting_for_deletion`: the error will not be fixed and the unit will be deleted' checkpoints: readOnly: true description: Timestamps (ISO 8601, UTC) of the milestones the unit has reached; a milestone not reached yet is `null`. allOf: - $ref: '#/components/schemas/ShipmentUnitCheckpoint' errors: readOnly: true description: Errors blocking the unit, such as a failed label creation; empty when nothing is blocking it. type: array items: $ref: '#/components/schemas/ShipmentUnitDetailError' error_code: type: string readOnly: true description: Code of the error currently blocking the unit, for example `LC00` for a carrier error; `null` when there is none. slam: type: boolean readOnly: true description: Whether the unit is measured and labelled by a SLAM (scan, label, apply, manifest) machine. autobag: type: boolean readOnly: true description: Whether the unit is packed by an automatic bagging machine. dimensions: description: Outer dimensions (cm) and weight (kg) of the packed unit. allOf: - $ref: '#/components/schemas/UnitDimensions' pregenerated: type: boolean readOnly: true description: Whether the unit and its shipping label were created in advance, before packing. packaging_materials: description: Packaging materials the unit was packed with. type: - array - 'null' items: $ref: '#/components/schemas/PackagingMaterials' group_number: type: integer readOnly: true description: Number of the packing station group whose printer printed the unit's label; `null` until the unit is labelled. sequence_number: type: string readOnly: true description: Position of the unit among the shipment's units, starting at 1. metrics: readOnly: true description: Item and pick counts for the unit; `null` for units without recorded items. allOf: - $ref: '#/components/schemas/UnitMetrics' title: Shipment list unit PickProduct: type: object properties: id: type: string format: uuid description: ID of the product (UUID). name: type: string description: Name of the product. sku: type: string description: Stock keeping unit (SKU) of the product, unique in your account. barcode: type: string description: Primary barcode of the product; see `barcodes` for all of them. barcodes: readOnly: true description: All barcodes of the product. type: array items: $ref: '#/components/schemas/ProductBarcode' type: type: string description: 'Type of the product. - `product` - `alias` - `supplementary` - `marketing` - `branding` - `packaging_material` - `prepacked_product` - `bundle`' serial_number_enabled: type: boolean readOnly: true description: Whether serial numbers of the product are recorded when it is shipped. serial_number_regex: type: - string - 'null' readOnly: true description: Regular expression the product's serial numbers must match; `null` when any value is accepted. inventory_serial_number_enabled: type: boolean readOnly: true description: Whether serial numbers of the product are tracked in stock, not only when shipping. title: Pick product ShipmentListMetrics: type: object properties: total_picks: type: string readOnly: true description: Number of picks, one for each storage location to pick from; 0 until stock is allocated. total_packaging_units: type: string readOnly: true description: Number of packaging units to pick; 0 until stock is allocated. total_items: type: string readOnly: true description: Number of physical items in the shipment; the contents of bundles are counted, the bundles themselves are not. total_non_branding_items: type: string readOnly: true description: Number of physical items in the shipment, not counting branding products such as flyers or stickers. total_skus: type: string readOnly: true description: Number of distinct products in the shipment, not counting bundles. total_pick_items: type: string readOnly: true description: Number of items the warehouse takes off the shelf; a packaging unit counts as one item. 0 until stock is allocated. title: Shipment list metrics PddpSurcharge: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ tax_factor: type: - number - 'null' actual_carrier: type: - string - 'null' value: type: string readOnly: true title: Pddp surcharge ReturnShipmentDocument: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). type: type: string description: 'Kind of document. - `printable_label`: return label to print and stick on the parcel - `qr_code`: QR code image provided by the carrier' dataType: type: string description: 'File format of the document. - `pdf`: PDF file - `png`: PNG image' required: - dataType - type title: Return shipment document UnitProduct: type: object properties: id: type: string format: uuid description: ID of the product (UUID). name: type: string readOnly: true description: Name of the product. sku: type: string readOnly: true description: Stock keeping unit (SKU) of the product, unique in your account. barcodes: readOnly: true description: All barcodes of the product. type: array items: $ref: '#/components/schemas/ProductBarcode' serial_number_enabled: type: boolean readOnly: true description: Whether serial numbers of the product are recorded when it is shipped. title: Unit product ItemsAnnounced: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). shipment_item_id: type: string format: uuid description: ID of the shipment item to return (UUID), from the `items` of the original shipment. amount: type: integer minimum: 1 description: Number of units of this item to return; at least `1` and at most the amount shipped. reason: type: string maxLength: 64 description: Why this item is being returned, as free text of up to 64 characters. example: arrived-too-late required: - amount - reason - shipment_item_id title: Items announced ShipmentUpdate: type: object properties: customs: type: - object - 'null' properties: invoice_number: type: string description: Commercial invoice number of the order, printed on the customs documents. goods_type: type: string default: other enum: - document - gift - sample - remand - other description: 'Type of goods in the shipment, declared to customs; defaults to `other`. - `document`: documents only - `gift`: a gift - `sample`: commercial samples - `remand`: goods sent back - `other`: anything else, such as sold goods' export_mrn: type: - string - 'null' maxLength: 18 description: Movement Reference Number (MRN) of the export declaration filed for the shipment, passed to the carrier; up to 18 characters. has_electronic_export_notification: type: - boolean - 'null' description: Whether an electronic export declaration was filed for the shipment; passed to the carrier. description: Customs details used to generate the export documents; required for international shipments. `null` when none were provided. destination_address: description: Address and contact details of the recipient. For deliveries to a carrier pickup point, see the pickup point guides for how to fill it. allOf: - $ref: '#/components/schemas/ShipmentUpdateDestinationAddress' documents: description: Documents the warehouse prints and packs with the shipment, such as delivery notes or invoices. type: array items: $ref: '#/components/schemas/ShipmentUpdateDocument' insurance: type: - object - 'null' properties: value: type: number description: Value of the whole shipment it is insured for, in `currency`. currency: type: string description: Currency of `value` (ISO 4217), for example `EUR`. description: Declared value the shipment is insured for; `null` when the shipment is not insured. items: minItems: 1 description: Products in the shipment and their quantities; at least one. type: array items: $ref: '#/components/schemas/ItemInput' notes: type: - object - 'null' properties: customer_note: type: - string - 'null' description: Note for your own use, shown in the dashboard; it is not sent to the recipient or shown to the warehouse. packaging_instructions: type: string readOnly: true description: Packing instructions for the warehouse, from the account settings of the customer; not taken from the request. Not returned to customers. label_error_note: type: string readOnly: true description: Instructions byrd gave the warehouse when resolving a label error on the shipment; `null` when there are none. description: Free-text notes for your own use and packaging instructions for the warehouse. options: description: Fulfilment and shipping options set on the shipment. allOf: - $ref: '#/components/schemas/ShipmentUpdateOptions' service: type: string enum: - economy - standard - express - pickup - pickup_point description: 'Shipping service the shipment is sent with. - `standard`: regular delivery - `express`: faster delivery, picked with higher priority - `economy`: cheapest, slower delivery - `pickup_point`: delivery to a carrier pickup point - `pickup`: collected from the warehouse, not shipped' shop: description: Order references from your shop or order system, such as the order number. allOf: - $ref: '#/components/schemas/ShipmentUpdateShop' user_id: type: string description: ID of the byrd account the shipment is created for (UUID); for your requests it is always your own account. warehouse_id: type: string description: ID of the warehouse that has to fulfil the shipment; if omitted, byrd assigns one automatically. cash_on_delivery: type: - object - 'null' properties: price: description: Total amount the carrier collects from the recipient; only `EUR` is supported. allOf: - $ref: '#/components/schemas/CashOnDeliveryPrice' description: Amount the carrier collects from the recipient on delivery; `null` when the shipment is not cash on delivery. pickup_point: type: - object - 'null' description: Carrier pickup point to deliver to, for `pickup_point` shipments; the fields it needs depend on the carrier. additionalProperties: {} packaging_materials: description: Packaging materials requested or suggested for packing the shipment. type: array items: $ref: '#/components/schemas/PackagingMaterialsInput' required: - destination_address - items title: Shipment update ShipmentShop: type: object properties: id: type: string description: ID of the byrd shop integration the shipment was imported from; `null` for shipments created through the API. type: type: string description: Type of the byrd shop integration the shipment was imported from; `null` for shipments created through the API. order_number: type: string description: Order number in your shop or order system, shown in the Order column of the dashboard. order_id: type: string description: Any other identifier of the order in your system; not shown in the dashboard. marketplace_order_number: type: - string - 'null' description: Order number given by the marketplace the order was sold on, when that is not the system sending the shipment, for example the Amazon order number of an order forwarded by a connected shop. Returns are labelled with it, which lets the warehouse match a return to the shipment; send it in addition to `order_number` and `order_id`. marketplace: type: - string - 'null' description: Marketplace that `marketplace_order_number` belongs to, in lower case, for example `amazon`, `ebay` or `kaufland`. If you cannot tell it reliably, leave it out rather than guess. title: Shipment shop ItemBase: type: object properties: id: type: string format: uuid readOnly: true description: ID of the item line (UUID). product_id: type: string format: uuid readOnly: true description: ID of the byrd product to ship (UUID); send it or `sku`. `null` for custom bundles. quantity: type: integer readOnly: true description: Number of units to ship; at least 1. For items of a custom bundle, the number per bundle. name: type: string readOnly: true description: Name of the product; replaced by the name stored on the product. Required for custom bundles and their items. price: readOnly: true description: Retail price of one unit, used for customs documents and insurance; it is multiplied by `quantity`. Required for custom bundles. allOf: - $ref: '#/components/schemas/CarrierShippingRate' dimensions: readOnly: true description: Dimensions and weight of one unit of the product; missing values are taken from the product, and the weight stored on the product always replaces the one sent. allOf: - $ref: '#/components/schemas/Dimensions' customs: readOnly: true description: Customs details of the product, needed for shipments leaving the EU or the UK; taken from the product when not sent. allOf: - $ref: '#/components/schemas/ItemCustoms' lot_number: type: string readOnly: true description: Lot the units have to be picked from; if not sent, byrd chooses lots first in, first out (FIFO). serial_number_tracked: type: boolean readOnly: true description: Whether serial numbers are recorded for the item when it is packed; set from the serial number setting of the product. dangerous_goods: readOnly: true description: Dangerous goods classifications of the product, taken from the product; empty when it is not dangerous goods. type: array items: $ref: '#/components/schemas/ItemBaseDangerousGoods' type: type: string description: 'Type of item. - `product`: a single product (default) - `bundle`: a bundle product set up in byrd - `custom_bundle`: products packed together, listed in `children` - `supplement`: a supplementary product, such as a flyer, added because it is linked to another product in the shipment' fragile: type: boolean default: false readOnly: true description: Whether the product is fragile, as set on the product. organic: type: boolean default: false readOnly: true description: Whether the product is organic and needs special shipping conditions, as set on the product. grs: type: boolean default: false readOnly: true description: Whether the product complies with the Global Recycled Standard (GRS), as set on the product. required: type: boolean readOnly: true description: Whether the item has to be in the shipment for it to be sent; `false` for optional supplementary products, such as flyers, that can be left out. description: type: - string - 'null' description: Description of the product, used on customs documents; taken from the product when not sent. sku: type: - string - 'null' description: SKU of the byrd product to ship; send it or `product_id`. Required for custom bundles, where it has to be unique within the shipment. title: Item base PaginationFields: type: object properties: page: type: integer description: Current page of results, 0-indexed per_page: type: integer description: Number of results per page page_count: type: integer description: Number of result pages total_count: type: integer description: Total number of results across all pages title: Pagination fields ShipmentDestinationAddress: type: object properties: id: type: string format: uuid readOnly: true description: ID of the address (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). validated: type: boolean readOnly: true description: Whether the address passed byrd address validation; `false` also when it has not been validated. name: type: string readOnly: true description: Name of the recipient, if the recipient is a person. company_name: type: string readOnly: true description: Company name of the recipient, if the recipient is a company. email: type: string readOnly: true description: Email address of the recipient; given to the carrier, which may use it to notify the recipient about the delivery. phone: type: string readOnly: true description: Phone number, with the country code where possible, for example `+49 1234567890`. For a recipient, it is given to the carrier, and characters other than digits and `+` are removed. street_name: type: string description: Name of the street, without the house number. street_number: type: string description: House number. city: type: string description: City. country_code: type: string description: Country (ISO 3166-1 alpha-2), for example `DE`. address_addition: type: string description: Additional address details, such as building or floor. postal_code: type: string description: Postal code. For countries with numeric postal codes, anything but digits is removed, such as a `DE-` prefix. state: type: string description: State, province or region; `null` when not needed. required: - country_code title: Shipment destination address Error: type: object required: - code - message - errors properties: code: type: string enum: - Authentication.AuthenticationRequired - Authentication.ExpiredJWTToken - Authentication.InvalidCredentials - Authentication.InvalidJWTToken - Authentication.LocalityRequired - Authentication.MissingPermission - Authentication.ReadOnly - Authentication.RoleNotAllowed - Authentication.UserLocked - Exception.404 - Exception.500 - Request.InvalidPagination - Request.InvalidQuery - Request.InvalidSchema - Request.NoInput - Request.ResourceNotFound message: type: string errors: type: array items: type: object description: Embedded instance of Error title: Error ShipmentUpdateOptions: type: object properties: branding: type: - boolean - 'null' default: null description: Whether the shipment is packed with your branded packaging material; defaults to your account setting. packaging: type: - boolean - 'null' default: null description: Whether the warehouse packs the items in packaging material; defaults to your account setting. auto_release: type: - boolean - 'null' default: null description: Whether the shipment is released to a warehouse automatically once it is created; if `false` or not sent, it normally stays `new` until you release it. preferred_carrier: type: - string - 'null' default: null description: Carrier to send the shipment with, instead of the one byrd selects; see the list of carriers. Use it with caution, as a carrier that cannot serve the shipment leads to shipment errors. incoterm: type: - string - 'null' default: null enum: - DAP - DDP - null description: 'Incoterm passed to the carrier for international shipments. - `DAP`: delivered at place; the recipient pays import duties and taxes (default) - `DDP`: delivered duty paid; you pay them' expired_stock_allowed: type: - boolean - 'null' default: null description: Whether the shipment may be fulfilled with expired stock; defaults to `false`. create_return_label: type: - boolean - 'null' default: null description: Whether a return label is created for each parcel when the shipment is released; send it together with `print_return_label`. print_return_label: type: - boolean - 'null' default: null description: Whether the return label is printed and packed with the shipment; requires `create_return_label` to be `true`, and has to be sent together with it. title: Shipment update options ShipmentListOptions: type: object properties: branding: type: - boolean - 'null' default: null description: Whether the shipment is packed with your branded packaging material; defaults to your account setting. packaging: type: - boolean - 'null' default: null description: Whether the warehouse packs the items in packaging material; defaults to your account setting. custom_handling: type: - boolean - 'null' default: false description: Whether the shipment is held for custom handling at the warehouse; it cannot be packed while this is `true`. Read-only for you. auto_release: type: - boolean - 'null' default: null description: Whether the shipment is released to a warehouse automatically once it is created; if `false` or not sent, it normally stays `new` until you release it. preferred_carrier: type: - string - 'null' default: null description: Carrier to send the shipment with, instead of the one byrd selects; see the list of carriers. Use it with caution, as a carrier that cannot serve the shipment leads to shipment errors. incoterm: type: - string - 'null' default: null description: 'Incoterm passed to the carrier for international shipments. - `DAP`: delivered at place; the recipient pays import duties and taxes (default) - `DDP`: delivered duty paid; you pay them' charge: type: string readOnly: true description: Whether byrd charges you for the shipment. fragile: type: boolean readOnly: true description: Whether the shipment contains at least one fragile product. organic: type: boolean readOnly: true description: Whether the shipment contains at least one organic product. grs: type: boolean readOnly: true description: Whether the shipment contains at least one product that complies with the Global Recycled Standard (GRS). create_return_label: type: boolean readOnly: true description: Whether a return label is created for each parcel when the shipment is released; send it together with `print_return_label`. print_return_label: type: boolean readOnly: true description: Whether the return label is printed and packed with the shipment; requires `create_return_label` to be `true`, and has to be sent together with it. economy_fallback: type: boolean readOnly: true description: Whether the shipment is sent with the `standard` service when `economy` is not available for it; set on your account. not_before_date: type: string format: date-time readOnly: true description: Earliest date the shipment may be sent (ISO 8601, at midnight); `null` when there is no such date. not_later_date: type: string format: date-time readOnly: true description: Latest date and time the shipment has to be sent by (ISO 8601); `null` when not set. pickup_date: type: string format: date readOnly: true description: Date the carrier collects the shipment (ISO 8601), for B2B shipments; `null` when not scheduled. international: type: - boolean - 'null' default: null description: Whether the shipment needs a customs declaration because it crosses a customs border; `null` until the shipment is released. has_dangerous_goods: type: boolean readOnly: true description: Whether the shipment contains at least one item classified as dangerous goods. v3_packaging: type: boolean readOnly: true description: Whether the warehouse packs the shipment with the v3 packing process. requires_export_declaration: type: string readOnly: true description: Whether the shipment has to carry an export declaration; always `false` before the shipment is released. slam_compatible: type: string readOnly: true description: Whether the warehouse can pack the shipment on its automated labelling line; `null` until the shipment is released. autobag_compatible: type: string readOnly: true description: Whether the warehouse can pack the shipment with its automatic bagging machine. expired_stock_allowed: type: boolean readOnly: true description: Whether the shipment may be fulfilled with expired stock; defaults to `false`. pickup_date_from: type: string format: date readOnly: true description: First day of the window in which the shipment will be collected (ISO 8601), for B2B shipments; set with the schedule pickup endpoint. pickup_date_to: type: string format: date readOnly: true description: Last day of the window in which the shipment will be collected (ISO 8601), for B2B shipments; set with the schedule pickup endpoint. self_pickup_by_customer: type: boolean readOnly: true description: Whether you collect the shipment from the warehouse yourself instead of a carrier, for B2B shipments; set with the schedule pickup endpoint. shipping_label_mode: type: string readOnly: true description: 'How the shipping label is obtained. - `auto`: byrd creates it with the carrier - `manual`: byrd uploads it, for example for `pickup` shipments' title: Shipment list options ShipmentRecall: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). reason: type: - string - 'null' default: null enum: - stock_inaccurate - stock_expired - null description: 'Reason for the recall; optional for you. - `stock_inaccurate`: the stock recorded for an item is wrong - `stock_expired`: the stock of an item has expired' reset: type: boolean default: false description: 'Whether to undo the picking and packing of a shipment the warehouse has already started on before recalling it. Reserved for byrd: requests from your account with `true` are rejected (403).' title: Shipment recall ShipmentUpdateDestinationAddress: type: object properties: name: type: - string - 'null' description: Name of the recipient, if the recipient is a person. company_name: type: - string - 'null' description: Company name of the recipient, if the recipient is a company. email: type: - string - 'null' format: email description: Email address of the recipient; given to the carrier, which may use it to notify the recipient about the delivery. phone: type: - string - 'null' description: Phone number, with the country code where possible, for example `+49 1234567890`. For a recipient, it is given to the carrier, and characters other than digits and `+` are removed. street_name: type: - string - 'null' description: Name of the street, without the house number. street_number: type: - string - 'null' description: House number. city: type: - string - 'null' description: City. country_code: type: string pattern: ^[A-Z]{2}$ description: Country (ISO 3166-1 alpha-2), for example `DE`. address_addition: type: - string - 'null' description: Additional address details, such as building or floor. postal_code: type: - string - 'null' description: Postal code. For countries with numeric postal codes, anything but digits is removed, such as a `DE-` prefix. state: type: - string - 'null' description: State, province or region; `null` when not needed. required: - country_code title: Shipment update destination address ItemCustoms: type: object properties: origin_country_code: type: string description: Country the product was made in (ISO 3166-1 alpha-2), for example `CN`. hs_tariff_number: type: - string - 'null' description: 'Harmonized System (HS) tariff number of the product: 6, 8 or 10 digits.' title: Item customs Metrics: type: object properties: total_picks: type: string readOnly: true description: Number of picks, one for each storage location to pick from; 0 until stock is allocated. total_packaging_units: type: string readOnly: true description: Number of packaging units to pick; 0 until stock is allocated. total_items: type: string readOnly: true description: Number of physical items in the shipment; the contents of bundles are counted, the bundles themselves are not. total_non_branding_items: type: string readOnly: true description: Number of physical items in the shipment, not counting branding products such as flyers or stickers. total_skus: type: string readOnly: true description: Number of distinct products in the shipment, not counting bundles. total_unread_notifications: type: string readOnly: true description: Number of notifications about the shipment and its units that you have not read yet. title: Metrics SchedulePickup: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). self_pickup: type: boolean default: false description: Whether you collect the shipment from the warehouse yourself instead of a carrier; defaults to `false`. carrier: type: - string - 'null' description: Name of the carrier collecting the shipment; `null` if not known. carrier_tracking_url: type: - string - 'null' format: url description: Tracking URL from the carrier collecting the shipment; `null` if there is none. carrier_tracking_number: type: - string - 'null' description: Tracking number from the carrier collecting the shipment; `null` if there is none. pickup_date_from: type: string format: date x-minimum: '2026-09-24' description: First day the shipment can be collected (ISO 8601); today or later. pickup_date_to: type: string format: date x-minimum: '2026-09-24' description: Last day the shipment can be collected (ISO 8601); today or later, and also used as the planned sent date. required: - pickup_date_from - pickup_date_to title: Schedule pickup Document: type: object properties: id: type: string format: uuid description: ID of the document (UUID). Send it to change an existing document; leave it out to add a new one. created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). data_type: type: string description: 'File format of the document: `pdf`, `pdfb64` (base64-encoded PDF), `pdfurl`, `zpl`, `epl` or `jpeg`. Required for a new document; use `pdf` for documents you upload.' print_copies: type: integer description: Number of copies the warehouse prints automatically and packs with the shipment, from 0 to 10; defaults to 0 (not printed). format: type: string description: 'Printer the document is printed on: `document` (A4 paper) or `label` (label printer). Required when `print_copies` is greater than 0.' internal: type: boolean readOnly: true description: Whether byrd generated the document (`true`) or it was uploaded (`false`). last_printed_at: type: string format: date-time readOnly: true description: When the document was last printed (ISO 8601); `null` if it has not been printed. url: type: - string - 'null' format: url writeOnly: true description: URL the document is downloaded from when it is printed, on an HTTP or FTP server without authentication. Required for a new document. name: type: string minLength: 4 maxLength: 64 pattern: ^[a-zA-Z0-9_\-]*$ description: 'Name of the document: 4 to 64 characters, only letters, digits, `_` and `-` (no spaces).' meta: type: object description: Additional data about the document, such as the carrier, tracking number and tracking URL of a shipping or return label; the keys depend on `type`. additionalProperties: {} type: description: Type of document. Documents you upload to be printed use `consignment_note`, `delivery_note`, `export_document`, `proforma_invoice`, `supplement` or `other`; documents byrd creates use other types, such as `shipping_label`, `return_label`, `commercial_invoice` or `customs_cn23`. type: string enum: - amazon_fba - amazon_fba_box_label - amazon_fba_pallet_label - batch_packaging_summary - customs_cn22 - customs_cn23 - commercial_invoice - consignment_note - delivery_note - dhl_export_declaration_label - export_document - generic_large_label - other - pickup_confirmation - pickup_confirmation_template - proforma_invoice - proof_of_delivery - return_label - shipping_label - sku_relabelling - supplement - byrd_label - sequence_number_label - return_slip unit_id: type: string description: ID of the unit (parcel) the document belongs to (UUID); `null` for documents that belong to the whole shipment. required: - name - type title: Document ShipmentBatchRelease: type: object properties: shipment_ids: type: array minItems: 1 description: IDs of the shipments (UUIDs); at least one. items: type: string format: uuid warehouse_id: type: - string - 'null' format: uuid description: ID of the warehouse that has to fulfil the shipment; if omitted, byrd assigns one automatically. required: - shipment_ids title: Shipment batch release ShipmentUser: type: object properties: company_name: type: string description: Company name of the byrd account. first_name: type: string description: First name of the byrd account holder. id: type: string format: uuid readOnly: true description: ID of the byrd account (UUID). last_name: type: string description: Last name of the byrd account holder. sender_name: type: string description: Sender name printed on shipping labels and used in tracking emails; if empty, `company_name` is used. title: Shipment user ReturnShipmentItemAnnouncedInput: type: object properties: shipment_item_id: type: string format: uuid writeOnly: true description: ID of the shipment item to return (UUID), from the `items` of the original shipment. amount: type: integer minimum: 1 description: Number of units of this item to return; at least `1` and at most the amount shipped. reason: type: string maxLength: 64 description: Why this item is being returned, as free text of up to 64 characters. example: arrived-too-late required: - amount - reason - shipment_item_id additionalProperties: false title: Return shipment item announced input ReturnShipmentUnit: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). parcelID: type: string readOnly: true description: Unique code of the parcel in the warehouse. title: Return shipment unit Child: type: object properties: product_id: type: - string - 'null' format: uuid description: ID of the byrd product to ship (UUID); send it or `sku`. `null` for custom bundles. shop_product_id: type: - string - 'null' description: ID of the product in your shop or order system; not necessarily a UUID. quantity: type: integer minimum: 1 description: Number of units to ship; at least 1. For items of a custom bundle, the number per bundle. name: type: - string - 'null' description: Name of the product; replaced by the name stored on the product. Required for custom bundles and their items. price: type: - object - 'null' properties: value: type: number description: Amount in `currency`, with a dot as decimal separator. currency: type: string pattern: ^[A-Z]{3}$ description: Currency of `value` (ISO 4217), for example `EUR`. tax_factor: type: - number - 'null' description: Tax factor of the price; `1.0` on item prices and `null` elsewhere. Ignored on input. required: - currency - value description: Retail price of one unit, used for customs documents and insurance; it is multiplied by `quantity`. Required for custom bundles. dimensions: type: - object - 'null' properties: height: type: - number - 'null' minimum: 0.1 description: Height in cm; `null` when unknown. width: type: - number - 'null' minimum: 0.1 description: Width in cm; `null` when unknown. length: type: - number - 'null' minimum: 0.1 description: Length in cm; `null` when unknown. weight: type: - number - 'null' minimum: 0.001 description: Weight in kg; `null` when unknown. description: Dimensions and weight of one unit of the product; missing values are taken from the product, and the weight stored on the product always replaces the one sent. customs: type: - object - 'null' properties: origin_country_code: type: - string - 'null' pattern: ^[A-Z]{2}$ description: Country the product was made in (ISO 3166-1 alpha-2), for example `CN`. hs_tariff_number: type: - string - 'null' description: 'Harmonized System (HS) tariff number of the product: 6, 8 or 10 digits.' additionalProperties: false description: Customs details of the product, needed for shipments leaving the EU or the UK; taken from the product when not sent. lot_number: type: - string - 'null' description: Lot the units have to be picked from; if not sent, byrd chooses lots first in, first out (FIFO). description: type: - string - 'null' description: Description of the product, used on customs documents; taken from the product when not sent. sku: type: - string - 'null' description: SKU of the byrd product to ship; send it or `product_id`. Required for custom bundles, where it has to be unique within the shipment. serial_number_tracked: type: - boolean - 'null' description: Whether serial numbers are recorded for the item when it is packed; set from the serial number setting of the product. type: type: - string - 'null' description: 'Type of item. - `product`: a single product (default) - `bundle`: a bundle product set up in byrd - `custom_bundle`: products packed together, listed in `children` - `supplement`: a supplementary product, such as a flyer, added because it is linked to another product in the shipment' required: - quantity title: Child UnitDimensions: type: object properties: height: type: number minimum: 1 description: Height of the packed unit in cm; at least 1. width: type: number minimum: 1 description: Width of the packed unit in cm; at least 1. length: type: number minimum: 1 description: Length of the packed unit in cm; at least 1. weight: type: number minimum: 0.01 description: Weight of the packed unit in kg; at least 0.01. title: Unit dimensions B2BConfig: type: object properties: id: type: string format: uuid description: ID of the B2B configuration (UUID). created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). template_key: type: string readOnly: true description: Key of the B2B template (processing standard) the shipment uses. exchanged_pallets: type: integer readOnly: true description: Number of pallets exchanged with the carrier at pickup. template_id: type: string format: uuid description: ID of the B2B template to use (UUID); see the list of B2B config templates. customer_input: type: string description: Your values for the fields the B2B template asks for, in the structure given by its `customerInputSchema`. is_pallet: type: boolean description: Whether the shipment is sent on pallets (`true`) or as parcels (`false`); defaults to `false`. required: - customer_input - template_id title: B2B config Carrier: type: object properties: name: type: string tracking_number: type: string tracking_url: type: string is_tracked: type: boolean shipment_id: type: string shipping_rate: $ref: '#/components/schemas/CarrierShippingRate' byrd_shipping_rate: $ref: '#/components/schemas/CarrierShippingRate' fuel_surcharge_rate: $ref: '#/components/schemas/FuelSurcharge' peak_surcharge_rate: $ref: '#/components/schemas/PeakSurcharge' decarbonization_surcharge_rate: $ref: '#/components/schemas/DecarbonizationSurcharge' pddp_surcharge_rate: $ref: '#/components/schemas/PddpSurcharge' remote_area_surcharge_rate: $ref: '#/components/schemas/RemoteAreaSurcharge' island_surcharge_rate: $ref: '#/components/schemas/IslandSurcharge' sub_carrier_name: type: string sub_carrier_tracking_number: type: string sub_carrier_tracking_url: type: string sub_carrier_shipment_id: type: string title: Carrier ShipmentInputShop: type: object properties: type: type: string description: Type of the byrd shop integration the shipment was imported from; `null` for shipments created through the API. order_number: type: string description: Order number in your shop or order system, shown in the Order column of the dashboard. order_id: type: string description: Any other identifier of the order in your system; not shown in the dashboard. marketplace_order_number: type: string description: Order number given by the marketplace the order was sold on, when that is not the system sending the shipment, for example the Amazon order number of an order forwarded by a connected shop. Returns are labelled with it, which lets the warehouse match a return to the shipment; send it in addition to `order_number` and `order_id`. marketplace: type: string description: Marketplace that `marketplace_order_number` belongs to, in lower case, for example `amazon`, `ebay` or `kaufland`. If you cannot tell it reliably, leave it out rather than guess. title: Shipment input shop ShipmentDocument: type: object properties: id: type: string format: uuid readOnly: true description: ID of the record (UUID). createdAt: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updatedAt: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). name: type: string minLength: 4 maxLength: 64 pattern: ^[a-zA-Z0-9_\-]*$ description: 'File name of the document, without extension: 4 to 64 letters, digits, `_` or `-`; no spaces.' dataType: type: string enum: - pdf - pdfb64 - zpl - epl description: 'File format of the document. - `pdf`: PDF file - `pdfb64`: PDF file encoded as base64 - `zpl`: ZPL label for thermal printers - `epl`: EPL label for thermal printers' type: description: Type of the document, for example `shipping_label`, `delivery_note`, `commercial_invoice` or `proforma_invoice`. type: string enum: - amazon_fba - amazon_fba_box_label - amazon_fba_pallet_label - customs_cn22 - customs_cn23 - commercial_invoice - consignment_note - delivery_note - other - proforma_invoice - return_label - shipping_label - supplement - export_document - pickup_confirmation - pickup_confirmation_template - byrd_label - sequence_number_label - return_slip - generic_large_label - batch_packaging_summary - sku_relabelling - dhl_export_declaration_label - proof_of_delivery url: type: string format: url writeOnly: true description: 'URL the document is downloaded from when it is printed: an HTTP or FTP server without authentication. Write-only.' toBePrinted: type: boolean description: Whether the warehouse prints the document automatically when packing the shipment. copies: type: integer minimum: 0 maximum: 10 description: Number of copies printed automatically when the shipment is packed, from 0 to 10; above 0 when `toBePrinted` is `true`. outputType: type: string enum: - document - label - '' description: 'Format the document is printed in; required when `toBePrinted` is `true`. Send an empty string to unset it. - `document`: printed on a regular (A4) printer - `label`: printed on a label printer' meta: type: object readOnly: true description: Additional information byrd keeps about the document; its content depends on the document type. additionalProperties: {} required: - dataType - name - type - url title: Shipment document ShipmentUpdateDocument: type: object properties: id: type: string format: uuid description: ID of the document (UUID). Send it to change an existing document; leave it out to add a new one. created_at: type: string format: date-time readOnly: true description: When the record was created (ISO 8601). updated_at: type: string format: date-time readOnly: true description: When the record was last changed (ISO 8601). data_type: type: string description: 'File format of the document: `pdf`, `pdfb64` (base64-encoded PDF), `pdfurl`, `zpl`, `epl` or `jpeg`. Required for a new document; use `pdf` for documents you upload.' print_copies: type: integer default: 0 description: Number of copies the warehouse prints automatically and packs with the shipment, from 0 to 10; defaults to 0 (not printed). format: type: string description: 'Printer the document is printed on: `document` (A4 paper) or `label` (label printer). Required when `print_copies` is greater than 0.' url: type: string format: url description: URL the document is downloaded from when it is printed, on an HTTP or FTP server without authentication. Required for a new document. name: type: string minLength: 4 maxLength: 64 pattern: ^[a-zA-Z0-9_\-]*$ description: 'Name of the document: 4 to 64 characters, only letters, digits, `_` and `-` (no spaces).' meta: type: object description: Additional data about the document, such as the carrier, tracking number and tracking URL of a shipping or return label; the keys depend on `type`. additionalProperties: {} type: description: Type of document. Documents you upload to be printed use `consignment_note`, `delivery_note`, `export_document`, `proforma_invoice`, `supplement` or `other`; documents byrd creates use other types, such as `shipping_label`, `return_label`, `commercial_invoice` or `customs_cn23`. type: string enum: - amazon_fba - amazon_fba_box_label - amazon_fba_pallet_label - batch_packaging_summary - customs_cn22 - customs_cn23 - commercial_invoice - consignment_note - delivery_note - dhl_export_declaration_label - export_document - generic_large_label - other - pickup_confirmation - pickup_confirmation_template - proforma_invoice - proof_of_delivery - return_label - shipping_label - sku_relabelling - supplement - byrd_label - sequence_number_label - return_slip internal: type: boolean description: Whether byrd generated the document (`true`) or it was uploaded (`false`). required: - name - type title: Shipment update document parameters: SortBy: name: sort_by in: query description: The model field to sort results by schema: type: string Fields: name: fields in: query description: Model fields to search through; comma separated schema: type: array items: type: string description: Fields are comma separated explode: false required: false Page: name: page in: query description: Result page to jump to, 0-indexed schema: type: integer default: 0 minimum: 0 PerPage: name: per_page in: query description: Number of results per page schema: type: integer default: 250 minimum: 1 SortOrder: name: sort_order in: query description: The direction of result sorting schema: type: string enum: - asc - desc Query: name: q in: query description: The search term schema: type: string responses: Empty: description: Empty response content Error: content: application/json: schema: $ref: '#/components/schemas/Error' description: Generic error response Undefined: content: application/json: schema: $ref: '#/components/schemas/UndefinedResponse' description: Generic success response securitySchemes: tokenAuth: type: http scheme: bearer bearerFormat: JWT description: Authorization with previously obtained JSON Web Token x-provenance: method: searched source: https://developers.getbyrd.com/reference harvested: '2026-10-14' tool: harvest-readme-openapi.py note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored. assembled_from: - https://developers.getbyrd.com/reference/authapiv2_get.md - https://developers.getbyrd.com/reference/b2bconfigapi_get.md - https://developers.getbyrd.com/reference/b2bconfigtemplateapi_get.md - https://developers.getbyrd.com/reference/bundledetailsapi_delete.md - https://developers.getbyrd.com/reference/bundledetailsapi_get.md - https://developers.getbyrd.com/reference/bundlelistapi_get.md - https://developers.getbyrd.com/reference/bundlelistapi_post.md - https://developers.getbyrd.com/reference/bundlelistapi_put.md - https://developers.getbyrd.com/reference/dangerousgoodsunitlimitsapi_get.md - https://developers.getbyrd.com/reference/deliveriesapi_get.md - https://developers.getbyrd.com/reference/deliveriesapi_post.md - https://developers.getbyrd.com/reference/deliveryapi_delete.md - https://developers.getbyrd.com/reference/deliveryapi_get.md - https://developers.getbyrd.com/reference/deliveryapi_patch.md - https://developers.getbyrd.com/reference/deliveryapi_put.md - https://developers.getbyrd.com/reference/deliverydocumentapi_delete.md - https://developers.getbyrd.com/reference/deliverydocumentapi_patch.md - https://developers.getbyrd.com/reference/deliverydocumentsapi_get.md - https://developers.getbyrd.com/reference/deliverydocumentsapi_post.md - https://developers.getbyrd.com/reference/deliveryitemapi_get.md - https://developers.getbyrd.com/reference/deliverylistcountapiv3_get.md - https://developers.getbyrd.com/reference/deliverylotsapi_get.md - https://developers.getbyrd.com/reference/inventoryexportapi_get.md - https://developers.getbyrd.com/reference/loginapiv2_post.md - https://developers.getbyrd.com/reference/lotdetailapi_get.md - https://developers.getbyrd.com/reference/lotdetailapi_patch.md - https://developers.getbyrd.com/reference/lotlistapi_get.md - https://developers.getbyrd.com/reference/lotlistapi_post.md - https://developers.getbyrd.com/reference/picklistapiv3_get.md - https://developers.getbyrd.com/reference/productapi_delete.md - https://developers.getbyrd.com/reference/productapi_get.md - https://developers.getbyrd.com/reference/productapi_patch.md - https://developers.getbyrd.com/reference/productapi_put.md - https://developers.getbyrd.com/reference/productsapi_get.md - https://developers.getbyrd.com/reference/productsapi_post.md - https://developers.getbyrd.com/reference/productserialnumbersapi_get.md - https://developers.getbyrd.com/reference/productstatsapi_get.md - https://developers.getbyrd.com/reference/productstockbywarehouseapi_get.md - https://developers.getbyrd.com/reference/refreshtokenapi_post.md - https://developers.getbyrd.com/reference/returnsexportapi_get.md - https://developers.getbyrd.com/reference/returnshipmentannouncedapiv3_post.md - https://developers.getbyrd.com/reference/returnshipmentdetailapi_get.md - https://developers.getbyrd.com/reference/returnshipmentdocumentsapiv3_post.md - https://developers.getbyrd.com/reference/returnshipmentlistapi_get.md - https://developers.getbyrd.com/reference/schedulepickupapiv3_post.md - https://developers.getbyrd.com/reference/shipmentaddressvalidationapiv3_post.md - https://developers.getbyrd.com/reference/shipmentapiv3_delete.md - https://developers.getbyrd.com/reference/shipmentapiv3_get.md - https://developers.getbyrd.com/reference/shipmentapiv3_patch.md - https://developers.getbyrd.com/reference/shipmentbatchrecallapiv3_post.md - https://developers.getbyrd.com/reference/shipmentbatchreleaseapiv3_post.md - https://developers.getbyrd.com/reference/shipmentdocumentfileapiv3_get.md - https://developers.getbyrd.com/reference/shipmentdocumentsbatchapiv3_get.md - https://developers.getbyrd.com/reference/shipmentdocumentsbatchapiv3_post.md - https://developers.getbyrd.com/reference/shipmentexportapi_get.md - https://developers.getbyrd.com/reference/shipmentlistapiv3_get.md - https://developers.getbyrd.com/reference/shipmentlistapiv3_post.md - https://developers.getbyrd.com/reference/shipmentlistcountapiv3_get.md - https://developers.getbyrd.com/reference/shipmentpicklistapiv3_get.md - https://developers.getbyrd.com/reference/shipmentrecallapiv3_post.md - https://developers.getbyrd.com/reference/shipmentreportapiv3_get.md - https://developers.getbyrd.com/reference/shipmentreservationlistapiv3_get.md - https://developers.getbyrd.com/reference/shipmentunitapiv3_get.md - https://developers.getbyrd.com/reference/unitlistapiv3_get.md - https://developers.getbyrd.com/reference/unitlistcountapiv3_get.md - https://developers.getbyrd.com/reference/userapiv2_patch.md - https://developers.getbyrd.com/reference/userwarehouselinksapi_get.md - https://developers.getbyrd.com/reference/warehouseapi_get.md - https://developers.getbyrd.com/reference/warehousesapi_get.md merge: pages: 69 deduped: 601 conflicts_kept_first: 0