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.
- If you don’t already have one, create a Shippo account .
- 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.
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
- 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.
- 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.
- Create a Shipment and Generate rates.
- Purchase a label.
1. Create a Shippo Account for your customer
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.
{
"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.
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.
{
"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.
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.
"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.
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:
{
{
"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.
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:
{
"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:
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:
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.
- Merchant has been updated to Shippo Accounts .
- Carrier Own Accounts has been updated to Carrier Accounts .
- Carrier Master Accounts has been updated and is now part of Carrier Accounts .
Example
To list all the address stored in a merchant’s account
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>'
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.