Skip to content
YoPrintDevelopers

Add a line to a shipment

Open .md

POST/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item

v2Operation ID v2_public_shipment_item_create

Adds one line to a shipment and recalculates it. Returns the line in an action envelope (action_performed CREATED, has_changes, lock_version, item).

product.type What it is
order_item Ships a quantity of a line of the same order (any kind of product line, or a fee).
shipment_cost A shipping cost line (Shipping Cost in the web app), with its own price, optionally tied to a package or an estimate.

Numbers are { value, dp } pairs: value is the number without its decimal point and dp the count of decimal places, so 12.50 is { "value": 1250, "dp": 2 } (or { "value": 125, "dp": 1 }). value is a JSON integer or a digit string, never a float: 12.5 is refused. Quantities take up to 8 decimal places; shipping costs and a pricing mode's rate take 6. More significant decimals than that are a 422, not rounded. Send very large numbers as strings. Answers send prices at the stored scale (6 decimal places), quantities without trailing zeros, and _meta.subtotal (price × quantity) at the combined scale, compacted when it would exceed a safe integer: always read dp.

Nothing caps the quantity at what was ordered: shipping more marks the order line over-allocated.

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

  • product.type is order_item or shipment_cost only; the order line kinds (db_catalog and so on) are refused with "The selected product.type is invalid."
  • An order line can be on a shipment once: 422 cart_item_validation_error "Shipment already has the same Order Item".
  • The order line must be on the shipment's order and shippable; otherwise 422 with a bare { "message": "order_item: ..." }.
  • A shipping cost line's package or estimate must belong to this shipment. A second cost line for the same package returns the first with action_performed NONE.
  • A Shopify shipment that is locked (managed by Shopify or already fulfilled there) or has a broken Shopify link takes no new lines: 422 validation_error "Cannot create Shopify-synced shipment item from API." An externally synced shipment on a draft order: "Publish this order before creating an externally synced shipment item."
  • Fields that aren't listed are dropped, and a null counts as not sent (except shipment_package_id and shipment_estimate_id).

Side effects

  • Recalculates the shipment's cost and billable fee totals and the order's shipping totals.
  • Updates each order line's shipped status (not allocated, partly, fully or over-allocated).
  • On an Auto Invoice order, shipping cost lines are mirrored as shipping fees on the managed invoice.
  • 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.

What are you adding?

Send one of these 2 bodies.

Order lineShipping cost

Order line

Ships a quantity of a line of the same order.

  • productobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "order_item"
    • propertiesobjectrequired
      Child fields (1)
      • idstringrequired

        The order line's id (a hash id). It must be on the shipment's order, shippable, and not already on this shipment.

  • quantityobjectrequired

    How many to ship. Not negative; may be more than ordered (the line then shows as over-allocated).

    Child fields (2)
    • typestringrequired
      • Always "unit"
    • totaldecimal pairrequired

      The quantity, up to 8 decimal places.

      • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
  • positionintegerrequired

    Where the line sits on the shipment; lower comes first.

  • pricingobject

    Optional; the price always comes from the order line.

    Child fields (1)
    • typestring
      • Always "system"

Example request

curl
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/item' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "position": 100,    "product": {      "properties": {        "id": "ZJTJ2uF5dMiArL"      },      "type": "order_item"    },    "quantity": {      "total": {        "dp": 0,        "value": 24      },      "type": "unit"    }  }'

Shipping cost

A shipping cost line with its own cost.

  • pricingobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "shipment_cost"
    • product_costobjectrequired
      Child fields (2)
      • pricing_modestringrequired

        Send none: the price billed is the cost. See the notes for the other values.

        • One of: "none", "override", "markup", "margin"
      • totaldecimal pair

        The cost, up to 6 decimal places. Missing means 0.

        • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
  • productobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "shipment_cost"
    • propertiesobjectrequired
      Child fields (4)
      • namestringrequired
      • descriptionstring
      • shipment_estimate_idstring | null

        A shipping estimate of this shipment the cost comes from.

      • shipment_package_idstring | null

        A package of this shipment the cost is for. One live cost line per package: a second create returns the existing line.

  • positionintegerrequired
  • quantityobject

    Optional and not used in the totals.

Example request

curl
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/item' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "position": 900,    "pricing": {      "product_cost": {        "pricing_mode": "none",        "total": {          "dp": 2,          "value": 1240        }      },      "type": "shipment_cost"    },    "product": {      "properties": {        "name": "USPS Ground Advantage",        "shipment_package_id": "o6foWpSAayc79D"      },      "type": "shipment_cost"    }  }'

Response

200Successful response.

  • dataobjectrequired

    What happened, and the line.

    Child fields (5)
    • object_typestring
      • Always "shipment_item"
    • action_performedstring

      NONE when nothing changed.

      • One of: "CREATED", "UPDATED", "DELETED", "NONE"
    • has_changesboolean
    • itemobject

      A shipment line.

      Child fields (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.

      • 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.

      • shipment_idstring

        The shipment.

      • typestring

        Same as product.type.

      • weightobject

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

    • lock_versionobject

      Lock versions after the change.

      Child fields (2)
      • orderobject

        The order's lock versions: job_lock_version, invoice_lock_version, order_item_lock_version, shipment_lock_version, payment_lock_version, order_lock_version.

      • shipmentobject

        The shipment's lock versions: shipment_item_lock_version, shipment_lock_version.

  • 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 business rule (cart_item_validation_error, or a bare message).
    Fix
    Read the message and fix the line.

Notes

  • A shipping cost line's pricing_mode override, markup and margin are accepted, but the API can't pass their rate: override bills 0 and the others bill the cost. Use none and set the cost you want to bill.

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 specSupport: support@yoprint.comyoprint.com