Carrier authorization using OAuth

To protect your account security, some carriers (for example UPS) require you to use OAuth to authorize Shippo to perform some actions, like requesting rates or buying labels, on your behalf. This means you must verify your identity before you can start using that carrier account.

This guide is intended for platforms who provide access to shipping services for their merchants. Depending on how you manage your merchants accounts, it may be useful for you to review our Platform accounts guide.

Follow this guide to learn how to connect a carrier to a merchant, especially if the carrier needs OAuth authorization. If you already have an existing carrier account connected to Shippo, you may still need to verify your identity to remain compliant with that carrier's terms and conditions.

Add your carrier

If your merchant has already added a carrier and you are using this guide to update that carrier, continue to (Get your carrier object_id).

To add a new carrier, refer to our Carrier accounts guide. Each carrier can require unique parameters

The following example shows how to connect a UPS account.

curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'SHIPPO-ACCOUNT-ID: <ShippoAccountID>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "account_id": "94567e",
  "active": true,
  "carrier": "ups",
  "metadata": "UPS Account",
  "parameters": {
    "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",
    "company": "Shippo",
    "email": "hippo@shippo.com",
    "full_name": "Mr Hippo",
    "phone": "1112223333",
    "pickup_address_city": "San Francisco",
    "pickup_address_country_iso2": "US",
    "pickup_address_same_as_billing_address": false,
    "pickup_address_state": "CA",
    "pickup_address_street1": "731 Market St",
    "pickup_address_street2": "STE 200",
    "pickup_address_zip": "94103",
    "ups_agreements": true
  },
  "test": false
}'

{
  "account_id": "94567e",
  "active": true,
  "carrier": "ups",
  "parameters": {},
  "carrier_name": "UPS",
  "is_shippo_account": false,
  "metadata": "string",
  "object_id": "6aa34d5f6865448fbb1ee93636e98999",
  "object_owner": "hippo@shippo.com",
  "service_levels": [{}],
  "test": false
}

Review the response and select the object_id of the carrier connected to the account.

Get your carrier object_id

To find the object ID of a carrier account connected to Shippo, following this example.

curl https://api.goshippo.com/carrier_accounts \
 -H "Authorization: ShippoToken <API_TOKEN>" \
 -H "SHIPPO-ACCOUNT-ID: <ShippoAccountID>"

{
  "next": "baseurl?page=3&results=10",
  "previous": "baseurl?page=1&results=10",
  "results": [
        {
            "carrier": "ups",
            "object_id": "6aa34d5f6865448fbb1ee93636e98999",
            "object_owner": "hippo@shippo.com",
            "account_id": "56782",
            "parameters": {},
            "test": true,
            "active": true,
            "is_shippo_account": false,
            "metadata": "",
            "carrier_name": "UPS",
            "carrier_images": {
                "75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
                "200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png"
            }
        }
  ]
}

Review the response and select the object_id of the appropriate carrier connected to your account.

Validate your credentials using OAuth

The Shippo OAuth validation flow directs you to a site to validate your carrier account.

curl "https://api.goshippo.com/carrier_accounts/6aa34d5f6865448fbb1ee93636e98999/signin/initiate?redirect_uri=https://client.example.com/cb&state=SplxlOBeZQQYbYS6WxSbIA" \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "SHIPPO-ACCOUNT-ID: <ShippoAccountID>"

This call is the beginning of the OAuth process.

• The /signin/initiate endpoint redirects your user to the Shippo carrier login page to manage the OAuth process.
• The redirect_uri is the URL we redirect your user to following carrier OAuth. Use this to return your user back to your application.
• Use state in your request to prevent CSRF attacks. The consuming application checks that the same value is returned after the user authorizes Shippo. The state will be returned as a query string of the redirect_uri .

Check your carrier status

You can check the status of a connected carrier at any time using the carrier object_id.

curl https://api.goshippo.com/carrier_accounts/6aa34d5f6865448fbb1ee93636e98999 \
-H "Authorization: ShippoToken <API_TOKEN>"

The response includes object_info that gives insights into the state of a carrier account's authorization. object_info contains authentication that contains two elements.

• type . This is a string that indicates the authentication method used by the account. It can be one of the following.
  • default . Signifying the use of Shippo's standard authentication method.
  • oauth . Indicating that OAuth 2.0 is the authentication method in place for the account.
• status . This is a string that represents the current authentication status of the carrier account. It can be one of the following enum values.
  • authorization_pending . This status signifies that the account is awaiting the initial authorization flow. It indicates that the OAuth process has been initiated but not yet completed.
  • connected . This indicates that the account is authorized and active, with valid OAuth tokens in place. The account can perform API actions without any additional authorization steps required.
  • disconnected .This status means that the authorization has been lost, and the account needs to reconnect. It suggests that the existing OAuth tokens are either expired or invalidated, and the user must start the authorization flow again. Shippo will keep these tokens up-to-date but we could have rare edge cases where the authorization is lost and we must ask users to reconnect.

{
 "object_info": {
   "authentication": {
     "type": "oauth",
     "status": "connected"
   }
 }
}