Using your Platform Account

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

Note

This 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

Create account requestCreate account response
Copy
Copied
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"
  }'
Copy
Copied
{
  "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.

Add a Shippo carrier account requestAdd a Shippo carrier account response
Copy
Copied
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": {}
}'
Copy
Copied
{
  "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.

Note

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

Add your own carrier account requestAdd your own carrier account response
Copy
Copied
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"
}'
Copy
Copied
 "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.

Create a Shipment request for a Managed AccountCreate a Shipment for a Managed Account response
Copy
Copied
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
    }'
Copy
Copied
{
   {
  "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.

Purchase a label for a Managed Account requestPurchase a label for a Managed Account response
Copy
Copied
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
Copy
Copied
{
    "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.