Get a shipment

GET/v2/api/store/{team_slug}/v2/shipment/{unique_key}

v2Operation ID v2_public_shipment_show

A shipment sends some or all of a sales order's (or quote's) lines to one address, by one shipping type. One order can have many shipments. Each shipment line points at an order line with a quantity, or is a shipping cost line; packages hold the labels and tracking numbers.

Returns the shipment with its lines (items), packages (shipment_packages) and shipping estimates (shipment_estimates): order and customer, shipping type, Ship To as shipping_address_id plus the full address in shipping_address (null when none), the receiver contact as receiver_contact_id only (read it with Get a contact by id), ready_to_ship (every job of its lines is Completed), status_id plus the full status object, external_mutation_source (which side may change a Shopify shipment), notes, cost_total and billable_fee_total as { value, dp } pairs, and pdf links (packing slip and shipment labels; they carry their own access token).

scoped_id reads back as SHIP-<number>.

Permission

Any member of the team.

Path parameters

• team_slugstringrequired

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

  • Example your-team
• unique_keystringrequired

  The shipment's id (a hash id), as its answers show it. Its unique key (shp_...) also works, but API answers don't include it.

  • Example MQyJUnd3oty75h

Request body

This operation takes no request body.

Response

200Successful response.

• dataobjectrequired

  A shipment.

  Child fields (43)

  • billable_fee_totaldecimal pair

    Shipping cost lines (what is billed), at the stored scale (4 decimal places). A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

    • See Money and quantities.
  • cost_totaldecimal pair

    Shipping cost lines (the cost), at the stored scale (4 decimal places). A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

    • See Money and quantities.
  • customerobject | null

    The customer (the full customer record).

    Child fields (2)

    • idstring

      The customer.

    • namestring
  • customer_due_datestring (date-time) | null

    The order's customer due date. ISO 8601 with offset, or null.

  • customer_idstring | null

    The customer.

  • customer_po_numberstring | null
  • customer_profile_idstring | null

    The brand profile printed on the documents.

  • delivery_notesstring | null
  • external_idsarray of objects

    The shipment's links to external systems (a Shopify fulfillment); usually empty.

  • external_mutation_sourcestring

    Who may change a Shopify shipment: shopify means it is managed in Shopify and locked here; unknown on non-Shopify orders.

    • One of: "shopify", "yoprint", "broken_link", "unknown"
  • external_typestring | null
  • from_legacyboolean
  • has_third_party_fulfilled_itemsboolean
  • idstring

    The shipment.

  • internal_notesstring | null
  • is_externalboolean | integer | null
  • is_validboolean

    Has lines, a shipping type, an address, and the order's customer.

  • itemsarray of objects

    The lines.

    Fields of each item (16)

    • _metaobject

      Read-only details of the line.

    • auto_invoice_managedboolean
    • billable_fee_totaldecimal pair

      Shipping cost lines only: what is billed (after override, markup or margin); pricing.product_cost.total is the cost. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

      • See Money and quantities.
    • external_idsarray of objects

      Links to external systems; usually empty.

    • external_typestring | null
    • from_legacyboolean
    • idstring

      The shipment line.

    • is_externalboolean
    • lock_versioninteger

      Returned but not checked on shipment lines.

    • positioninteger
    • pricingobject

      For system, _meta.unit_price is the order line's unit price and _meta.subtotal is that price × this shipment line's quantity (_meta.total is always 0); for shipment_cost, product_cost has override (always true for lines saved through the API), total (the cost), pricing_mode and pricing_mode_total (decimal pairs at 6 decimal places).

      Child fields (1)

      • typestring
        • One of: "system", "shipment_cost"
    • productobject
      Child fields (3)

      • _metaobject

        Read-only details; for order_item, parent describes the order line.

      • propertiesobject

        For order_item, id is the order line; for shipment_cost, name, description, shipment_package_id, shipment_estimate_id.

      • typestring
        • One of: "order_item", "shipment_cost"
    • quantityobject
      Child fields (2)

      • typestring
        • Always "unit"
      • totaldecimal pair

        The quantity. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

        • See Money and quantities.
    • shipment_idstring

      The shipment.

    • typestring

      Same as product.type.

    • weightobject

      The order line's weight (_meta.total, _meta.unit).

  • last_sync_sourcestring | null
  • lock_versioninteger
  • order_external_idsarray of objects

    The order's links to external systems.

  • order_external_typestring | null
  • order_idstring

    The order.

  • order_object_typestring | null
  • order_quoteboolean
  • order_scoped_idstring | null

    The order number.

  • packed_bystring | null

    Who packed it.

  • pdfarray of objects

    The packing slip and the shipment label in Letter, 4" x 6" and 1" x 2-1/8" sizes (is_custom absent), then one entry per enabled custom shipment PDF template (label, type, description, url, the show_in_* flags, is_custom: true).

    Fields of each item (5)

    • descriptionstring
    • is_customboolean

      True on custom template entries.

    • labelstring
    • object_typestring
    • urlstring

      A download link with its own access token.

  • ready_to_shipboolean

    Every job of its lines is in a Completed status.

  • receiver_contact_idstring | null

    The receiver contact.

  • scoped_idstring

    The shipment number with its prefix. Update a shipment takes only the digits.

  • ship_due_datestring (date-time) | null

    The order's ship-by date. ISO 8601 with offset, or null.

  • ship_to_statusstring
    • One of: "okay", "empty", "diff_from_order", "diff_from_customer"
  • shipment_estimatesarray of objects

    The saved shipping estimates.

    Fields of each item (22)

    • created_atstring (date-time)
    • frontend_dataobject | array

      What you sent as frontend_data; an empty list [] when you sent none.

    • frontend_data_versionany

      What you sent, or null.

    • goshippo_selected_rate_idstring | null

      The rate chosen when it was saved.

    • goshippo_shipment_idstring | null

      The Shippo shipment.

    • idstring

      The estimate.

    • order_idstring

      The order.

    • order_object_typestring | null
    • order_quoteboolean
    • order_scoped_idstring | null
    • shipment_idstring

      The shipment.

    • shipment_scoped_idstring | null
    • shippo_address_fromobject
    • shippo_address_toobject
    • shippo_carrier_accountsarray of strings
    • shippo_extraany

      The label options, or null.

    • shippo_object_idstring | null
    • shippo_parcelsarray of objects
    • shippo_ratesarray of objects

      Every rate of that Shippo shipment, as saved (amount is a decimal string).

      Fields of each item (19)

      • amountstring
      • amount_localstring
      • arrives_bystring | null
      • attributesarray of strings

        Shippo's tags, for example CHEAPEST.

      • carrier_accountstring
      • currencystring
      • currency_localstring
      • duration_termsstring | null
      • estimated_daysinteger | null
      • included_insurance_pricestring | null
      • messagesarray of objects
      • object_createdstring
      • object_idstring

        The rate id. Send it as rate_id to buy this label.

      • object_updatedstring
      • providerstring
      • provider_image_200string
      • provider_image_75string

        A URL of the carrier logo.

      • servicelevelobject

        Exactly these four keys; null when Shippo sends no service level.

        Child fields (4)

        • extended_tokenstring
        • namestring
        • termsstring
        • tokenstring
      • shipmentstring

        The Shippo shipment this rate belongs to.

    • shippo_shipment_datestring | null
    • shippo_statusstring | null
    • typestring
  • shipment_packagesarray of objects

    The packages.

    Fields of each item (36)

    • chargesinteger | number | string | null

      The label cost. For a multi-parcel label every package repeats the rate's full amount: read the master's value and don't add packages up. Null for external labels. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • created_atstring (date-time)
    • from_addressany

      The address record behind from_address_id, or null when it is not set.

    • from_address_idstring | null

      Older packages only: the ship-from address record; null otherwise.

    • goshippoobject

      Shippo labels only: the Shippo details (shipment, rate, carrier, addresses, parcels).

      Child fields (13)

      • address_fromany

        The ship-from address sent to Shippo.

      • address_returnany

        The return address sent to Shippo.

      • address_toany

        The ship-to address sent to Shippo.

      • carrier_idstring | null

        The Shippo carrier account.

      • parcel_idstring | null

        The Shippo parcel.

      • parcelsany

        The parcels of the Shippo shipment.

      • providerstring | null
      • provider_image_200string | null
      • provider_image_75string | null
      • provider_tracking_numberstring | null
      • rate_idstring | null

        The Shippo rate bought.

      • shipment_dataany

        The Shippo shipment the rate came from.

      • shipment_idstring | null

        The Shippo shipment.

    • heightnumber | string | null

      Parcel size and weight as stored, in length_unit and weight_unit. Null for external labels.

    • idstring

      The package.

    • is_masterboolean

      The first package of a label (the others have parent_id).

    • lengthnumber | string | null
    • length_unitstring | null

      Shippo labels only, upper case.

    • order_external_idsarray of objects

      The order's links to external systems.

    • order_external_typestring | null

      shopify when the order came from Shopify.

    • order_idstring

      The order.

    • order_object_typestring | null
    • order_quoteboolean
    • order_scoped_idstring | null
    • parent_idstring | null

      The master package, for the other parcels of a multi-parcel label.

    • pdfarray of objects

      Not on external labels: the label file. label and description are fixed texts that always say 4 x 6, whatever your label size setting.

      Fields of each item (3)

      • descriptionstring
      • labelstring
      • urlstring

        For a Shippo label, Shippo's signed link to the label file: don't publish it.

    • provider_namestring | null

      The carrier.

    • provider_saturday_deliveryboolean

      Shippo labels only (absent on external labels); always false today.

    • provider_service_codestring | null

      For external labels, ups, fedex or other. For Shippo labels it may be null: read the service from provider_service_name.

    • provider_service_namestring | null
    • provider_shipment_idstring | null

      The Shippo transaction id (Shippo labels).

    • provider_tracking_numberstring | null
    • shipment_external_typestring | null

      shopify when the shipment is linked to Shopify.

    • shipment_has_third_party_fulfilled_itemsboolean
    • shipment_idstring

      The shipment.

    • shipment_scoped_idstring
    • shipment_shopify_syncany

      Shopify sync state of the shipment.

    • statusstring
      • One of: "pending", "ready-to-ship", "shipped", "delivered"
    • to_addressany

      The address record behind to_address_id, or null when it is not set.

    • to_address_idstring | null

      Older packages only: the ship-to address record; null otherwise.

    • typestring

      goshippo a label bought through Shippo; external_label a label recorded from elsewhere.

      • One of: "goshippo", "external_label", "single_label"
    • weightnumber | string | null
    • weight_unitstring | null

      Shippo labels only, upper case.

    • widthnumber | string | null
  • shipping_addressobject | null

    Ship To, the full address, always included (null when none).

    Child fields (10)

    • address1string | null
    • address2string | null
    • citystring | null
    • countrystring | null
    • country_codestring | null
    • idstring

      The address.

    • labelstring | null
    • postcodestring | null
    • statestring | null
    • state_codestring | null
  • shipping_address_idstring | null

    Ship To.

  • shipping_type_idstring | null

    The shipping type.

  • shopify_syncany

    Shopify sync state, for Shopify shipments.

  • statusobject | null

    The shipment status, always included.

    Child fields (9)

    • colorstring | null

      Hex color.

    • customer_labelstring
    • idstring

      The status.

    • labelstring
    • pipeline_idstring

      Only on the statuses of a task preset (role pipeline): the task preset. Absent on other statuses.

    • positioninteger

      Its place in the team's list: sort by it to find the next status.

    • rolestring

      Which list it belongs to: job for job statuses, pipeline for the statuses of a task preset.

      • One of: "order", "quote", "job", "purchase_order", "shipment", "customer_message", "pipeline"
    • trashedboolean

      The status was deleted.

    • typestring

      The kind of status: start (Pending), pre_production and in_progress (In Progress), end (Completed).

      • One of: "start", "pre_production", "in_progress", "end"
  • status_idstring | null

    The shipment status.

  • typestring | null
  • versioninteger
• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

• 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

• 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

  When

  The shipment isn't your team's.

  Fix

  Use an id from the order's shipment list or Filter shipments.

Notes

• Very old shipments (version 1) come back in the old shipment shape, without the v2 includes.

Related

• PUTUpdate a shipment/v2/api/store/{team_slug}/v2/shipment/{unique_key}
• GETList the lines of a shipment/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item
• GETList the packages of a shipment/v2/api/store/{team_slug}/v2/shipment/{hash_id}/packages
• GETList the shipments of a sales order/v2/api/store/{team_slug}/v2/sales_order/{unique_key}/shipment

Example request

curl

curl 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1'

Example response 200

Response

{
  "data": {
    "billable_fee_total": {
      "dp": 4,
      "value": 124000
    },
    "cost_total": {
      "dp": 4,
      "value": 124000
    },
    "customer": {
      "id": "ifAHmADekGZ6id",
      "name": "Northwind Apparel"
    },
    "customer_id": "ifAHmADekGZ6id",
    "customer_profile_id": null,
    "delivery_notes": "Leave at the loading dock.",
    "external_ids": [],
    "external_mutation_source": "unknown",
    "external_type": null,
    "from_legacy": false,
    "has_third_party_fulfilled_items": false,
    "id": "MQyJUnd3oty75h",
    "internal_notes": null,
    "is_external": false,
    "is_valid": true,
    "items": [
      {
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "u8mEG7LHUtS55s",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 100,
        "pricing": {
          "_meta": {
            "subtotal": {
              "dp": 0,
              "value": 300
            },
            "total": {
              "dp": 0,
              "value": 0
            },
            "unit_price": {
              "dp": 6,
              "value": 12500000
            }
          },
          "type": "system"
        },
        "product": {
          "_meta": {
            "parent": {
              "product_name": "Gildan 5000 T-shirt"
            }
          },
          "properties": {
            "id": "ZJTJ2uF5dMiArL"
          },
          "type": "order_item"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 24
          },
          "type": "unit"
        },
        "shipment_id": "MQyJUnd3oty75h",
        "type": "order_item",
        "weight": {
          "type": "use_system"
        }
      },
      {
        "auto_invoice_managed": false,
        "billable_fee_total": {
          "dp": 6,
          "value": 12400000
        },
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "bLpxVNJLniZ4dm",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 900,
        "pricing": {
          "product_cost": {
            "override": true,
            "pricing_mode": "none",
            "pricing_mode_total": {
              "dp": 6,
              "value": 0
            },
            "total": {
              "dp": 6,
              "value": 12400000
            }
          },
          "type": "shipment_cost"
        },
        "product": {
          "properties": {
            "description": null,
            "name": "USPS Ground Advantage",
            "shipment_estimate_id": null,
            "shipment_package_id": "o6foWpSAayc79D"
          },
          "type": "shipment_cost"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 1
          },
          "type": "unit"
        },
        "shipment_id": "MQyJUnd3oty75h",
        "type": "shipment_cost"
      }
    ],
    "last_sync_source": null,
    "lock_version": 1730000000000000,
    "order_external_ids": [],
    "order_external_type": null,
    "order_id": "sFbALVSYD55eXe",
    "order_object_type": "sales_order",
    "order_quote": false,
    "order_scoped_id": "SO1001",
    "packed_by": null,
    "pdf": [
      {
        "description": "Packing slip with white labeling",
        "label": "Packing Slip",
        "object_type": "shipment",
        "url": "https://example.com/pdf/packing-slip.pdf"
      }
    ],
    "ready_to_ship": false,
    "receiver_contact_id": null,
    "scoped_id": "SHIP-12",
    "ship_to_status": "okay",
    "shipment_estimates": [
      {
        "created_at": "2026-11-03T15:00:00+00:00",
        "frontend_data": [],
        "frontend_data_version": null,
        "goshippo_selected_rate_id": "rate_0001",
        "goshippo_shipment_id": "shipment_0001",
        "id": "tVjoZLKlSwZFF5",
        "order_id": "sFbALVSYD55eXe",
        "order_object_type": "sales_order",
        "order_quote": false,
        "order_scoped_id": "SO1001",
        "shipment_id": "MQyJUnd3oty75h",
        "shipment_scoped_id": "SHIP-12",
        "shippo_address_from": {
          "city": "Austin",
          "company": "",
          "country": "US",
          "email": "",
          "name": "Northwind Apparel",
          "phone": "+1 201 555 0123",
          "state": "TX",
          "street1": "100 Example Street",
          "street2": "",
          "zip": "78701"
        },
        "shippo_address_to": {
          "city": "Denver",
          "company": "",
          "country": "US",
          "email": "alex@example.com",
          "name": "Alex Rivera",
          "phone": "",
          "state": "CO",
          "street1": "100 Example Street",
          "street2": "",
          "zip": "80202"
        },
        "shippo_carrier_accounts": [],
        "shippo_extra": null,
        "shippo_object_id": "shipment_0001",
        "shippo_parcels": [
          {
            "distance_unit": "in",
            "height": "4",
            "length": "12",
            "mass_unit": "lb",
            "weight": "2",
            "width": "10"
          }
        ],
        "shippo_rates": [
          {
            "amount": "12.40",
            "amount_local": "12.40",
            "arrives_by": null,
            "attributes": [
              "CHEAPEST"
            ],
            "carrier_account": "carrier_0001",
            "currency": "USD",
            "currency_local": "USD",
            "duration_terms": "Delivery in 2 to 5 days.",
            "estimated_days": 3,
            "included_insurance_price": null,
            "messages": [],
            "object_created": "2026-11-03T15:00:00Z",
            "object_id": "rate_0001",
            "object_updated": "2026-11-03T15:00:00Z",
            "provider": "USPS",
            "provider_image_200": "https://example.com/usps_200.png",
            "provider_image_75": "https://example.com/usps_75.png",
            "servicelevel": {
              "extended_token": "usps_ground_advantage",
              "name": "Ground Advantage",
              "terms": "",
              "token": "usps_ground_advantage"
            },
            "shipment": "shipment_0001"
          }
        ],
        "shippo_shipment_date": "2026-11-03T15:00:00Z",
        "shippo_status": "SUCCESS",
        "type": "integration_shippo"
      }
    ],
    "shipment_packages": [
      {
        "charges": 12400,
        "created_at": "2026-11-03T15:00:00+00:00",
        "goshippo": {
          "parcels": [
            {
              "distance_unit": "in",
              "height": "4",
              "length": "12",
              "mass_unit": "lb",
              "weight": "2",
              "width": "10"
            }
          ],
          "provider": "USPS",
          "rate_id": "rate_0001"
        },
        "height": "4",
        "id": "o6foWpSAayc79D",
        "is_master": true,
        "length": "12",
        "length_unit": "IN",
        "order_id": "sFbALVSYD55eXe",
        "order_object_type": "sales_order",
        "order_quote": false,
        "order_scoped_id": "SO1001",
        "parent_id": null,
        "pdf": [
          {
            "description": "Postage label individually to be printed 4\" x 6\" label",
            "label": "Postage Label (4 in x 6 in label)",
            "url": "https://example.com/labels/o6foWpSAayc79D.pdf"
          }
        ],
        "provider_name": "USPS",
        "provider_saturday_delivery": false,
        "provider_service_code": null,
        "provider_service_name": "Ground Advantage",
        "provider_shipment_id": "transaction_0001",
        "provider_tracking_number": "9400100000000000000000",
        "shipment_has_third_party_fulfilled_items": false,
        "shipment_id": "MQyJUnd3oty75h",
        "shipment_scoped_id": "SHIP-12",
        "status": "pending",
        "type": "goshippo",
        "weight": "2",
        "weight_unit": "LB",
        "width": "10"
      }
    ],
    "shipping_address": {
      "address1": "100 Example Street",
      "address2": null,
      "city": "Austin",
      "country": "United States",
      "country_code": "US",
      "id": "117KfwwfreX15N",
      "label": "Main office",
      "postcode": "78701",
      "state": "Texas",
      "state_code": "TX"
    },
    "shipping_address_id": "117KfwwfreX15N",
    "shipping_type_id": "6OTWtTOpYcBz8q",
    "status": {
      "color": "#9e9e9e",
      "customer_label": "Pending",
      "id": "AvY6ZbnrTJqpUI",
      "label": "Pending",
      "position": 1,
      "role": "shipment",
      "trashed": false,
      "type": "start"
    },
    "status_id": "AvY6ZbnrTJqpUI",
    "version": 2
  },
  "status": 200,
  "success": true
}