Platform Accounts

What is a Platform Account?

Marketplaces, e-commerce platforms, and third-party logistics providers often want to offer built-in shipping functionality to their customers. They may also need to track shipping data on a per-customer basis. Without a Platform Account, managing this process can require complex mapping and logic within your code.

A Platform Account allows you to customize the shipping capabilities that are offered to your customers by allowing you to configure headless Managed Shippo Accounts for each customer.

What are Managed Shippo Accounts?

Managed Shippo Accounts are headless accounts (they do not have a Shippo website login) that represent your customers. You own your Managed Shippo Accounts and interact with them only through the Shippo API. Managed Shippo Accounts are opaque to your end customers, meaning they don’t need to create their own Shippo login or have a billing relationship with Shippo. Using Managed Shippo Accounts, you can control shipping settings for your customers while the shipping experience for your end users remains native and seamless.

Administering your customers as Managed Shippo Accounts allows you to do the following.

  • Customize multiple customers settings behind the scenes that simplifies managing customers at scale . For example, setting up specific carrier accounts to be used for each customer.
  • Accurately report on each customer’s activity. For example, obtaining each customer’s associated shipments and other relevant data.
Note

Do not use Managed Shippo Accounts if you want your customers to self-manage their shipping settings on Shippo or have a direct billing relationship with Shippo. Instead, you should consider using an OAuth integration for a co-branded experience.

Upgrade your account

To start using Managed Shippo Accounts, you must convert your existing Shippo Account to a Platform Account. Follow these steps.

  1. If you don’t already have one, create a Shippo account .
  2. Contact our partnership support team to guide you through the process of setting up your Platform Account.

When your account has been upgraded, you can begin using Managed Shippo Accounts.

note

Managed Shippo Accounts do NOT automatically inherit access to carriers from your Platform account. To give your Managed Shippo Accounts access to a carrier, you must add a carrier account to each Managed Account individually. You must do this for each carrier you want your Platform account to have access to.

Flow diagram showing how Shippo accounts are upgrade to platform accounts to control shippo managed accounts

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.

1. Create a Shippo Account for your customer

Copy
Copied
curl -i -X POST \
  https://api.goshippo.com/shippo-accounts \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'SHIPPO-API-VERSION: string' \
  -d '{
    "email": "hippo@shippo.com",
    "first_name": "Shippo",
    "last_name": "Meister",
    "company_name": "Acme"
  }'

A successful response will look like this.

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.

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

Copy
Copied
curl --location --request POST '/carrier_accounts/register/new' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
–-header 'SHIPPO-API-VERSION: string' \
--header 'SHIPPO-ACCOUNT-ID: adcfdddf8ec64b84ad22772bce3ea37a' \
--data-raw '{
{
  "carrier": "usps",
  "parameters": {}
}
}'

A successful response will look like this.

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.

Copy
Copied
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken shippo_live_******' \
--header 'Content-Type: application/json' \
–-header 'SHIPPO-API-VERSION: string' \
--header 'SHIPPO-ACCOUNT-ID: adcfdddf8ec64b84ad22772bce3ea37a' \
--data-raw '{
   "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,   //true if test account
   "active": true,
   "is_shippo_account": false,
   "metadata": "EVRi Account",
   "carrier_name": "EVRi"
}'

A successful response will look like this.

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"
           }

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

Copy
Copied
curl https://api.goshippo.com/shipments/  \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"  \
    -H 'SHIPPO-ACCOUNT-ID: adcfdddf8ec64b84ad22772bce3ea37a' \
    -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
    }'

A successful response will look like this:

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": []
}

4. Purchase a label

Using a selected rate, you can now purchase a label.

Copy
Copied
curl https://api.goshippo.com/transactions \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H 'SHIPPO-ACCOUNT-ID: adcfdddf8ec64b84ad22772bce3ea37a' \
    -d rate="eab0f0c5689347439a9b87f2380710e5"
    -d label_file_type="PDF"
    -d async=false

A successful response will look like this:

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.

Migrating from Platform API to Shippo API

If you already use the Shippo for Platforms API to support your merchants, you may choose to update your integration to take advantage of the Shippo API. Follow this guide to learn how.

1. Change your Base URL

Previously, Shippo for Platforms used the base URL https://platform-api.goshippo.com. To use the Shippo API, change your base URL to https://api.goshippo.com/.

2. Reference Merchants using a header, not a parameter

Previously, you referenced merchants using a parameter, for example:

Copy
Copied
curl https://platform-api.goshippo.com/merchants/{MerchantId}/addresses/

where {MerchantId} is the object ID of your merchant.

To use Managed Shippo Accounts in the Shippo API, you reference your Managed Account merchant using a header element. For example:

Copy
Copied
curl https://api.goshippo.com/addresses/ -H 'SHIPPO-ACCOUNT-ID: adcfdddf8ec64b84ad22772bce3ea37a'

where SHIPPO-ACCOUNT-ID is the object ID of your Managed Account merchant.

3. Renamed endpoints

The following endpoints have changed. Follow the examples in our reference documentation to update your integration.

Example

To list all the address stored in a merchant’s account

Shippo APIPlatform API
Copy
Copied
curl https://api.goshippo.com/addresses/ \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'SHIPPO-API-VERSION: string' \
  -H 'SHIPPO-ACCOUNT-ID: <MANAGED_ACCOUNT_ID>'
Copy
Copied
curl https://platform-api.goshippo.com/merchants/{MerchantId}/addresses/ \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'SHIPPO-API-VERSION: string'
Note

You do not need to migrate any data from your existing Platforms account.