Guides
/
Carriers
/
List Carriers
Last updated

List Carriers

The /v2/carriers endpoint can return a lot of useful information about the carriers available to your account. The most important of which is the carrier_id. Each of your carriers has a unique carrier_id, which you'll use to specify the carrier account for many commonly used endpoints.

For example, when purchasing a label, you'll explicitly specify the carrier_id for the account the label should come from. Similarly, when rate shopping, you may want to specify the carrier_id of the account that you know has the best rates for the type of package you are shipping.

You can also use this endpoint in a few different ways, depending on what you need:

  • List Carriers: Returns a list of all your available carriers and their details (including carrier_id, carrier_code, account_number), a list of all the carriers’ available services and their attributes, a list of the carriers’ available package types and their attributes, and a list of all the carriers’ available options.
  • Get a single carrier: Returns a list of services, package types, and options for the specified carrier_id.
  • List Carrier Services: Returns a list of services and service attributes for the specified carrier_id.
  • List Carrier Package Types: Returns a list of available package types for the specified carrier_id.
  • List Carrier Options: Returns a list of the available advanced options for a specified carrier_id. Advanced options include the ability to ship alcohol or dangerous goods, bill to a third-party account, and much more.

Requirements

  • You’ll need the carrier_id for all except the List Carriers call.

List Carriers: Sample Request

GET /v2/carriers/

GET /v2/carriers HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

Depending on how many carriers you have connected to your account, the response can be quite long, as it includes all services, package types, and options available for each carrier. This sample response is truncated to a single carrier with its package types and options (in this case, no options are available for this carrier).

{
 "carriers": [
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "account_number": null,
     "requires_funded_amount": true,
     "balance": 0.0,
     "nickname": "Free",
     "friendly_name": "Stamps.com",
     "primary": true,
     "has_multi_package_supporting_services": false,
     "services": [
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_first_class_mail",
         "name": "USPS First Class Mail",
         "domestic": true,
         "international": false,
         "is_multi_package_supported": false
       },
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_media_mail",
         "name": "USPS Media Mail",
         "domestic": true,
         "international": false,
         "is_multi_package_supported": false
       },
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_parcel_select",
         "name": "USPS Parcel Select Ground",
         "domestic": true,
         "international": false,
         "is_multi_package_supported": false
       },
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_priority_mail",
         "name": "USPS Priority Mail",
         "domestic": true,
         "international": false,
         "is_multi_package_supported": false
       },
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_priority_mail_express",
         "name": "USPS Priority Mail Express",
         "domestic": true,
         "international": false,
         "is_multi_package_supported": false
       },
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_first_class_mail_international",
         "name": "USPS First Class Mail Intl",
         "domestic": false,
         "international": true,
         "is_multi_package_supported": false
       },
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_priority_mail_international",
         "name": "USPS Priority Mail Intl",
         "domestic": false,
         "international": true,
         "is_multi_package_supported": false
       },
       {
         "carrier_id": "se-123890",
         "carrier_code": "stamps_com",
         "service_code": "usps_priority_mail_express_international",
         "name": "USPS Priority Mail Express Intl",
         "domestic": false,
         "international": true,
         "is_multi_package_supported": false
       }
     ],
     "packages": [
       {
         "package_id": null,
         "package_code": "flat_rate_envelope",
         "name": "Flat Rate Envelope",
         "description": "USPS flat rate envelope. A special cardboard envelope provided by the USPS that clearly indicates Flat Rate."
       },
       {
         "package_id": null,
         "package_code": "flat_rate_legal_envelope",
         "name": "Flat Rate Legal Envelope",
         "description": "Flat Rate Legal Envelope"
       },
       {
         "package_id": null,
         "package_code": "flat_rate_padded_envelope",
         "name": "Flat Rate Padded Envelope",
         "description": "Flat Rate Padded Envelope"
       },
       {
         "package_id": null,
         "package_code": "large_envelope_or_flat",
         "name": "Large Envelope or Flat",
         "description": "Large envelope or flat. Has one dimension that is between 11 1/2 and 15 long, 6 1/18 and 12 high, or 1/4 and 3/4 thick."
       },
       {
         "package_id": null,
         "package_code": "large_flat_rate_box",
         "name": "Large Flat Rate Box",
         "description": "Large Flat Rate Box"
       },
       {
         "package_id": null,
         "package_code": "large_package",
         "name": "Large Package (any side > 12)",
         "description": "Large package. Longest side plus the distance around the thickest part is over 84 and less than or equal to 108."
       },
       {
         "package_id": null,
         "package_code": "letter",
         "name": "Letter",
         "description": "Letter"
       },
       {
         "package_id": null,
         "package_code": "medium_flat_rate_box",
         "name": "Medium Flat Rate Box",
         "description": "USPS flat rate box. A special 11 x 8 1/2 x 5 1/2 or 14 x 3.5 x 12 USPS box that clearly indicates Flat Rate Box"
       },
       {
         "package_id": null,
         "package_code": "package",
         "name": "Package",
         "description": "Package. Longest side plus the distance around the thickest part is less than or equal to 84"
       },
       {
         "package_id": null,
         "package_code": "small_flat_rate_box",
         "name": "Small Flat Rate Box",
         "description": "Small Flat Rate Box"
       },
       {
         "package_id": null,
         "package_code": "thick_envelope",
         "name": "Thick Envelope",
         "description": "Thick envelope. Envelopes or flats greater than 3/4 at the thickest point."
       }
     ],
     "options": []
   }
 ],
 "request_id": "fd27e4f2-4dfb-4963-ad46-e6b4f1658439",
 "errors": []
}

Get a Single Carrier: Sample Request

GET /v2/carriers/:carrier_id

GET /v2/carriers/se-123890 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "carrier_id": "se-123890",
 "carrier_code": "stamps_com",
 "account_number": null,
 "requires_funded_amount": true,
 "balance": 0.0,
 "nickname": "Free",
 "friendly_name": "Stamps.com",
 "primary": true,
 "services": [
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_first_class_mail",
     "name": "USPS First Class Mail",
     "domestic": true,
     "international": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_media_mail",
     "name": "USPS Media Mail",
     "domestic": true,
     "international": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_parcel_select",
     "name": "USPS Parcel Select Ground",
     "domestic": true,
     "international": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail",
     "name": "USPS Priority Mail",
     "domestic": true,
     "international": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail_express",
     "name": "USPS Priority Mail Express",
     "domestic": true,
     "international": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_first_class_mail_international",
     "name": "USPS First Class Mail Intl",
     "domestic": false,
     "international": true
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail_international",
     "name": "USPS Priority Mail Intl",
     "domestic": false,
     "international": true
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail_express_international",
     "name": "USPS Priority Mail Express Intl",
     "domestic": false,
     "international": true
   }
 ],
 "packages": [
   {
     "package_id": null,
     "package_code": "flat_rate_envelope",
     "name": "Flat Rate Envelope",
     "description": "USPS flat rate envelope. A special cardboard envelope provided by the USPS that clearly indicates \"Flat Rate\"."
   },
   {
     "package_id": null,
     "package_code": "flat_rate_legal_envelope",
     "name": "Flat Rate Legal Envelope",
     "description": "Flat Rate Legal Envelope"
   },
   {
     "package_id": null,
     "package_code": "flat_rate_padded_envelope",
     "name": "Flat Rate Padded Envelope",
     "description": "Flat Rate Padded Envelope"
   },
   {
     "package_id": null,
     "package_code": "large_envelope_or_flat",
     "name": "Large Envelope or Flat",
     "description": "Large envelope or flat. Has one dimension that is between 11 1/2 and 15 long, 6 1/18 and 12 high, or 1/4 and 3/4 thick."
   },
   {
     "package_id": null,
     "package_code": "large_flat_rate_box",
     "name": "Large Flat Rate Box",
     "description": "Large Flat Rate Box"
   },
   {
     "package_id": null,
     "package_code": "large_package",
     "name": "Large Package (any side > 12)",
     "description": "Large package. Longest side plus the distance around the thickest part is over 84 and less than or equal to 108."
   },
   {
     "package_id": null,
     "package_code": "letter",
     "name": "Letter",
     "description": "Letter"
   },
   {
     "package_id": null,
     "package_code": "medium_flat_rate_box",
     "name": "Medium Flat Rate Box",
     "description": "USPS flat rate box. A special 11 x 8 1/2 x 5 1/2 or 14 x 3.5 x 12 USPS box that clearly indicates \"Flat Rate Box\""
   },
   {
     "package_id": null,
     "package_code": "package",
     "name": "Package",
     "description": "Package. Longest side plus the distance around the thickest part is less than or equal to 84"
   },
   {
     "package_id": null,
     "package_code": "small_flat_rate_box",
     "name": "Small Flat Rate Box",
     "description": "Small Flat Rate Box"
   },
   {
     "package_id": null,
     "package_code": "thick_envelope",
     "name": "Thick Envelope",
     "description": "Thick envelope. Envelopes or flats greater than 3/4 at the thickest point."
   }
 ],
 "options": []
}

List Carrier Services: Sample Request

GET /v2/carriers/:carrier_id/services

GET /v2/carriers/se-123890/services HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "services": [
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_first_class_mail",
     "name": "USPS First Class Mail",
     "domestic": true,
     "international": false,
     "is_multi_package_supported": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_media_mail",
     "name": "USPS Media Mail",
     "domestic": true,
     "international": false,
     "is_multi_package_supported": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_parcel_select",
     "name": "USPS Parcel Select Ground",
     "domestic": true,
     "international": false,
     "is_multi_package_supported": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail",
     "name": "USPS Priority Mail",
     "domestic": true,
     "international": false,
     "is_multi_package_supported": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail_express",
     "name": "USPS Priority Mail Express",
     "domestic": true,
     "international": false,
     "is_multi_package_supported": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_first_class_mail_international",
     "name": "USPS First Class Mail Intl",
     "domestic": false,
     "international": true,
     "is_multi_package_supported": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail_international",
     "name": "USPS Priority Mail Intl",
     "domestic": false,
     "international": true,
     "is_multi_package_supported": false
   },
   {
     "carrier_id": "se-123890",
     "carrier_code": "stamps_com",
     "service_code": "usps_priority_mail_express_international",
     "name": "USPS Priority Mail Express Intl",
     "domestic": false,
     "international": true,
     "is_multi_package_supported": false
   }
 ]
}

List Carrier Package Types: Sample Request

GET /v2/carriers/:carrier_id/packages

GET /v2/carriers/se-123890/packages HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "packages": [
   {
     "package_id": null,
     "package_code": "flat_rate_envelope",
     "name": "Flat Rate Envelope",
     "description": "USPS flat rate envelope. A special cardboard envelope provided by the USPS that clearly indicates \"Flat Rate\"."
   },
   {
     "package_id": null,
     "package_code": "flat_rate_legal_envelope",
     "name": "Flat Rate Legal Envelope",
     "description": "Flat Rate Legal Envelope"
   },
   {
     "package_id": null,
     "package_code": "flat_rate_padded_envelope",
     "name": "Flat Rate Padded Envelope",
     "description": "Flat Rate Padded Envelope"
   },
   {
     "package_id": null,
     "package_code": "large_envelope_or_flat",
     "name": "Large Envelope or Flat",
     "description": "Large envelope or flat. Has one dimension that is between 11 1/2 and 15 long, 6 1/18 and 12 high, or 1/4 and 3/4 thick."
   },
   {
     "package_id": null,
     "package_code": "large_flat_rate_box",
     "name": "Large Flat Rate Box",
     "description": "Large Flat Rate Box"
   },
   {
     "package_id": null,
     "package_code": "large_package",
     "name": "Large Package (any side > 12)",
     "description": "Large package. Longest side plus the distance around the thickest part is over 84 and less than or equal to 108."
   },
   {
     "package_id": null,
     "package_code": "letter",
     "name": "Letter",
     "description": "Letter"
   },
   {
     "package_id": null,
     "package_code": "medium_flat_rate_box",
     "name": "Medium Flat Rate Box",
     "description": "USPS flat rate box. A special 11 x 8 1/2 x 5 1/2 or 14 x 3.5 x 12 USPS box that clearly indicates Flat Rate Box"
   },
   {
     "package_id": null,
     "package_code": "package",
     "name": "Package",
     "description": "Package. Longest side plus the distance around the thickest part is less than or equal to 84"
   },
   {
     "package_id": null,
     "package_code": "small_flat_rate_box",
     "name": "Small Flat Rate Box",
     "description": "Small Flat Rate Box"
   },
   {
     "package_id": null,
     "package_code": "thick_envelope",
     "name": "Thick Envelope",
     "description": "Thick envelope. Envelopes or flats greater than 3/4 at the thickest point."
   }
 ]
}

List Carrier Options: Sample Request

This example uses UPS as the carrier since UPS offers a wide variety (but not an exhaustive list) of potential advanced options.

GET /v2/carriers/:carrier_id/options

GET /v2/carriers/se-123890/options HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "options": [
   {
     "name": "bill_to_account",
     "default_value": "",
     "description": ""
   },
   {
     "name": "bill_to_country_code",
     "default_value": "",
     "description": ""
   },
   {
     "name": "bill_to_party",
     "default_value": "",
     "description": ""
   },
   {
     "name": "bill_to_postal_code",
     "default_value": "",
     "description": ""
   },
   {
     "name": "contains_alcohol",
     "default_value": "false",
     "description": ""
   },
   {
     "name": "non_machinable",
     "default_value": "false",
     "description": ""
   },
   {
     "name": "saturday_delivery",
     "default_value": "false",
     "description": ""
   },
   {
     "name": "delivered_duty_paid",
     "default_value": "false",
     "description": ""
   }
 ]
}
Previous page
Next page