# 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](/docs/oauth_integrations/oauth). 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](#create-a-managed-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](#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.](#create-a-shipment-and-generate-rates)
4. [Purchase a label.](#purchase-a-label)


### ![](/assets/step1.14ee6260337a0b326de06f1173e3703f933b52790e666cd390788635d3e7e0a6.9c1bb791.svg) Create a Managed Shippo Account for your customer

**Request:**


```shell
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:**


```json
{
  "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`.

### ![](/assets/step2.37831ee18f1f0290fe49fb6b512319f7a374b18f4063f0302fe35b4afcd9816b.9c1bb791.svg) 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](/docs/carriers/carrieraccounts/#default-carrier-accounts) 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](/shippoapi/public-api/carrier-accounts/registercarrieraccount) endpoint.

**Request:**


```shell
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:**


```json
{
  "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](/shippoapi/public-api/carrier-accounts/createcarrieraccount) 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](/docs/carriers/carrieraccounts) guide to identify which parameters are required for your carrier.

**Request:**


```shell
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:**


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

### ![](/assets/step3.882dd6eb157abc25c1f2895637ba8769f3b55aa52288a40e94bd0d9550a670c5.9c1bb791.svg) 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:**


```
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:**


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

### ![](/assets/step4.3e238973da1bfa25a515a0ceb0fa4ba0aff3b95a0b56ae4973003052290131dd.9c1bb791.svg) Purchase a label

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

**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:**


```
{
    "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.