# Carrier Metadata

The Carrier Metadata endpoint returns information about all the carriers available on the EasyPost platform.
This information may include service levels, predefined packages, shipment options, supported features, and more that are available per carrier.
This metadata can be useful during onboarding and integration or when determining the ideal carrier mix for your setup.

---

## CarrierMetadata object

| Property | Type | Description |
|----------|------|-------------|
| name | string | The single-word name of a carrier, such as "royalmail" (these may not match the human-readable name) |
| human_readable | string | The human-readable name of the carrier (helps describe what kind of entry this is) |
| type | string | The CarrierAccount type associated with this carrier (some carriers may have multiple entries that share a type - Wallet vs BYOCA) |
| service_levels | array | A list of ServiceLevel objects for this carrier |
| predefined_packages | array | A list of PredefinedPackage objects for this carrier |
| supported_features | array | A list of SupportedFeature objects for this carrier |
| shipment_options | array | A list of ShipmentOption objects for this carrier |

Example Object:

```json
{
  "human_readable": "USPS BYOCA",
  "name": "uspsbyoca",
  "predefined_packages": [
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "6in x 4.5in x 0.016in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "Card"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "11.5in x 6.125in x 0.25in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "Letter"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "11.5in x 6.125in x 0.75in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "Flat"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "12.5in x 9.5in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "FlatRateEnvelope"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "15in x 9.5in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "FlatRateLegalEnvelope"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "12.5in x 9.5in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "FlatRatePaddedEnvelope"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "10in x 5in",
        "12.5in x 9.5in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "FlatRateWindowEnvelope"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "12.5in x 9.5in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "FlatRateCardboardEnvelope"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "10in x 6in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "SmallFlatRateEnvelope"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "Varies based on service level"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "Parcel"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "Varies based on service level"
      ],
      "human_readable": null,
      "max_weight": 320,
      "name": "SoftPack"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "8.6875in x 5.4375in x 1.75in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "SmallFlatRateBox"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "11.25in x 8.75in x 6in",
        "14.125in x 12in x 3.5in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "MediumFlatRateBox"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "12.25in x 12in x 6in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "LargeFlatRateBox"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "12.25in x 12.25in x 6in"
      ],
      "human_readable": null,
      "max_weight": null,
      "name": "LargeFlatRateBoxAPOFPO"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [],
      "human_readable": null,
      "max_weight": null,
      "name": "FlatTubTrayBox"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [],
      "human_readable": null,
      "max_weight": null,
      "name": "EMMTrayBox"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [],
      "human_readable": null,
      "max_weight": null,
      "name": "FullTrayBox"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [],
      "human_readable": null,
      "max_weight": null,
      "name": "HalfTrayBox"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [],
      "human_readable": null,
      "max_weight": null,
      "name": "PMODSack"
    }
  ],
  "service_levels": [
    {
      "carrier": "uspsbyoca",
      "description": "1-5 business days",
      "dimensions": [
        "Cards, Letters and Flats only (no Parcels)",
        "See Predefined Packages (Card, Letter, Flat) for details"
      ],
      "human_readable": "First-Class Mail®",
      "max_weight": 13,
      "name": "First"
    },
    {
      "carrier": "uspsbyoca",
      "description": "1-3 business days",
      "dimensions": [
        "Combined Length and Girth < 108in"
      ],
      "human_readable": "Priority Mail®",
      "max_weight": 1120,
      "name": "Priority"
    },
    {
      "carrier": "uspsbyoca",
      "description": "1-2 days",
      "dimensions": [
        "Combined Length and Girth < 108in"
      ],
      "human_readable": "Priority Mail Express®",
      "max_weight": 1120,
      "name": "Express"
    },
    {
      "carrier": "uspsbyoca",
      "description": "2-5 days",
      "dimensions": [
        "Combined Length and Girth < 130in"
      ],
      "human_readable": "USPS Ground Advantage®",
      "max_weight": 1120,
      "name": "GroundAdvantage"
    },
    {
      "carrier": "uspsbyoca",
      "description": "2-8 business days",
      "dimensions": [
        "Combined Length and Girth < 108in"
      ],
      "human_readable": "Library Mail®",
      "max_weight": 1120,
      "name": "LibraryMail"
    },
    {
      "carrier": "uspsbyoca",
      "description": "2-8 business days",
      "dimensions": [
        "Combined Length and Girth < 108in"
      ],
      "human_readable": "Media Mail®",
      "max_weight": 1120,
      "name": "MediaMail"
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "dimensions": [
        "Must be rectangular, otherwise an additional charge may apply."
      ],
      "human_readable": "First-Class Mail International®",
      "max_weight": 15.994,
      "name": "FirstClassMailInternational"
    },
    {
      "carrier": "uspsbyoca",
      "description": "7-21 days",
      "dimensions": [
        "Packages (Other Than Rolls): Combined Length and Girth < 108in",
        "Rolls (Tubes): Length: min 4in; max 36 in. Length plus twice the diameter (combined): min 6.75 in; max 42in.",
        "Some countries have specific prohibitions and restrictions"
      ],
      "human_readable": "First-Class Package International Service®",
      "max_weight": 64,
      "name": "FirstClassPackageInternationalService"
    },
    {
      "carrier": "uspsbyoca",
      "description": "6-10 business days",
      "dimensions": [
        "Combined Length and Girth < 108in"
      ],
      "human_readable": "Priority Mail International®",
      "max_weight": 1120,
      "name": "PriorityMailInternational"
    },
    {
      "carrier": "uspsbyoca",
      "description": "3-5 business days",
      "dimensions": [
        "Combined Length and Girth < 108in"
      ],
      "human_readable": "Priority Mail Express International®",
      "max_weight": 1120,
      "name": "ExpressMailInternational"
    }
  ],
  "shipment_options": [
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Additional Handling",
      "name": "additional_handling",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Auto Manifest",
      "name": "auto_manifest",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Carrier Insurance Amount",
      "name": "carrier_insurance_amount",
      "type": "float"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Certificate Number",
      "name": "certificate_number",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Certified Mail",
      "name": "certified_mail",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Container",
      "name": "container",
      "type": "map"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Content Description",
      "name": "content_description",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Currency",
      "name": "currency",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Customs Include Shipping",
      "name": "customs_include_shipping",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Dangerous Goods",
      "name": "dangerous_goods",
      "type": "map"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Delivery Confirmation",
      "name": "delivery_confirmation",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Delivery Date",
      "name": "delivery_date",
      "type": "datetime"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Delivery Max Datetime",
      "name": "delivery_max_datetime",
      "type": "datetime"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Delivery Min Datetime",
      "name": "delivery_min_datetime",
      "type": "datetime"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Entry",
      "name": "entry",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Handling Instructions",
      "name": "handling_instructions",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Hazmat",
      "name": "hazmat",
      "type": "enum"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Image Format",
      "name": "image_format",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Import Control Description",
      "name": "import_control_description",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Import Control",
      "name": "import_control",
      "type": "enum"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Import Federal Tax Id",
      "name": "import_federal_tax_id",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Importer Reference",
      "name": "importer_reference",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Invoice Number",
      "name": "invoice_number",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Label Date",
      "name": "label_date",
      "type": "datetime"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Label Format",
      "name": "label_format",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Label Size",
      "name": "label_size",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "License Number",
      "name": "license_number",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Live Animal",
      "name": "live_animal",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Machinable",
      "name": "machinable",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Po Sort",
      "name": "po_sort",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Print Custom",
      "name": "print_custom",
      "type": "array"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Registered Mail Amount",
      "name": "registered_mail_amount",
      "type": "float"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Registered Mail",
      "name": "registered_mail",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Return Receipt",
      "name": "return_receipt",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Return Service",
      "name": "return_service",
      "type": "string"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Saturday Delivery",
      "name": "saturday_delivery",
      "type": "boolean"
    },
    {
      "carrier": "uspsbyoca",
      "deprecated": false,
      "description": null,
      "human_readable": "Special Rates Eligibility",
      "name": "special_rates_eligibility",
      "type": "string"
    }
  ],
  "supported_features": [
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "bill_on_delivery",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "bill_on_label_purchase",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "commercial_invoices",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "delivers_to_po_box",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "labels",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "pickups",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "rating",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "refunds",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "returns",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "scanforms",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "test_environment",
      "supported": true
    },
    {
      "carrier": "uspsbyoca",
      "description": null,
      "name": "tracking",
      "supported": true
    }
  ],
  "type": "UspsAccount"
}
```

---

## ServiceLevel object

| Property | Type | Description |
|----------|------|-------------|
| carrier | string | The single-word name of the carrier |
| name | string | The service level name used by EasyPost |
| description | string | A description of the service level, or null |
| human_readable | string | The human-readable name of the service level, or null |
| max_weight | float | The maximum weight in ounces, or null |
| dimensions | array | Dimension requirements or limits, as strings, or null |

Example Object:

```json
{
  "carrier": "uspsbyoca",
  "description": "1-5 business days",
  "dimensions": [
    "Cards, Letters and Flats only (no Parcels)",
    "See Predefined Packages (Card, Letter, Flat) for details"
  ],
  "human_readable": "First-Class Mail®",
  "max_weight": 13,
  "name": "First"
}
```

---

## PredefinedPackage object

| Property | Type | Description |
|----------|------|-------------|
| carrier | string | The single-word name of the carrier |
| name | string | The predefined package name used by EasyPost |
| description | string | A description of the predefined package, or null |
| human_readable | string | The human-readable name of the predefined package, or null |
| max_weight | float | The maximum weight in ounces, or null |
| dimensions | array | Available package dimensions, as strings, or null |

Example Object:

```json
{
  "carrier": "uspsbyoca",
  "description": null,
  "dimensions": [
    "6in x 4.5in x 0.016in"
  ],
  "human_readable": null,
  "max_weight": null,
  "name": "Card"
}
```

---

## SupportedFeature object

| Property | Type | Description |
|----------|------|-------------|
| carrier | string | The single-word name of the carrier |
| name | string | The name of the carrier feature |
| supported | boolean | Whether the feature is supported, or null |
| description | string | A description of the feature, or null |

Example Object:

```json
{
  "carrier": "uspsbyoca",
  "description": null,
  "name": "bill_on_delivery",
  "supported": true
}
```

---

## ShipmentOption object

| Property | Type | Description |
|----------|------|-------------|
| carrier | string | The single-word name of the carrier |
| name | string | The shipment option name used by EasyPost |
| description | string | A description of the shipment option, or null |
| human_readable | string | The human-readable name of the shipment option, or null |
| deprecated | boolean | Whether the shipment option is deprecated, or null |
| type | string | The shipment option value type, or null |

Example Object:

```json
{
  "carrier": "uspsbyoca",
  "deprecated": false,
  "description": null,
  "human_readable": "Additional Handling",
  "name": "additional_handling",
  "type": "boolean"
}
```

---

## Retrieve Carrier Metadata

### Example: GET /metadata/carriers

#### cURL

```shell
# Request all metadata for all carriers
curl -X GET https://api.easypost.com/v2/metadata/carriers \
  -u "EASYPOST_API_KEY":

# Request specific metadata for specific carriers
curl -X GET "https://api.easypost.com/v2/metadata/carriers?carriers=usps&types=service_levels,predefined_packages" \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func retrieve() {
	client := easypost.New("EASYPOST_API_KEY")

	// Request all metadata for all carriers
	carrierMetadata, _ := client.GetCarrierMetadata()
	fmt.Println(carrierMetadata)

	// Request specific metadata for specific carriers
	carrierMetadataWithFilters, _ := client.GetCarrierMetadataWithCarriersAndTypes([]string{"usps"}, []string{"service_levels", "predefined_packages"})
	fmt.Println(carrierMetadataWithFilters)
}
```

#### Java

```java
package carrier_metadata;

import com.easypost.exception.EasyPostException;
import com.easypost.model.CarrierAccount;
import com.easypost.service.EasyPostClient;

import java.util.ArrayList;
import java.util.List;

public class Retrieve {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        // Request all metadata for all carriers
        CarrierAccount carrierMetadata = client.carrierMetadata.retrieve();
        System.out.println(carrierMetadata);

        // Request specific metadata for specific carriers
        List<String> carriers = new ArrayList<String>();
        carriers.add("usps");

        List<String> types = new ArrayList<String>();
        types.add("service_levels");
        types.add("predefined_packages");

        CarrierAccount carrierMetadata = client.carrierMetadata.retrieve(carriers, types);
        System.out.println(carrierMetadata);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            // Request all metadata for all carriers
            List<EasyPost.Models.API.Carrier> carrierMetadata = await client.CarrierMetadata.Retrieve();
            Console.WriteLine(JsonConvert.SerializeObject(carrierMetadata, Formatting.Indented));

            // Request specific metadata for specific carriers
            EasyPost.Parameters.CarrierMetadata.Retrieve parameters = new()
            {
                Carriers = new List<string> { "UPS", "USPS" },
                Types = new List<EasyPost.Models.API.CarrierMetadataType> { CarrierMetadataType.ServiceLevels, CarrierMetadataType.PredefinedPackages },
            };

            List<EasyPost.Models.API.Carrier> carrierMetadata = await client.CarrierMetadata.Retrieve(parameters);
            Console.WriteLine(JsonConvert.SerializeObject(carrierMetadata, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostBetaClient = require('@easypost/api');

const client = new EasyPostBetaClient('EASYPOST_API_KEY');

(async () => {
  // Request all metadata for all carriers
  const carrierMetadata = await client.CarrierMetadata.retrieve();
  console.log(carrierMetadata);

  // Request specific metadata for specific carriers
  const carrierMetadataWithFilters = await client.CarrierMetadata.retrieve(
    ['usps'],
    ['service_levels', 'predefined_packages'],
  );
  console.log(carrierMetadataWithFilters);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

// Request all metadata for all carriers
$carrierMetadata = $client->carrierMetadata->retrieve();
echo $carrierMetadata;

// Request specific metadata for specific carriers
$carrierMetadata = $client->carrierMetadata->retrieve(
    ['usps'],
    ['service_levels', 'predefined_packages'],
);
echo $carrierMetadata;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

# Request all metadata for all carriers
carrier_metadata = client.carrier_metadata.retrieve()
print(carrier_metadata)

# Request specific metadata for specific carriers
carrier_metadata = client.carrier_metadata.retrieve(
    carriers=["usps"],
    types=["service_levels", "predefined_packages"],
)
print(carrier_metadata)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

# Request all metadata for all carriers
carrier_metadata = client.carrier_metadata.retrieve
puts carrier_metadata

# Request specific metadata for specific carriers
usps_carrier_metadata = client.carrier_metadata.retrieve('usps', %w[service_levels predefined_packages])
puts usps_carrier_metadata
```

Retrieve all `CarrierMetadata` for all carriers on the EasyPost platform.
Optionally, filter the response by specifying a list of carriers or metadata types.