# Update a shipment

When shipment details change in your e-comm platform, update the shipment in Onward.

Endpoint: PATCH /shipments/{shopShipmentId}
Version: 1.0.0
Security: api_key

## Security:

  - `api_key` (unknown)
    apiKey in header X-API-Key

## Path parameters:

  - `shopShipmentId` (string, required)
    Your unique ID for the Shipment (the same shop_shipment_id you sent when creating it)

## Header parameters:

  - `Content-Type` (string, required)
    Content-Type must be application/json

  - `Accept` (string, required)
    Accept must be application/json

## Request fields (application/json):

  - `shop_shipment_id` (string, required)
    Your unique identifier for the Shipment. Must be unique across your shipments and stable over time — Onward uses it to look up and de-duplicate shipments, so the same value must always refer to the same shipment.
    Example: 3712

  - `shop_order_id` (string, required)
    Your ID for the Order this Shipment relates to. Must match the shop_order_id of an existing Order.
    Example: 18282

  - `tracking_number` (string, required)
    Courier tracking number
    Example: 780371515850

  - `tracking_url` (string)
    URL to courier tracking page
    Example: https://www.fedex.com/wtrk/track/?trknbr=780371515850

  - `tracking_company` (string, required)
    Courier name
    Example: DHL Express

  - `line_items` (array, required)
    The order line items included in this shipment

  - `line_items.shop_line_item_id` (string, required)
    Your identifier for the Line Item. Must be unique within its Order and stable over time — Onward uses it to look up and de-duplicate line items within an order, so the same value must always refer to the same line item.
    Example: 816721

  - `line_items.shop_product_id` (string, required)
    Your identifier for the product. This is a reference to the product, not a unique per-line-item value — the same product ID will recur across every line item (and order) for that product.
    Example: 142

  - `line_items.shop_variant_id` (string, required)
    Your identifier or SKU for the variant. This is a reference to the variant, not a unique per-line-item value — the same variant ID will recur across every line item (and order) for that variant.
    Example: 7261

  - `line_items.name` (string, required)
    Name for the product and variant purchased
    Example: Cool T-shirt - Red

  - `line_items.unit_price` (object, required)
    Item price in order's currency

  - `line_items.unit_price.cents` (integer, required)
    Example: 1299

  - `line_items.unit_price.currency` (string, required)
    Currency code (ISO 4217)
    Example: USD

  - `line_items.total_price` (object, required)
    Line item total in order's currency

  - `line_items.total_price_presentment` (object)
    Line item total in customer's currency

  - `line_items.quantity` (integer, required)
    Example: 2

  - `line_items.image_url` (string)
    URL to an image of the item
    Example: https://placecats.com/neo/300/200.png

  - `line_items.grams` (integer, required)
    Weight of the item in grams
    Example: 24

  - `line_items.is_protected` (boolean, required)
    Whether the item is covered by Onward protection. Required on every line item; send false for line items that are not being protected, including the protection fee line itself. Requires purchase token and amount protected in the Order. Use `requires_shipping` to say whether the item ships.
    Example: true

  - `line_items.requires_shipping` (boolean)
    Whether the item is physically shipped. Items that don't ship can't be claimed and aren't shown in packages on the Customer Hub. When omitted, defaults to the value of `is_protected`, so send it on every order create and update that includes the item; an update that omits it resets the item to `is_protected`.
    Example: true

  - `line_items.refunded_quantity` (integer, required)
    Number of items refunded (for full or partial refunds)
    Example: 1

  - `line_items.refunded_price` (object, required)
    Total refunded amount in order's currency

  - `line_items.refunded_price_presentment` (object)
    Total refunded amount in customer's currency

  - `created_at` (string, required)
    When the shipment was created in your e-comm platform. Must be a valid ISO 8601 / RFC 3339 timestamp. Send it in UTC with a trailing `Z` (as in the example); timezone offsets such as `-08:00` are also accepted.
    Example: 2024-11-26T17:32:28Z

## Response 200:

  - `200` (unknown)
    Shipment updated successfully

## Response 200 fields (application/json):

  - `shop_shipment_id` (string, required)
    Your unique identifier for the Shipment. Must be unique across your shipments and stable over time — Onward uses it to look up and de-duplicate shipments, so the same value must always refer to the same shipment.
    Example: 3712

  - `shop_order_id` (string, required)
    Your ID for the Order this Shipment relates to. Must match the shop_order_id of an existing Order.
    Example: 18282

  - `tracking_number` (string, required)
    Courier tracking number
    Example: 780371515850

  - `tracking_url` (string)
    URL to courier tracking page
    Example: https://www.fedex.com/wtrk/track/?trknbr=780371515850

  - `tracking_company` (string, required)
    Courier name
    Example: DHL Express

  - `line_items` (array, required)
    The order line items included in this shipment

  - `line_items.shop_line_item_id` (string, required)
    Your identifier for the Line Item. Must be unique within its Order and stable over time — Onward uses it to look up and de-duplicate line items within an order, so the same value must always refer to the same line item.
    Example: 816721

  - `line_items.shop_product_id` (string, required)
    Your identifier for the product. This is a reference to the product, not a unique per-line-item value — the same product ID will recur across every line item (and order) for that product.
    Example: 142

  - `line_items.shop_variant_id` (string, required)
    Your identifier or SKU for the variant. This is a reference to the variant, not a unique per-line-item value — the same variant ID will recur across every line item (and order) for that variant.
    Example: 7261

  - `line_items.name` (string, required)
    Name for the product and variant purchased
    Example: Cool T-shirt - Red

  - `line_items.unit_price` (object, required)
    Item price in order's currency

  - `line_items.unit_price.cents` (integer, required)
    Example: 1299

  - `line_items.unit_price.currency` (string, required)
    Currency code (ISO 4217)
    Example: USD

  - `line_items.total_price` (object, required)
    Line item total in order's currency

  - `line_items.total_price_presentment` (object)
    Line item total in customer's currency

  - `line_items.quantity` (integer, required)
    Example: 2

  - `line_items.image_url` (string)
    URL to an image of the item
    Example: https://placecats.com/neo/300/200.png

  - `line_items.grams` (integer, required)
    Weight of the item in grams
    Example: 24

  - `line_items.is_protected` (boolean, required)
    Whether the item is covered by Onward protection. Required on every line item; send false for line items that are not being protected, including the protection fee line itself. Requires purchase token and amount protected in the Order. Use `requires_shipping` to say whether the item ships.
    Example: true

  - `line_items.requires_shipping` (boolean)
    Whether the item is physically shipped. Items that don't ship can't be claimed and aren't shown in packages on the Customer Hub. When omitted, defaults to the value of `is_protected`, so send it on every order create and update that includes the item; an update that omits it resets the item to `is_protected`.
    Example: true

  - `line_items.refunded_quantity` (integer, required)
    Number of items refunded (for full or partial refunds)
    Example: 1

  - `line_items.refunded_price` (object, required)
    Total refunded amount in order's currency

  - `line_items.refunded_price_presentment` (object)
    Total refunded amount in customer's currency

  - `created_at` (string, required)
    When the shipment was created in your e-comm platform. Must be a valid ISO 8601 / RFC 3339 timestamp. Send it in UTC with a trailing `Z` (as in the example); timezone offsets such as `-08:00` are also accepted.
    Example: 2024-11-26T17:32:28Z

## Response 400:

  - `400` (unknown)
    Request body could not be parsed as JSON.

## Response 400 fields (application/json):

  - `errors` (array, required)
    A list of parser errors describing why the request body could not be parsed.

## Response 401:

  - `401` (unknown)
    API key missing or invalid. Provide a valid `X-Api-Key` header.

## Response 401 fields (application/json):

  - `error` (string, required)
    A short, human-readable description of the authentication failure.
    Example: Unauthorized

## Response 404:

  - `404` (unknown)
    Shipment not found

## Response 422:

  - `422` (unknown)
    Validation exception

## Response 422 fields (application/json):

  - `errors` (array, required)
    Array of errors. Each error contains the field in the beginning followed by the issue found.