Skip to main content

​
How does it work?

Using the Shippo API works exactly the same with a Platform Account as it did with your Shippo account before, except you will be making API calls for your customers instead of for yourself. To make an API call for your customer’s Shippo Account, add their Shippo Account ID to the header of the call with the key value pair SHIPPO-ACCOUNT-ID: <ShippoAccountID>.
NoteThis is different from making authorized API calls on behalf of your customers through an OAuth integration. In an OAuth integration, the experience is co-branded where your customers manage their own Shippo Accounts and have a direct billing relationship with Shippo. With a Platform Account integration, you fully manage your customers’ Shippo Accounts behind the scenes and they do not need to have any awareness of Shippo.

​
Using Managed Shippo Accounts

In this example you will learn how to do the following. Note: The examples assume you have migrated your Shippo Account to a Platform Account
  1. Create a shippo account for your customer. This is a Shippo Account that you fully manage within your environment and it is opaque to your end customer.
  2. Add a carrier account. This enables the customer’s Shippo Account to request rates and generates labels from that carrier. You must do this for every customer’s Shippo Account.
  3. Create a Shipment and Generate rates.
  4. Purchase a label.

​
Create a Managed Shippo Account for your customer

Request:
Create account request
curl -i -X POST \
  https://api.goshippo.com/shippo-accounts \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "hippo@shippo.com",
    "first_name": "Shippo",
    "last_name": "Meister",
    "company_name": "Acme"
  }'
Response:
Create account response
{
  "email": "hippo@shippo.com",
  "first_name": "Shippo",
  "last_name": "Meister",
  "company_name": "Acme",
  "object_created": "2022-08-24T14:15:22Z",
  "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  "object_updated": "2022-08-24T14:15:22Z"
}
The object_id is the customer’s Shippo Account ID. To make an API call for this account, set this ID in the SHIPPO-ACCOUNT-ID header of the call. In the following example, you will replace <ShippoAccountID> with this object_id.

​
Add a Carrier Account

For every customer’s Managed Shippo Account, you must enable at least one carrier account. When the shipping rates are generated for the customer’s Managed Shippo Account, only rates from enabled carriers are returned. To specify which Managed Shippo Account is being enabled with a carrier, use the object_id of the account in the SHIPPO-ACCOUNT-ID header. You have two options for enabling carrier accounts for your customer. You can use a Shippo carrier account that benefits from rates that Shippo have negotiated or you can use your own account that uses rates that you have agreed with a carrier.

​
Adding a Shippo carrier account

If you want your customers to use a Shippo carrier account, use the Add a Shippo carrier account endpoint. Request:
Add a Shippo carrier account request
curl -L -X POST 'https://api.goshippo.com/carrier_accounts/register/new' \
-H 'Authorization: ShippoToken <API_TOKEN>' \
-H 'Content-Type: application/json' \
-H 'SHIPPO-ACCOUNT-ID: <ShippoAccountID>' \
-d '{
  "carrier": "usps",
  "parameters": {}
}'
Response:
Add a Shippo carrier account response
{
  "account_id": "****",
  "active": true,
  "carrier": "UPS",
  "parameters": {
    "account_number": "94567e",
    "aia_country_iso2": "US",
    "billing_address_city": "San Francisco",
    "billing_address_country_iso2": "US",
    "billing_address_state": "CA",
    "billing_address_street1": "731 Market St",
    "billing_address_street2": "STE 200",
    "billing_address_zip": "94103",
    "collec_country_iso2": "US",
    "collec_zip": "94103",
    "company": "Acme",
    "currency_code": "USD",
    "email": "hippo@shippo.com",
    "full_name": "Shippo Meister",
    "has_invoice": true,
    "invoice_controlid": "1234",
    "invoice_date": "20210529",
    "invoice_number": "1112234",
    "invoice_value": "11.23",
    "phone": "1112223333",
    "title": "Manager",
    "ups_agreements": true
  },
  "is_shippo_account": false,
  "metadata": "string",
  "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  "object_owner": "bob+22@gmail.com",
  "test": false
}

​
Adding your own carrier account

If you have your own carrier account and want your customer’s Managed Shippo Account to use that account, use the Create a new carrier account endpoint. If your user has their own carrier account, you can also choose to add that account for them to use using the same endpoint.
NoteThis step requires you to have your account set up with your preferred carrier. Depending on the carrier you choose, there may be different parameters required to enable that carrier for your Managed Shippo Account. Use our carrier accounts guide to identify which parameters are required for your carrier.
Request:
Add your own carrier account request
curl -L -X POST 'https://api.goshippo.com/carrier_accounts/' \
-H 'Authorization: ShippoToken <API_TOKEN>' \
-H 'Content-Type: application/json' \
-H 'SHIPPO-ACCOUNT-ID: <ShippoAccountID>' \
-d '{
   "carrier": "hermes_uk",
    "account_id": "hermes_account_1",
    "parameters": {
              "hermes_uk_api_user": "user-name",
              "hermes_uk_api_password": "1234qwerty",
              "hermes_uk_client_id": 123,
              "hermes_uk_client_name": "CompanyName",
              "hermes_uk_parcel_shop_api_user": "ABC1234",
              "hermes_uk_parcel_shop_api_password": "12345678"
               },
   "test": false,
   "active": true,
   "is_shippo_account": false,
   "metadata": "EVRi Account",
   "carrier_name": "EVRi"
}'
Response:
Add your own carrier account response
 "carrier": "hermes_uk",
           "object_id": "2edac0dddcfc4416b2708cc10b2d11e0",
           "object_owner": "hippo@shippo.com",
           "account_id": "UNIQUE_ACCOUNT_ID_HERE",
           "parameters": {
               "hermes_uk_api_user": "user-name",
               "hermes_uk_api_password": "1234qwerty",
               "hermes_uk_client_id": 123,
               "hermes_uk_client_name": "CompanyName",
               "hermes_uk_parcel_shop_api_user": "ABC1234",
               "hermes_uk_parcel_shop_api_password": "12345678"
           },
           "test": false,
           "active": true,
           "is_shippo_account": false,
           "metadata": "EVRi Account",
           "carrier_name": "EVRi",
           "carrier_images": {
               "200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/hermes.png",
               "75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/hermes.png"
           }

​
Create a Shipment and generate Rates

To create a Shipment and generate a rate on behalf of a customer’s Managed Shippo Account, add the object_id of the account in the SHIPPO-ACCOUNT-ID key value pair. Request:
Create a Shipment request for a Managed Account
curl https://api.goshippo.com/shipments/  \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"  \
    -H 'SHIPPO-ACCOUNT-ID: <ShippoAccountID>' \
    -d '{
       "address_from":{
          "name":"Mr. Hippo",
          "street1":"215 Clayton St.",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94117",
          "country":"US"
       },
       "address_to":{
          "name":"Mrs. Hippo",
          "street1":"965 Mission St.",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94105",
          "country":"US"
       },
       "parcels":[{
          "length":"5",
          "width":"5",
          "height":"5",
          "distance_unit":"in",
          "weight":"2",
          "mass_unit":"lb"
       }],
       "async": false
    }'
Response:
Create a Shipment for a Managed Account response
{
   {
  "carrier_accounts": [],
  "object_created": "2022-08-24T14:16:22Z",
  "object_updated": "2022-08-24T14:16:22Z",
  "object_id": "76ca5cbfd24f4b2d96f38ea6834985be",
  "object_owner": "shippotle@shippo.com",
  "status": "SUCCESS",
  "address_from": {
    "object_id": "e0d64d09edf846d0bd94dda91b299be9",
    "is_complete": true,
    "name": "Mr. Hippo",
    "company": "",
    "street_no": "",
    "street1": "215 Clayton St.",
    "validation_results": {},
    "street2": "",
    "street3": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "",
    "email": "",
    "is_residential": null,
    "test": true
  },
  "address_to": {
    "object_id": "b2d9219521be4637b5d1baeb70022c33",
    "is_complete": true,
    "name": "Mrs. Hippo",
    "company": "",
    "street_no": "",
    "street1": "965 Mission St.",
    "validation_results": {},
    "street2": "",
    "street3": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US",
    "phone": "",
    "email": "",
    "is_residential": null,
    "test": true
  },
  "parcels": [
    {
      "object_state": "VALID",
      "object_created": "2022-08-24T14:16:22Z",
      "object_updated": "2022-08-24T14:16:22Z",
      "object_id": "8c119bb117934dfea19eac1e90230fa5",
      "object_owner": "shippotle@shippo.com",
      "template": null,
      "extra": {},
      "length": "5.0000",
      "width": "5.0000",
      "height": "5.0000",
      "distance_unit": "in",
      "weight": "2.0000",
      "mass_unit": "lb",
      "value_amount": null,
      "value_currency": null,
      "metadata": "",
      "line_items": [],
      "test": true
    }
  ],
  "shipment_date": "2022-12-15T11:32:41.845Z",
  "address_return": {
    "object_id": "e0d64d09edf846d0bd94dda91b299be9",
    "is_complete": true,
    "name": "Mr. Hippo",
    "company": "",
    "street_no": "",
    "street1": "215 Clayton St.",
    "validation_results": {},
    "street2": "",
    "street3": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "",
    "email": "",
    "is_residential": null,
    "test": true
  },
  "alternate_address_to": null,
  "customs_declaration": null,
  "extra": {},
  "rates": [
    {
    "object_created": "2022-08-24T14:16:22Z",
    "object_id": "eab0f0c5689347439a9b87f2380710e5",
    "object_owner": "shippotle@shippo.com",
    "shipment": "76ca5cbfd24f4b2d96f38ea6834985be",
    "attributes": [ ],
    "amount": "24.30",
    "currency": "USD",
    "amount_local": "24.30",
    "currency_local": "USD",
    "provider": "USPS",
    "provider_image_75": "https://shippo-static.s3.amazonaws.com/providers/75/USPS.png",
    "provider_image_200": "https://shippo-static.s3.amazonaws.com/providers/200/USPS.png",
    "servicelevel": {},
    "estimated_days": 2,
    "arrives_by": null,
    "duration_terms": "Overnight delivery to most U.S. locations.",
    "messages": [ ],
    "carrier_account": "b19e750708384303ac19ca693fe037ce",
    "test": true,
    "zone": "1"
    },
    ...
  ],
  "metadata": "",
  "test": true,
  "order": null
}
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": []
}

​
Purchase a label

Using a selected rate, you can now purchase a label. Request:
Purchase a label for a Managed Account request
curl https://api.goshippo.com/transactions \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H 'SHIPPO-ACCOUNT-ID: <ShippoAccountID>' \
    -d rate="eab0f0c5689347439a9b87f2380710e5"
    -d label_file_type="PDF"
    -d async=false
Response:
Purchase a label for a Managed Account response
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2022-08-24T14:17:22Z",
    "object_updated": "2022-08-24T14:17:22Z",
    "object_id": "2db03e1bc677420a8c56dc77a60e9386",
    "object_owner": "shippotle@shippo.com",
    "test": true,
    "rate": "eab0f0c5689347439a9b87f2380710e5",
    "tracking_number": "92701901755477000000000011",
    "tracking_status": "UNKNOWN",
    "eta": null,
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92701901755477000000000011",
    "label_url": "https://deliver.goshippo.com/2db03e1bc677420a8c56dc77a60e9386.pdf?Expires=1702641466&Signature=dHAPUFOt7qrqQ-cUI2ptZKwO6rdmXQDu0XZS7gaWO9b77Og5O4yYQDaWuQCQ~otPHczkkI-EPPv20jkf3mTfi4oxdHdUX7W4OURzICPWSyDkP~neuNPDp21q5Wnohf5SBxC300NksR~be4Vdg0DygbWS4-aGDN6tQGuTNIWfUrqFuhzY~2DWEdCljt-XDYQLWxOWPD3sh99FaPvqutC2QRtJxmnxQx-A-CZO6XKeP5JNcCiPjc3Ic~3qbrgVdHnEJH6xmtTP6PBxvipsP0sJdZOp7xYAHOlLx4KHEv0Keah0eEy9lEZLfkSoYo6QOLymWf8TAIQplaYPlRY2yhlihw__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ",
    "commercial_invoice_url": null,
    "messages": [ ],
    "order": null,
    "metadata": "Order ID",
    "parcel": "8c119bb117934dfea19eac1e90230fa5",
    "billing": {
    "payments": [ ]
},
    "qr_code_url": null
}
Your Managed Shippo Account has now purchased a shipping label.