Save a shipping estimate

POST/v2/api/store/{team_slug}/v2/shipment/{hash_id}/shipment_estimate/goshippo

v2Operation ID v2_public_shipment_estimate_create_goshippo

Saves a Shippo rate quote on a YoPrint shipment, as a shipping estimate. Nothing is bought.

Get rates first, then send the reply's top-level object_id as goshippo_shipment_id, and the rate you picked as goshippo_selected_rate_id. YoPrint reads that Shippo shipment back and stores it with all its rates. Returns the estimate (shippo_rates, shippo_address_from, shippo_parcels, ...).

An estimate is a quote you can show or bill for. Buying the label is a separate call that takes a rate id; you can pass the estimate's id there as shipment_estimate_id, only to link the label's shipping cost line to it.

Permission

Any member of the team. No sales order permission is checked. Needs a connected, enabled Shippo integration (Settings > Integrations > Shippo Shipping). Without one the reply is 422 goshippo_not_enabled with no message.

Business rules

• Works on shipments of quotes and sales orders, in any status.
• Each call adds a new estimate; sending the same ids twice saves two.

Side effects

• Reads the Shippo shipment (it buys nothing) and saves an estimate. Open Admin Portal pages refresh.

Path parameters

• team_slugstringrequired

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

  • Example your-team
• hash_idstringrequired

  The shipment's hash id (id). Hash ids only: a unique key or a document number gives 404.

  • Example MQyJUnd3oty75h

Request body

application/json, required.

• goshippo_shipment_idstringrequired

  The top-level object_id from Get shipping rates.

• frontend_dataobject

  Your own data to keep with the estimate (the web app stores its form here).

• frontend_data_versionany

  Required with frontend_data: your format version for it.

• goshippo_selected_rate_idstring

  The rates[].object_id you chose. Not checked against the shipment.

Response

200Successful response.

• dataobjectrequired

  A saved shipping estimate.

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

  Check the shipment 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

  Shippo rejected the shipment id (Shippo answered 400): validation_error, "The shipping rate could not be loaded. Get shipping rates again and choose a rate before saving." Other Shippo failures, possibly including an unknown id, are a 500.

  Fix

  Get rates again and send the new object_id.

  When

  goshippo_shipment_id is missing, or frontend_data is sent without frontend_data_version.

  Fix

  Send the required fields.

  When

  Shippo isn't connected or is disabled (goshippo_not_enabled).

  Fix

  Connect Shippo in the web app first.

• 500A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as action_not_allowed; an unexpected failure answers {"message": "Server Error"}. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.

  When

  Shippo refused the request or could not be reached. Shippo errors are not translated into 4xx replies.

  Fix

  Check the addresses, parcels and ids, then retry once. Do not loop.

Related

• POSTGet shipping rates/v2/api/store/{team_slug}/v2/shipment_rate/goshippo
• GETList the shipping estimates of a shipment/v2/api/store/{team_slug}/v2/shipment/{hash_id}/estimates
• POSTBuy a shipping label (charges your Shippo account)/v2/api/store/{team_slug}/v2/shipment/{hash_id}/label/goshippo

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/shipment_estimate/goshippo' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "goshippo_selected_rate_id": "rate_0001",    "goshippo_shipment_id": "shipment_0001"  }'

Example response 200

Response

{
  "data": {
    "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"
  },
  "status": 200,
  "success": true
}