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