Update a shipment

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

v2Operation ID v2_public_shipment_update

Changes a shipment's number, shipping type, address, receiver contact, brand profile, packer and notes. Send only what you change; returns the shipment.

This doesn't change the shipment's status (use Change the status of a shipment), its lines, packages or totals. A shipment that is Completed or has labels can still be edited.

Permission

Needs permission to edit the shipment's order: the team owner, a role whose Manage Sales Orders permission is "update all", or "update assigned" when you created the order or are assigned to it, or, on a draft order, its creator when their role can create sales orders. Otherwise 403 user_is_not_authorized. Reading needs only team membership.

Business rules

An id of 0 or below is refused: "Choose a valid shipping address." (and the same for the other ids).
Only the listed fields can be cleared with null; elsewhere null means "not sent".
On a shipment linked to Shopify, changes are refused with 422 shopify_managed_shipment_locked, shopify_fulfilled_shipment_locked or shopify_broken_link_shipment_locked; on an order deleted in Shopify with shopify_order_deleted_externally.
On a Shopify order the address and receiver contact can't change: 422 shopify_shipment_snapshot_update_boundary.
An externally synced shipment on a draft order can't be updated: "Publish this order before updating an externally synced shipment."
Choosing Fulfill By Shopify on a shipment not managed by Shopify: 422 shopify_system_shipping_type_read_only.
Ids are not checked against your records: an address, contact, brand profile, user or shipping type that isn't yours (or isn't the order customer's) is saved as given. Read them from the order's customer and your settings first.

Side effects

Saves the fields; no totals change. Open Admin Portal pages refresh, and so do Customer Portal pages the order's customer has open. No webhook or email is sent.

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

application/json, required.

customer_idstring
Ignored: the shipment's customer is always the order's.
customer_profile_idstring | null
The brand profile whose details print on the documents. Null clears it.
delivery_notesstring | null
Notes for delivery. Null clears them.
internal_notesstring | null
Internal notes. Null clears them.
packed_bystring | null
The user who packed it. Null clears it.
receiver_contact_idstring | null
The receiver contact. Null clears it.
scoped_idstring
The shipment number without the SHIP- prefix, as a string. Not checked for duplicates. Don't echo the SHIP-... value you read.
shipping_address_idstring | null
The ship-to address. Null clears it.
shipping_type_idstring
The shipping type. Can't be cleared. Fulfill By Shopify is reserved for Shopify shipments.

Response

200Successful response.

dataobjectrequired
A shipment.
Child fields (40)
- 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.
- 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"
- 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.
When
Your role can't edit this order.
Fix
Ask the team owner to adjust your role or assign you to the order.
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
Check the id.
422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
When
Validation (validation_failed) or a Shopify rule (see rules).
Fix
Fix the named field or make the change in Shopify.

GETGet a shipment/v2/api/store/{team_slug}/v2/shipment/{unique_key}
PUTChange the status of a shipment/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/shipment/{id}/status
GETList shipping methods/v1/api/store/{team_slug}/setting/shipping_type

Example request

curl

curl -X PUT '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' \  -H 'Content-Type: application/json' \  -d '{    "delivery_notes": "Leave at the loading dock.",    "shipping_address_id": "117KfwwfreX15N",    "shipping_type_id": "6OTWtTOpYcBz8q"  }'

Example response 200

{
  "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,
    "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",
    "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
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com